Annotation Management & Reconciliation¶
Overview¶
This is the index document for a multi-feature initiative to modernise SyRF's annotation system. The initiative covers eight features designed together to ensure architectural coherence.
Discussion: GitHub Discussion #1953
Feature Specifications¶
Each feature has a standalone specification document following a consistent template:
| Feature | Description | Audience |
|---|---|---|
| Annotation Versioning | Foundational Identity + Immutable Versions pattern for AQ, QS, Annotation, and Session entities | PO + Dev |
| Question Management | Draft question creation, stage assignment, activation lifecycle, version history, admin decision framework | PO + Dev |
| Annotation Form V2 | Rebuilt signal-forms-based annotation form with virtual scroll, per-question auto-save, and session versioning | PO + Dev |
| Reconciliation | Authority determination, random pool assignment, blinded comparison, bulk approve, agreement metrics | PO + Dev |
| Stage Settings | Per-stage configuration: mode selection, reviewer policies, session targets, reconciliation settings | PO + Dev |
| Stage Filtering | Configurable stage-scoped study pools via Filter Sets with MongoDB compilation | PO + Dev |
| Screening Profiles | Named, reusable screening criteria configurations enabling multi-stage pipelines | PO + Dev |
| Screening Annotations | Structured exclusion reasons coupled to screening decisions for PRISMA compliance | PO + Dev |
Cross-Cutting Documents¶
| Document | Purpose |
|---|---|
| Product Overview | Non-technical summary for product owners and stakeholders |
| Design Decisions | Authoritative reference for all 50 design decisions (D1-D50) |
| Annotation Versioning Design | Design refinements D37-D50 (supersedes design-decisions.md where they conflict) |
Delivery Roadmap¶
The initiative is delivered across 9 phases. See .planning/ROADMAP.md for the full roadmap with success criteria and dependency graph.
| Phase | Name | Status |
|---|---|---|
| 1 | Spec Resolution & API Verification | Complete |
| 2 | Collection Infrastructure | Not started |
| 3 | Question Lifecycle | Not started |
| 4 | Annotation Form v2 | Not started |
| 5 | Question Management UI | Not started |
| 6 | Reconciliation Model & Authority | Not started |
| 7 | Data Migration & Rollout | Not started |
| 8 | Reconciliation Workflow & UI | Not started |
| 9 | Data Export | Not started |
Phases 4, 5, and 6 can execute in parallel after Phase 3. Phase 7 depends on both Phase 3 and Phase 6.
Prior Work & Discussions¶
This initiative builds on significant prior work:
| Reference | Type | Summary |
|---|---|---|
| Discussion #1516 | Feature Spec | Original question editing feature spec (Apr 2024) |
| Discussion #1646 | MVP Validation | MVP testing session (Aug 2024) |
| PR #1649 | Unmerged | Parent-child validation, new-option component, design store rewrite |
| PR #1564 | Unmerged | Edit text & edit options wizard dialogs |
| PR #1586 | Unmerged | System question lock icon on assign page |
| PR #1631 | Unmerged | Design page preview question view |
Note: PRs #1564, #1586, #1631, #1649 targeted the old
masterbranch before the monorepo migration. They are closed/unmerged but contain implementation patterns that should be reviewed during Phase 3-5 implementation.
Related Documentation¶
| Document | Purpose |
|---|---|
| Annotation Questions Business Logic | Current domain model and business rules |
| Formal Specification | Precise rule definitions |
| Architecture Analysis | Current vs. target architecture |
| Requirements | 54 v1 requirements with phase traceability |