Skip to main content

ASR, ADR, and PR governance

Operator- and AI-facing narrative for Architecture Significant Requirements (ASRs), Architecture Decision Records (ADRs), and pull/merge requests as architecture control points in AI-assisted A2C work.

Binding decisions:

ADRTopic
ADR-0019ASRs as first-class artifacts
ADR-0020Intent → ASR → ADR → optional Spec/Contract → planning
ADR-0021Amends vs Supersede; Amended status
ADR-0022Narrative architecture story (Markdown canonical)
ADR-0023PRs as architecture control points

This note does not replace those ADRs. Prefer the ADR Decision text when anything conflicts.

Core observation​

In an AI-assisted workflow, many low-level implementation changes can be generated, refactored, and validated with less human micro-review. The architectural core does not disappear. Explicit requirements, decisions, and change control become more important because models need clear constraints.

Consequence:

  • Routine implementation PRs may become lighter or more automated
  • Architecture PRs become more important, not less
  • The highest-value PRs establish, change, or validate ASRs and ADRs

ASRs as first-class artifacts​

Record ASRs with the same structural discipline as ADRs:

  • One ASR per file under docs/asr/NNNN-short-title.md
  • Stable numbered IDs and filenames
  • Clear internal structure (template: templates/asr/asr-template.md)
  • Independent review, deprecation, and Git history per requirement

Symmetry with docs/adr/ reduces navigation friction and makes policy checks practical: a PR that changes an ASR is immediately visible.

Critical ASR change rule​

No ASR may be modified beyond trivial typo or formatting fixes unless there is a corresponding ADR that explains why the change is needed, what is being changed, and what consequences follow.

ASRs are stable contracts. ADRs are the formal mechanism of change. Architectural drift is prevented because requirements cannot be quietly edited.

Relationship: ASR and ADR​

ArtifactRole
ASRSignificant requirement, constraint, driver, or invariant
ADRDecision in response to context, requirements, and trade-offs
ASR change via ADRWhen the requirement itself must evolve, the ADR records that evolution

Traceability chain:

  1. Original requirement (ASR)
  2. Decision that responded to it (ADR)
  3. Later decision that changed or refined the requirement (amend or supersede)
  4. Implementation that follows, citing ASR and ADR IDs

Optional Specs and Contracts sit after ADRs when used; if present they follow A2C rules (ADR-0020).

Amends vs Supersede​

Meaning changes always require a new ADR (or ASR). Choose the path:

IntentPath
Core decision still holds; extend or clarifyAmend — base becomes Amended; read base + amendments
Core decision no longer validSupersede — only the new ADR governs new work

See ADR-0021 and rules/08-adr-editing-evolution.md. Informal “Active” labels map to Accepted in A2C.

Pull requests as architecture control points​

PRs (GitLab merge requests, GitHub pull requests, or equivalent) remain the primary checkpoint where teams decide whether a requirement should exist, whether a constraint should change, whether a decision is justified, and whether implementation stays aligned.

Highest-priority PRs​

  • Add, amend, supersede, deprecate, or remove ASRs
  • Add, amend, supersede, reject, or deprecate ADRs
  • Change Specs/Contracts in ways that alter architectural intent
  • Ship implementation that realizes new or changed ASRs/ADRs (cite IDs)

What AI changes​

AI can draft ADRs and ASRs, generate and validate implementation, and absorb boilerplate. It does not remove architectural control points. Faster implementation increases the need for explicit governance.

Practical workflow​

  1. New architectural requirement → new docs/asr/NNNN-….md
  2. New decision → new docs/adr/NNNN-….md (reference ASR IDs)
  3. Existing ASR needs a non-trivial change → new ADR + ASR update in the same PR
  4. Implementation follows → cite ADR and ASR IDs
  5. Review focuses on architecture first: valid ASR? justified ADR? compliant code?

See ADR-0023.

Narrative architecture story​

Per ProductPhase (or equivalent planning horizon), keep a Markdown narrative architecture story as the canonical long-form synthesis. PDF, slides, and other exports are optional presentation artifacts (ADR-0022; templates under templates/architecture/).