ADR-0101 — Universal Story/Epic documentation standard (applies to every substantial work item; diagnostic add-ons live in ADR-0095)¶
Status: proposed (CVN-N014-EC-S17 ; plan_review 9bc3a310 PASSED, consensus strong, 0 blocker ; operator review applied)
Context-of-record: ADR-0095 produced a high-quality documentary shape (problématisation → user stories → hypotheses → state-of-the-art → consolidation + the 5 artifacts) — but scoped it diagnostic-only ("Does not apply to non-diagnostic Stories (feature/infra/tooling)"). Result: for non-diagnostic work the rigor was unmandated and regressed — CVN-N014-ED-S01 (infra) shipped without its doc set; CVN-N014-EC (a 17-Story Epic) had no epic doc nor nav entry. This ADR generalizes the documentary structure to every substantial Story/Epic, leaving the diagnostic method invariants in ADR-0095.
Context¶
A Story/Epic's documents are how the work becomes reviewable, discoverable, and operable. ADR-0095 proved the value of a mandated shape (its test-strategy decision table caught a real bug on paper). But two concerns belong to all substantial work, not just diagnostics: (a) the documentary structure (the reader-facing dossier + the artifact set + epic discoverability), and (b) enforcement (without a gate, the shape is skipped under delivery pressure). The diagnostic-specific method (pre-registered decision table, envelope bootstrap, multiple-testing control) is genuinely diagnostic and stays in ADR-0095.
Decision¶
Adopt a universal documentary standard for every substantial Story/Epic (see Invariant 2 for the definition), composed of a universal core + optional diagnostic add-ons (ADR-0095). The template is documentation/templates/TEMPLATE_story_doc_canonical.md; TEMPLATE_diagnostic_story.md composes it (no duplication). All artifacts live on docs.cvntrade.eu (ADR-77), hubbed under the Epic landing page (ADR-76).
Invariants¶
- Invariant 1 — universal documentary structure. A substantial Story carries: a hub (
stories/<cvn_id>/index.md), a plan dossier (problématisation 2p → user stories → hypotheses EN → state-of-the-art EN → Definition of Done → Consolidation), an architecture doc, a runbook, and a test strategy. A substantial Epic carries: an epic doc + mkdocs nav entry + scope map + Story index + cross-Story architecture + validation strategy. Testable: docs-site strict build + a presence check. - Invariant 2 — objective "substantial" trigger (non-circular). A work item is substantial when it meets ≥1 objective trigger: production-deployed code change (excl. truly trivial config) · impact on core system components or operational safety · cross-team or governance impact · expected effort >5 person-days / >1 sprint / >5 points · explicit maintainer/operator escalation to
plan_review.plan_reviewis a consequence or escalation, never the basis for substantiality. Docs-only / truly-trivial-config Stories use the lightweightTEMPLATE_story_phases_docs.md. - Invariant 3 — artifact applicability, non-empty compliance. Artifacts are adapted to the work-item type, never empty placeholders. For process/governance Stories: "architecture" = process/system-interaction architecture; "runbook" = gate operation + rollback/amendment + owner handoff; "test strategy" = validation of the process/tooling change. A non-applicable artifact MUST state
N/A+ rationale + reviewer acceptance. Empty placeholders are non-compliant.
| Work item | Required | Conditional / adapted |
|---|---|---|
| Substantial Story | hub · plan · architecture · runbook · test strategy | runbook = operational playbook for process/tooling |
| Substantial Epic | epic doc · nav · scope map · Story index · cross-Story architecture · validation strategy | per-Story artifacts under each Story |
| Diagnostic Story | universal set + ADR-0095 add-ons | decision table · envelope bootstrap · multiple-testing |
| Lightweight docs / trivial config | lightweight template + rationale | full set only on governance/core impact |
- Invariant 4 — Definition of Done includes operational readiness. The DoD covers monitoring/observability, alerting thresholds where applicable, runbook, rollback/recovery, owner handoff. For ML/data/model workflows this includes MLOps readiness (ADR-70); for process/governance Stories the equivalent is gate operation, training/adoption notes, waiver path, and rollback/amendment. DoD (completion checklist) and Consolidation (evidence/decision record + traceability) are both mandatory and distinct.
- Invariant 5 — enforcement: dual, advisory → blocking. A CI guardrail checks artifact presence + required headings; the
story-advancegate checks content quality and rejects empty compliance. Phase 1 (advisory): warnings only, gaps recorded to the remediation roadmap. Phase 2 (blocking): applies to new substantial work opened after a cutoff; legacy gaps do not block unrelated PRs unless that item is being advanced; promotion to blocking requires a published backlog roadmap + assigned owner + documented waiver path + ≥1 live example. Waivers require explicit rationale, owner, expiry, reviewer approval; CI reports them separately.
Relation to other ADRs¶
- ADR-0095 — diagnostic add-ons only from here; its methodological invariants (decision table, envelope, multiple-testing) compose on top of this universal core. ADR-0095 is not rewritten.
- ADR-77 — the artifacts are SSoT on docs.cvntrade.eu; the epic-doc + nav invariant is a discoverability instance.
- ADR-70 — MLOps readiness is the ML-workflow specialization of Invariant 4.
- ADR-81 / ADR-86 — the enforcement gate hangs off the ADR-81 transitions; advisory→blocking mirrors ADR-86 tier promotion.
Rollback¶
Revert this ADR + the universal template + the gate; non-diagnostic Stories fall back to free-form dossiers (the status quo this ADR corrects). No runtime/code impact — the invariants are doc/process conventions + an advisory CI check.