Skip to main content

ADR-0019: Architecture Significant Requirements as first-class artifacts

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

Context​

A2C already treats Architecture Decision Records (ADRs) as first-class, one-file-per-decision artifacts under docs/adr/. Architecture-significant requirements, constraints, and invariants are often left implicit, buried in long prose docs, or mixed into ADRs. That weakens:

  • Traceability (git history and review per requirement)
  • AI-assisted work (agents need explicit drivers and invariants)
  • Change control (requirements can drift without a formal decision)

Downstream discussions (including product work that motivated this intake) showed that Architecture Significant Requirements (ASRs) benefit from the same structural discipline as ADRs: one ASR per file, stable IDs, and strict rules for non-trivial modification.

This ADR establishes ASRs in the A2C method. Related decisions — governance chain, amending ADRs, architecture stories, and PRs as control points — are separate Proposed ADRs (0020–0023) per planning/intake/batch-intake-00-plan.md.

Decision​

  1. ASRs are first-class artifacts in A2C-governed repositories that adopt this convention. Each ASR is one Markdown file with a stable numeric ID.

  2. Location and naming (mirror ADRs):

    docs/asr/NNNN-short-title.md
    • NNNN — zero-padded sequence (0001, 0002, …)
    • short-title — lowercase kebab-case summary
    • Human labels may use ASR-NNNN in prose; filenames stay NNNN-short-title.md

  3. This method repository scaffolds docs/asr/ (with a README) so the layout is visible in a2c-workflow. Consumer repositories adopt the same path when they record ASRs.

  4. Template: use templates/asr/asr-template.md.

  5. Non-trivial ASR changes require a corresponding ADR that explains why the requirement changes, what changes, and consequences. Trivial typo and formatting fixes that do not change meaning do not require a new ADR. (Detailed amendment/supersession semantics for ADRs are ADR-0021.)

  6. Scope of this ADR: structure and first-class status of ASRs only. It does not define Specs/Contracts layout, ProductPhase narrative stories, or PR policy — those are separate ADRs.

Consequences​

Positive​

  • Symmetric, scannable layout for requirements and decisions
  • Independent review, history, and deprecation per ASR
  • Clearer contracts for humans and AI agents
  • Visible foundation for later governance ADRs (0020–0023)

Negative​

  • Additional artifact type and numbering sequence to maintain
  • Repositories must choose when to introduce ASRs (not every tiny project needs them on day one)
  • Until ADR-0021 and rules updates land, amendment mechanics for ADRs remain as today

References​

Supersedes​

  • (none)

Superseded by​

  • (none)