Skip to content

QM v2 Planning Context

This folder preserves the planning context that drove two related Question Management v2 initiatives at SyRF, captured originally in .planning/ and .gsd/ workspaces and migrated here so the substance survives the cleanup of those workspaces.

Initiative Source workspace Tracked under Migrated here as
SyRF Platform Evolution / QM v2 product roadmap (16 phases, 3 releases — annotation versioning, reconciliation, screening, PRISMA) .planning/ on PR #2398 PR #2398 qm-v2-requirements-tracker.md, phase-03-collection-infrastructure-plans.md
QM v2 backend & frontend implementation for feat/question-management-v2 (M001–M006 milestones) .gsd/ (gitignored, since deleted) PR #2461 / Epic #2488 qm-v2-implementation-history.md, qm-v2-architecture-and-knowledge.md

Both initiatives' canonical design lives in docs/features/ — this folder holds the planning / execution context that complements those design docs.

What lives here

File Subject Most-recent status
qm-v2-requirements-tracker.md Product roadmap requirements: living checklist of all 101 v1 requirements with phase + release mapping Phase 1 + 2 + 2.1 + 2.2 complete; Phase 3+ pending
phase-03-collection-infrastructure-plans.md Design reference for the unexecuted Phase 3 work: standalone pmAnnotationQuestion and pmQuestionSet collections + Study optimistic-concurrency fix Frozen — not yet executed
qm-v2-implementation-history.md Milestone-by-milestone narrative for the QM v2 implementation work (M001–M006): vision, slice delivery, key files, lessons learned, status M001–M004 ✅ complete (UI not wired). M006 next, then M005 (per D012).
qm-v2-architecture-and-knowledge.md D001–D012 architecture decisions + K001–K019 implementation knowledge (ngrx normalisation, signal stores, version-pinned loading, optimistic concurrency, etc.) Frozen reference for M006 wire-up work

Where the rest of the QM v2 content already lives in docs/

The bulk of the design content was already consolidated into docs/ before the planning workspaces were cleaned up. This table maps source → destination so future readers know where to look.

Product roadmap (PR #2398) outputs

Source (in .planning/ on the branch) Canonical home in docs/
.planning/ROADMAP.md (16 phases / 3 releases) docs/roadmap/product-features-roadmap.md
.planning/REQUIREMENTS.md traceability table docs/roadmap/product-features-roadmap.md (phases section) + per-feature briefs
Phase 1 (spec resolution) outputs Merged into docs/features/*/design-decisions.md files
Phase 2 (PRISMA specification) outputs docs/features/prisma-specification/ (5 spec docs)
Phase 2.1 (Documentation Suite) outputs The phase's output IS docs/features/, docs/user-guide-drafts/, and docs/architecture/platform-architecture.md
Phase 2.2 (Annotation Question Import) design docs/features/annotation-import/ (brief, design, implementation-plan)
Phase 6.1 (Annotation Import) implementation plans docs/features/annotation-import/implementation-plan.md — 1752-line consolidated plan supersedes the 5 GSD plans
Release 1 / 2 / 3 migration plans docs/roadmap/migrations/

QM v2 implementation (PR #2461) outputs

Source (in .gsd/ on the branch) Canonical home in docs/
Question Management design specs (data model, API, scope, workflows, migration) docs/features/question-management/README.md (1500+ lines, comprehensive)
Question Management feature briefs docs/features/question-management/brief.md, brief-phase-06.md
Annotation form v2 specs docs/features/annotation-form-v2/
Annotation versioning specs (Identity + Immutable Versions pattern) docs/features/annotation-versioning/
Reconciliation D1–D50 design decisions docs/features/reconciliation/design-decisions.md
.gsd/ event logs, transient state files (db-shm, db-wal, doctor-history) Not preserved (transient runtime state)

How these docs are intended to be used

  • qm-v2-requirements-tracker.md is living: as work lands, update the [ ] checkboxes to [x] and adjust the per-phase status column. The intent is to keep one consolidated view of QM v2 progress that complements the per-feature briefs.
  • qm-v2-implementation-history.md is frozen at 2026-04-23: it captures the milestone-level state at the point the GSD workspace was cleaned up. When M005 / M006 land, append new sections rather than rewriting old ones — the historical record is what makes lessons learned discoverable.
  • qm-v2-architecture-and-knowledge.md is a frozen reference: D001–D012 decisions and K001–K019 knowledge entries should inform future implementation work but should not be modified retroactively. If a decision is reconsidered, append a new entry (mirroring how D004 → D005 and K004 → K004 REVISED are layered here).
  • phase-03-collection-infrastructure-plans.md is a frozen design reference. When Phase 3 work is picked up, reuse the design decisions, code skeletons, and pitfalls captured there as input — but execute via whatever workflow is in use at the time (this project has moved away from the original GSD-style execution loop).

Status snapshot (2026-04-23)

Stream Where Status
Product roadmap Phase 1 (spec resolution) docs/features/*/design-decisions.md ✅ Complete
Product roadmap Phase 2 (PRISMA spec) docs/features/prisma-specification/ ✅ Complete
Product roadmap Phase 2.1 (Documentation suite) docs/features/, docs/user-guide-drafts/, docs/architecture/platform-architecture.md ✅ Complete
Product roadmap Phase 2.2 (Annotation Question Import design) docs/features/annotation-import/ ✅ Complete
Product roadmap Phases 3–7 (R1: QM + Form v2 + R1 migration) (pending) ⬜ Pending
Product roadmap Phases 8–11 (R2: reconciliation) (pending) ⬜ Pending
Product roadmap Phases 12–16 (R3: screening + dedup + PRISMA) (pending) ⬜ Pending
QM v2 backend M001 (Domain entities, migration, v2 API — 71 tests) code on feat/question-management-v2 + this folder ✅ Complete (2026-03-30)
QM v2 frontend M002 (Admin Design / Assign / Preview UI — 74 tests) code on feat/question-management-v2 + this folder ✅ Complete (2026-04-01), UI not wired to API
QM v2 frontend M003 (Annotation Form v2 — 46 tests) code on feat/question-management-v2 + this folder ✅ Complete (2026-04-01), UI not wired to API
QM v2 M004 (Admin Decision Framework — 55 tests) code on feat/question-management-v2 + this folder ✅ Complete (2026-04-01), UI not wired to API
QM v2 M006 (Frontend ↔ Backend Integration) (planned) Next up (per D012, must precede M005)
QM v2 M005 (Production Migration) (planned) ⬜ Blocked on M006

Cross-references