Specification reading index¶
Read the section that governs the task, not every chapter. These documents state requirements and decisions; code/tests show implementation, and merge task cards show delivery progress. A code/spec discrepancy is evidence to investigate, not authorization to discard a requirement.
| Task | Read |
|---|---|
| Scope, explicit exclusions | 00 — Scope |
| Vocabulary, lifecycle, permissions | 01 — Domain |
| Product behavior | 02 — Functional requirements: locate the relevant F-* family |
| Security, privacy, reliability, operations | 03 — Non-functional requirements: locate the relevant N-* family |
| Question type contract and behavior | 04 — Question types: shared contract, then the one type |
| Module boundaries, persistence, real time, execution | 05 — Architecture: read the relevant section |
| Database fields and schema intent | Data model reference, then the owning apps/api/src/db/ schema |
| A choice not yet settled | 06 — Open questions: never decide an unresolved row silently |
| Novice/expert interaction | 08 — Experience, plus apps/web/DESIGN.md |
For the reason behind a choice, use the ADR topic index. For implementation locations, use the repository map. The merge plan and its progress/task cards own pending migration work, including accepted features not implemented yet.
History, only when needed¶
07 — Original reuse of heig-classroom is frozen history, not an implementation plan. The MVP plan also records historical decisions (D1–D20), not a current backlog; its full text, cited as "PLAN-MVP §x.y", is archived. Follow the history links from a current chapter or ADR when you need an old rationale, compatibility detail or decision provenance. Do not load archives routinely.
Two registers number their decisions with a "D": the MVP plan's D1–D20
(§9 of PLAN-MVP.md, one or two digits) and the merge's
D01–D29 (08-decisions.md, always two digits).
The same number means two different decisions: D14 is the runner stub in
the MVP plan and the journal assets' storage in the merge. A citation names
its register when the context does not: "PLAN-MVP D14", "merge D14".
Keep requirement IDs, question numbers and links stable. Put an implementation fact in its owning code/schema, a product rule in its spec and a rationale in its ADR; link across them instead of copying declarations or delivery diaries.