Product Specification: Advanced Screening & Filtering¶
Primary Audience: Product Owner (Alex)
Purpose: Define the business value, user needs, acceptance criteria, and release scope for the Advanced Screening & Filtering feature.
1. Executive Summary¶
SyRF users conducting systematic reviews currently face significant friction when implementing multi-stage screening workflows (e.g., Title/Abstract screening followed by Full-Text screening). The platform's single-project limitation forces teams into cumbersome multi-project workarounds, resulting in lost auditability, duplicated effort, and frustrated users.
This feature introduces Screening Profiles and stage-scoped filtering to enable flexible, auditable, multi-stage screening pipelines within a single project — eliminating the need for workarounds while preserving all existing functionality.
Business Impact:
- Reduces user friction for the most common systematic review workflow (TA → FT)
- Eliminates support tickets related to multi-project workarounds
- Positions SyRF as a more capable platform vs. competitors
- Enables future PRISMA 2020 compliance features
2. Problem Statement¶
Current Pain Points¶
| Pain Point | User Impact | Business Impact |
|---|---|---|
| Single screening state per project | Users cannot distinguish Title/Abstract decisions from Full-Text decisions | Reduced platform adoption for complex reviews |
| Multi-project workarounds | Teams export data, create new projects, re-import studies | High support burden; user frustration |
| Lost audit trail | Decision history fragmented across projects | Compliance concerns for published reviews |
| Manual pass-forward | Studies must be manually moved between stages | Time-consuming; error-prone |
| No criteria versioning | Changing screening criteria invalidates existing decisions | Users restart screening when criteria evolve |
User Feedback Themes¶
From helpdesk tickets and user interviews:
"We have to create a new project for full-text screening and manually transfer studies. It takes hours."
"When our inclusion criteria changed mid-review, we had to start over."
"I can't show auditors a clean record of our screening decisions across stages."
3. User Personas¶
Primary Personas¶
| Persona | Role | Key Needs |
|---|---|---|
| Dr. Sarah (Project Admin) | Lead researcher managing a systematic review team | Configure multi-stage pipelines; maintain audit trail; control who sees what |
| James (Reviewer) | PhD student performing screening | Clear criteria visible during review; efficient workflow; resume where I left off |
| Dr. Chen (Reconciler) | Senior researcher resolving conflicts | See conflicting responses side-by-side; make authoritative decisions |
Secondary Personas¶
| Persona | Role | Key Needs |
|---|---|---|
| Gill (Helpdesk) | Support team member | Understand user configuration; export diagnostic data |
| External Auditor | Compliance reviewer | Verify screening decisions match stated criteria |
4. Goals & Success Metrics¶
Primary Goals¶
- Enable in-project multi-stage screening — Users can configure TA → FT (or other custom) pipelines without leaving a single project
- Preserve auditability — Every screening decision is traceable to a specific criteria version
- Maintain reviewer productivity — New model should not slow down reviewers
Key Performance Indicators (KPIs)¶
| Metric | Baseline | Target | Measurement |
|---|---|---|---|
| Projects using multi-project workaround | ~40% of multi-stage reviews | < 10% | User survey + helpdesk tickets |
| Time to configure two-stage pipeline | N/A (not possible) | ≤ 5 minutes | In-app timing |
| Reviewer throughput (studies/hour) | Current average | No regression | Analytics |
| Selection API latency (p95) | ~300ms | < 400ms | Application monitoring |
| Helpdesk tickets re: screening setup | ~15/month | < 5/month | Ticket tracking |
Qualitative Success Indicators¶
- Positive user feedback on setup experience
- Reduced confusion in helpdesk conversations about screening states
- Auditors can easily follow decision trail
5. Proposed Solution¶
Core Concepts¶
Screening Profiles¶
A named set of screening criteria that can be versioned. Once a profile has been used for screening decisions, it becomes immutable — users must clone to create a revised version. This preserves the audit trail.
Example:
- "TA Criteria v1" — Original Title/Abstract screening criteria
- "TA Criteria v2" — Revised criteria (cloned from v1)
- "FT Criteria v1" — Full-Text screening criteria
Stage Study Pool¶
Each stage defines which studies are eligible for review via a Filter Set. The filter can reference outcomes from other profiles, enabling pass-forward workflows.
Example: Full-Text stage filter: "Include studies where TA Criteria v1 outcome is Included, Conflict, or Maybe"
Selection Policies¶
Per-stage settings that control the reviewer experience:
- Study Selection Mode (required): Screening, Annotation, or Both
- Hide Excluded from Reviewers: Whether reviewers see studies they previously excluded
- Session Count Target: How many reviewers must annotate before reconciliation
- Self-Reconciliation: Whether reconcilers can resolve their own annotations
User Workflow: Two-Stage Review¶
1. Project Admin creates project
2. Admin creates Screening Profile "TA Criteria v1"
3. Admin creates Stage "Title/Abstract" with:
- Profile: TA Criteria v1
- Mode: Screening
- Filter: (none — all studies eligible)
4. Reviewers screen studies at TA stage
5. Admin creates Screening Profile "FT Criteria v1"
6. Admin creates Stage "Full-Text" with:
- Profile: FT Criteria v1
- Mode: Screening + Annotation
- Filter: TA outcome ∈ {Included, Conflict, Maybe}
7. Reviewers screen and annotate studies that passed TA
8. Reconcilers resolve conflicts
9. Admin exports PRISMA-compliant summary
6. User Stories¶
Project Admin Stories¶
US-001: Create Screening Profile¶
As a Project Admin I want to create a Screening Profile with criteria text So that reviewers know exactly what to screen for and decisions are traceable
Acceptance Criteria:
- Profile has a unique name within the project
- Profile includes criteria text (rich text supported)
- Profile shows creation date and author
- Profile can be edited until first use
- After first use, profile shows "In Use" status and is read-only
US-002: Clone Screening Profile¶
As a Project Admin I want to clone an existing profile to create a revised version So that I can update criteria without affecting existing decisions
Acceptance Criteria:
- Clone creates new profile with "(Copy)" suffix by default
- Clone preserves parent reference for audit trail
- Original profile and its decisions remain unchanged
- New profile starts in editable state
US-003: Configure Stage Settings¶
As a Project Admin I want to configure stage-specific settings So that each stage of my review operates according to its requirements
Acceptance Criteria:
- Stage requires a Study Selection Mode (no default)
- Stage allows setting Hide Excluded from Reviewers (default: ON)
- Stage allows setting Session Count Target (for annotation)
- Stage allows enabling/disabling self-reconciliation
- Settings can be modified until stage has activity
US-004: Define Stage Filter¶
As a Project Admin I want to define which studies are eligible for a stage So that only studies that passed previous stages appear for review
Acceptance Criteria:
- Filter builder shows available profiles from this project
- Filter allows selecting outcome values (Included, Excluded, Conflict, Pending)
- Live preview shows count of matching studies
- Filter validation prevents circular references
- Saving filter updates the Stage Study Pool immediately
US-005: Migrate Legacy Project¶
As a Project Admin I want to migrate an existing project to the new screening model So that I can use new features without losing existing work
Acceptance Criteria:
- Migration wizard explains what will happen
- Migration blocks review activity during conversion
- Migration creates initial profile from existing criteria
- Migration preserves all existing decisions
- Migration can be rolled back if errors occur
- Migration logs all actions to audit trail
Reviewer Stories¶
US-006: View Active Criteria¶
As a Reviewer I want to see the screening criteria while reviewing So that I make consistent decisions aligned with the project's methodology
Acceptance Criteria:
- Criteria text is visible (or accessible via one click) during review
- Criteria shows which profile is active
- Criteria is read-only (reviewers cannot edit)
US-007: Get Next Study¶
As a Reviewer I want to get the next study for my current stage and mode So that I can work efficiently through the queue
Acceptance Criteria:
- "Get Next" returns a study appropriate for my role/mode
- Studies I've already reviewed don't reappear (unless in reconciliation)
- If I have saved work in progress, I'm offered to resume
- If no studies are available, I see a clear completion message
US-008: Resume Saved Session¶
As a Reviewer I want to resume my incomplete screening sessions So that I don't lose work when I take a break
Acceptance Criteria:
- "Resume" option appears if I have incomplete sessions
- Resume takes me back to my most recent incomplete study
- My partial work (decisions, notes) is preserved
Reconciler Stories¶
US-009: Access Reconciliation Mode¶
As a Reconciler I want to enter reconciliation mode to resolve annotation conflicts So that conflicting reviewer responses can be consolidated
Acceptance Criteria:
- Reconciliation mode is visually distinct (banner, colour)
- Only studies with sufficient completed sessions appear
- I can see all reviewers' responses side-by-side
- My reconciliation decision becomes the authoritative value
US-010: Self-Reconciliation Control¶
As a Reconciler I want to only reconcile studies I didn't personally annotate (by default) So that reconciliation maintains objectivity
Acceptance Criteria:
- By default, studies I annotated don't appear in my reconciliation queue
- Project Admin can enable self-reconciliation if needed
- When enabled, my own studies appear with a visual indicator
7. Scope¶
In Scope (MVP)¶
| Capability | Description |
|---|---|
| Screening Profiles | CRUD, immutability, cloning |
| Stage Settings | Mode (required), policies, session count target |
| Filter Sets | Profile outcome filtering with AND logic |
| Selection | Mode-aware study selection with policy enforcement |
| Stats | Per-stage, per-user availability counts |
| Migration Wizard | Opt-in conversion from legacy model |
| Audit Trail | All profile/stage/decision changes logged |
Out of Scope (MVP) — Planned for Phase 2¶
| Capability | Rationale for Deferral |
|---|---|
| PRISMA 2020 Diagram | MVP establishes data model; diagram is reporting layer |
| Annotation-based Filtering | Requires reconciled annotations infrastructure |
| Tie-breaker Groups | Complex role model; gather feedback on profiles first |
| Complex Filter Logic (OR, nested groups) | MVP validates core workflow with simple rules |
Out of Scope (No Current Plans)¶
| Capability | Rationale |
|---|---|
| Cross-project profiles | Organisational-level features not in current roadmap |
| AI-assisted screening | Separate feature area |
| Third-party tool integration | Evaluate after core stability |
8. Dependencies & Risks¶
Dependencies¶
| Dependency | Type | Impact if Delayed |
|---|---|---|
| MongoDB indexes for new fields | Technical | Performance degradation |
| Feature flag infrastructure | Technical | Cannot do gradual rollout |
| Helpdesk training | Operational | Increased ticket volume |
| User documentation | Operational | User confusion, support burden |
Risks¶
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Migration data loss | Low | High | Snapshot + rollback; extensive testing |
| Performance regression | Medium | High | Load testing; index optimisation; feature flags |
| User adoption friction | Medium | Medium | Progressive disclosure; guided setup wizard |
| Scope creep | Medium | Medium | Strict MVP boundaries; Phase 2 parking lot |
| Training gap | High | Medium | Helpdesk SOP; in-app guidance; documentation |
9. Release Strategy¶
Rollout Phases¶
| Phase | Scope | Duration | Success Gate |
|---|---|---|---|
| Alpha | Internal testing + 2-3 friendly projects | 2 weeks | No critical bugs; positive feedback |
| Beta | Opt-in for any project via feature flag | 4 weeks | <5 support tickets; performance targets met |
| GA | Default for new projects; migration available | Ongoing | KPIs trending positive |
Feature Flags¶
| Flag | Purpose |
|---|---|
advancedScreening.enabled |
Master toggle for new model |
advancedScreening.migrationWizard |
Enable migration for existing projects |
advancedScreening.complexFilters |
Enable nested filter groups (Phase 2) |
Rollback Plan¶
- Feature flag can disable new UI instantly
- Database schema is additive (old fields preserved)
- Migration wizard includes rollback capability
- Legacy mode continues to function for non-migrated projects
10. Documentation & Training Requirements¶
User Documentation¶
| Document | Audience | Priority |
|---|---|---|
| "Setting up multi-stage screening" guide | Project Admins | P1 |
| "Migration guide" | Existing project owners | P1 |
| "Screening Profiles explained" | All users | P1 |
| Updated reviewer workflow guide | Reviewers | P2 |
Helpdesk Materials¶
| Material | Purpose |
|---|---|
| Diagnostic export bundle | Quickly capture project config for tickets |
| Decision flowchart | Guide users through setup choices |
| FAQ document | Common questions and answers |
| Escalation criteria | When to involve engineering |
11. Open Questions for Product Decision¶
| # | Question | Options | Recommendation |
|---|---|---|---|
| 1 | Should reconcilers see studies they excluded during screening? | A) Yes — consistent experience B) No — avoid bias |
B — Default to hiding; admin can override |
| 2 | What happens when a profile is cloned mid-review? | A) New decisions go to new profile B) Continue with old until stage settings change |
B — Explicit stage change maintains clarity |
| 3 | Should we enforce criteria text for profiles? | A) Required B) Optional |
A — Required for audit trail value |
| 4 | Default value for SessionCountTarget? | A) 1 (single reviewer) B) 2 (dual screening) |
No default — Force explicit choice |
12. Acceptance Checklist (UAT)¶
Before sign-off, verify:
Functional¶
- Create project → create profile → create stage → screen studies → view outcomes
- Clone profile → assign to new stage → filter by original profile's outcomes
- Migration wizard completes successfully on test project
- Rollback restores project to pre-migration state
- Stats match actual study counts
- Audit trail shows all actions
Non-Functional¶
- Selection API returns in < 400ms (p95)
- Page load times unchanged from baseline
- No accessibility regressions (keyboard navigation, screen reader)
Operational¶
- Helpdesk can export diagnostic bundle
- Feature flag enables/disables cleanly
- Documentation published and reviewed
13. Related Documents¶
| Document | Purpose |
|---|---|
| README.md | Feature overview and end-to-end workflow |
| technical-plan.md | Implementation details for engineering |
| terminology.md | Glossary of key terms |
| work-items.md | Sprint-level breakdown |
Document History
| Date | Author | Changes |
|---|---|---|
| 2025-12-08 | Team | Initial product specification |