Skip to main content

ADR-0022: Narrative architecture story per ProductPhase

  • Status: Accepted
  • Date: 2026-07-17
  • Deciders: Michel Gillet

Context​

A2C favors fine-grained ASRs and ADRs (ADR-0019, ADR-0020). That structure is strong for governance and AI constraints, but weak for:

  • New contributors who need a coherent overview
  • Stakeholders who prefer a narrative over many disconnected files
  • Reflecting how architecture evolved across ProductPhases (e.g. 1.0, 2.0)

Individual ADRs and optional Specs/Contracts do not replace a single story-like document that walks from intent through requirements and decisions to behavior and interfaces for a given phase.

Templates for that story already exist in this intake: architecture-story-abstract.md and architecture-story-skeleton.md.

Decision​

  1. Per ProductPhase narrative. For each major ProductPhase a project uses (e.g. 1.0, 2.0), produce a Narrative Architecture Story that:

    • Describes intent and problem framing for that phase
    • Summarizes key ASRs and ADRs that define the architecture
    • Explains how those decisions show up as Specs and Contracts when those artifacts are used (optional per ADR-0020)
    • Outlines how A2C and planning were used in that phase

  2. Markdown is canonical. The story is authored and versioned as Markdown under the repository (recommended: docs/architecture/, e.g. docs/architecture/productphase-1.0-architecture-story.md). Use the architecture-story templates above.

  3. Presentation exports are optional. PDF, slides, or other formats may be generated for human discussion and review. They are not a required CI or forge artifact for A2C method compliance. If exports are stored in-repo, keep them clearly secondary (e.g. under docs/releases/ or a local presentation folder) and regenerate from Markdown when the story changes.

  4. Source of truth. ASRs, ADRs, and optional Specs/Contracts remain the precise governing artifacts. The architecture story is a human-oriented summary; it must not contradict Accepted ASRs/ADRs. When architecture changes materially in a phase, update the story in the same delivery stream as the governing ADR/ASR changes (or promptly afterward).

  5. Adoption. Projects that do not use ProductPhase labeling may still publish a single architecture story for the current product stage. The convention is recommended for multi-phase products; it is not mandatory for every minimal A2C bootstrap.

Consequences​

Positive​

  • Onboarding and stakeholder review without reading every ASR/ADR file
  • Phase-scoped historical narrative for audits and design reviews
  • Aligns with docs-as-code: one Markdown source, optional exports
  • Templates already available for abstract and full skeleton

Negative​

  • Extra document to keep in sync when architecture changes
  • Risk of the story drifting from ASRs/ADRs if updates are skipped
  • Teams must choose local paths/export tooling; A2C does not mandate a PDF pipeline

References​

Amends​

  • (none)

Amended by​

  • (none)

Supersedes​

  • (none)

Superseded by​

  • (none)