Skip to content

TEMPLATE — canonical Story/Epic documentation (universal)

Is this work item "substantial"? (ADR-0101 Inv 2)

Substantial iff ≥1 objective trigger: prod-deployed code change (excl. truly trivial config) · impacts core components or operational safety · cross-team or governance impact · effort >5 person-days / >1 sprint / >5 points · explicit escalation to plan_review. plan_review is a consequence/escalation, not the basis. If none apply → use TEMPLATE_story_phases_docs.md.

The artifact set (ADR-0101 Inv 1) + applicability (Inv 3)

Work item Required artifacts Adapted meaning
Substantial Story stories/<cvn_id>/index.md (hub) · plan · design/<cvn_id>-architecture.md · runbooks/runbook_<slug>.md · stories/<cvn_id>/test_strategy.md process Story: "architecture"=process/system interaction; "runbook"=gate op + rollback/amendment + owner handoff; "test strategy"=validation of the process/tooling change
Substantial Epic epics/<epic>-*.md (epic doc) + mkdocs nav entry · scope map · Story index · cross-Story architecture · validation strategy per-Story artifacts live under each Story
Diagnostic Story universal set + ADR-0095 add-ons decision table · envelope bootstrap · multiple-testing control

Empty placeholders are non-compliant. N/A requires a short rationale + reviewer acceptance.

Skeleton — the PLAN dossier (documentation/reviews/<date>-<cvn>-<slug>-plan.md)

  1. Problématisation (non-technical, ~2 p.): the question in one sentence · why now · the traps/illusions · what is actually measured · the honesty of the verdict · why it matters (the decision it feeds).
  2. User stories ("As a… I want… so that…") mapped to the sections.
  3. Hypotheses (EN): each hypothesis + the NULL tested + the test method. Distinguish hypotheses tested vs working assumptions surfaced.
  4. State of the art (EN, references): theory + best practices grounding the approach, mapped to the hypotheses.
  5. Definition of Done (ADR-0101 Inv 4): actionable completion checklist — including the doc artifacts and operational readiness (monitoring/observability · alerting thresholds where applicable · runbook · rollback/recovery · owner handoff). ML/data/model → MLOps readiness (ADR-70); process/governance → gate operation · training/adoption notes · waiver path · rollback/amendment.
  6. Consolidation & traceability: problem→hypothesis→US→section→literature matrix (no dangling thread) + decision routing (verdict → action). DoD and Consolidation are both mandatory and distinct (ADR-0101 Inv 4).
  7. Approach / design (the how): mechanism vs judgment, files, risks & mitigations.

Diagnostic Stories add (ADR-0095): pre-registered decision rule (§1, before the run) · significance-keyed decisions · first-class inconclusives + no-crash · un-measured-input gating · exhaustive decision table + exhaustiveness test · explicit multiple-testing control.

Skeleton — ARCHITECTURE (design/<cvn_id>-architecture.md)

The how it is built: components + interfaces + data/control flow (or, for a process Story, the process/system-interaction architecture) · key load-bearing decisions · rollback mechanics · ADR compliance · scope boundary with adjacent Stories.

Skeleton — RUNBOOK (runbooks/runbook_<slug>.md)

The how the operator uses it (ADR-26: start at Grafana): trigger · detect · rollback / kill-switch (+ rehearsal if load-bearing) · owner handoff. For a process/tooling Story: gate operation · rollback/amendment path.

Skeleton — TEST STRATEGY (stories/<cvn_id>/test_strategy.md)

Objectives & scope (what is tested vs what is validation-only) · pyramid + ADR-83 tiers · test-case tables · invariants · @pytest.mark.story("<cvn_id>") (ADR-87) · system validation. Diagnostic: + exhaustive decision table + exhaustiveness test.

Skeleton — HUB (stories/<cvn_id>/index.md)

One-liner · "the documents (in reading order)" table (plan · architecture · ADR · runbook · test strategy · MLOps/readiness · committee) with for-whom · live state (OP = SSoT, ADR-76) · ADR-81 gate status.

Skeleton — EPIC doc (epics/<epic>-*.md) + nav entry

epic_id · need_id · OP/GH · status · objective · scope · cross-Story architecture · Story index table · validation strategy. MUST be added to mkdocs.yml nav (ADR-77 discoverability; ADR-0101 Inv 1).

Enforcement (ADR-0101 Inv 5)

CI guardrail checks presence + required headings; story-advance checks content quality + rejects empty compliance. Advisory first → blocking after cutoff (waivers: rationale · owner · expiry · approval).