Phase 15: Screening Annotations and Reconciliation¶
Release 3 -- Structured Screening Decisions Phase 15 upgrades screening from simple include/exclude to structured decisions with explicit exclusion reasons.
Summary¶
Today, SyRF screening records only a binary decision: include or exclude. This phase adds structured exclusion reasons -- when a reviewer excludes a study, they select specific reasons linked to the screening profile's criteria (e.g., "Wrong Population", "Wrong Intervention", "Wrong Study Design"). Screening disagreements get their own reconciliation workflow, following the same random-assignment pattern established for annotation reconciliation in Release 2.
The Problem¶
The PRISMA 2020 flow diagram requires exclusion counts broken down by reason (e.g., "45 excluded for wrong population, 23 for wrong intervention, 12 for wrong study design"). SyRF cannot produce these counts because it does not capture why studies are excluded.
Many teams have found a workaround: they use annotation questions to track exclusion reasons. But this decouples the reason from the screening decision -- the exclusion reason lives in the annotation system while the screening decision lives in the screening system, with no formal link between them. Some teams have abandoned SyRF's screening infrastructure entirely because of this limitation.
What We Are Building¶
Structured Exclusion Reasons¶
When configured by a project administrator, excluding a study triggers a structured form:
- Primary exclusion reason: Selected from a defined list linked to the screening profile's criteria (e.g., "Wrong Population", "Wrong Intervention")
- Sub-reasons: Optional follow-up questions for more detail (e.g., if "Wrong Population" is selected, a sub-question asks "Non-mammalian species?" or "Wrong age range?")
- Hierarchical structure: Questions can be conditional -- sub-questions appear only when relevant parent answers are selected
The form is mandatory when configured -- this guarantees 100% of exclusions have recorded reasons, ensuring complete data for PRISMA reporting. The exclusion reason and the screening decision are saved atomically as a single record, eliminating the data integrity gap.
Screening Reconciliation¶
When multiple reviewers screen the same study, they may disagree. Screening reconciliation follows the same principles as annotation reconciliation:
- Random assignment: Studies needing reconciliation enter a pool; the system assigns them to reconcilers
- Unified reconciliation: The reconciler creates a single authoritative record covering both the screening decision (include or exclude) and the exclusion reason. The reconciler has full authority to confirm or override the candidate decisions
- Bulk approve: When all screeners agree (same decision, same primary exclusion reason), studies can be approved in bulk
Important Ordering¶
Screening reconciliation must finish before annotation reconciliation can proceed for the same study. An excluded study is never reconciled for annotations -- this saves work and avoids meaningless reconciliation effort.
Optional -- Not a Requirement¶
Screening Annotations are optional. Teams that prefer the current simple include/exclude workflow are unaffected. The feature is configured per Screening Profile -- administrators choose whether to require structured exclusion reasons.
Why This Matters for PRISMA¶
Screening Annotations directly produce the data needed for the PRISMA "Reports excluded (with reasons)" boxes. With this feature, generating PRISMA-compliant exclusion breakdowns becomes a one-click operation rather than a manual data reconciliation exercise.
How It Connects¶
| Connection | Detail |
|---|---|
| Phase 13 (Screening Profiles) | Exclusion reasons are linked to Screening Profiles; the structured form is defined at the profile level |
| Phase 14 (Stage Filtering) | Final screening outcomes (after reconciliation) feed stage filter rules |
| Phase 10 (Reconciliation Workflow) | Screening reconciliation follows the same random-assignment, blinded-comparison pattern |
| Phase 16 (Export and PRISMA) | Screening decisions with structured reasons feed PRISMA exclusion breakdown |
For the platform architecture overview, see platform-architecture.md. For the full Screening Annotations specification, see README.md.
Phase 12 (dedup) cleans the data. Phase 13 (profiles) configures screening criteria. Phase 14 (filtering) routes studies to stages. Phase 15 (screening) adds structured decisions. Phase 16 (export/PRISMA) delivers the output.