Architectural Decision Records
Industry ADR, corpus (A)DR, and why hypothesis closure matters at bind
Decision Principles and the Record introduced seven decision-making principles and the Architectural Decision Log — (A)DR framework. This article answers three questions practitioners ask immediately:
- What is the industry ADR? Who invented it, what do you cite, and what is the template?
- What is our (A)DR? How does it relate to the industry form?
- Why add anything? What failures appear when Nygard’s minimal record is treated as sufficient for every consequential bind?
The wound ADRs address
The opening failure of this series — Where Everything Breaks — includes architecture and strategy rooms: decisions without owners, dissent that never reaches the record, stories that change after outcomes arrive. Industry ADRs were invented to reduce one slice of that pain: motivation loss when the team that decided has rotated away.
They work. They are not a complete answer to committed truth under uncertainty — which is what Genesis specifies.
Lineage: decisions before “ADR”
Recording architecture decisions — not only diagrams — predates the ADR label.
Who to cite in prose: Nygard (2011) for ADR origin and template; Kruchten (and the DSA book) for decision-documentation tradition; Fowler or adr.github.io as optional pointers for readers already using community tooling.
There is no ISO/RFC ADR. Teams converge on Nygard’s shape plus local additions (options considered, links to tickets, etc.).
Industry ADR — Nygard template
Nygard’s post is itself formatted as an ADR. The accepted decision:
- Keep a collection of records for architecturally significant decisions — structure, non-functionals, dependencies, interfaces, construction techniques.
- Store them in the project repository (e.g.
doc/arch/adr-NNN.md) as Markdown. - Number sequentially; never reuse numbers.
- When a decision is reversed, mark superseded — keep the old record.
Per-record sections:
Target: one to two pages, written as a letter to a future developer. The post’s experience report: developers rotating onto projects valued the context; clients appreciated longer-term intentions captured before rearchitecture.
What Nygard explicitly does not require: epistemic tiers, falsification triggers, named owners at an organisational commitment boundary, recorded dissent, contest paths, or immutable event logs. Those are not omissions to criticise — they reflect a narrower problem: preserve architectural rationale in agile, in-repo documentation.
Corpus (A)DR — same family, extended bind
This site uses (Architectural) Decision Record — (A)DR for the Genesis-aligned record defined in article 27 and the interactive framework.
Dictionary entry: Architecture Decision Record.
(A)DR retains industry ADR strengths — short, durable, supersede-friendly rationale — and adds what commit capture and the epistemic ladder require when decisions matter:
The log entry is the human-readable projection of a commit — an L0 event with named authority, evidence snapshot, and moment — not meeting minutes.
Field map: industry → corpus
Industry sections are subset, not replaced.
Comparison at a glance
Why the additions matter
1. Decision under uncertainty is a hypothesis
Nygard’s Context lists forces; it does not require testable assumptions with tiers. Under uncertainty, skipping assumptions smuggles inference-as-fact into the Decision section.
(A)DR rule: no listed assumptions under uncertainty → treat as claiming certainty — justify or add rows (Principle 4).
2. Acceptance is not immunity
Industry accepted status marks agreement. It does not wire what would change our mind. Teams then reopen via rank, narrative, or shame — unprincipled bind epilogue, commitment-as-immunity.
Falsification triggers and revision on trigger make revision mechanical when monitors fire — compatible with Principle 7 (finality closes debate, not evidence).
3. Rationale without authority is gossip
“We will use PostgreSQL” in an ADR does not always name who may commit the organisation to that bet. Diffuse authorship produces accountability without commitment.
(A)DR requires decision owner aligned with single writer principle at bind.
4. Git history ≠ institutional memory
Markdown in git helps. It does not by itself give contest channels, supersession propagation to dependents, or tier honesty on embedded claims. Mutable history and wiki rewrites remain risks unless commit discipline applies.
(A)DR ties high-stakes records to L0 and supersession — correction travels forward as facts.
5. Scale needs structure for machines and platforms
Platform self-service guardrails and LLM-enabled MOE tracking need machine-readable hypothesis structure — assumptions, observables, triggers — not only prose Consequences. Industry ADR is a human format; (A)DR is human-first but fielded for automation and effectiveness review.
Proportionality — not every choice needs full (A)DR
(A)DR is not mandatory boilerplate on every typo-level choice. The When the Commitment Boundary Needs Reinforcing and reversibility classes scale rigor:
Inside platform guardrails, Nygard-shaped ADRs may be in-set self-service; out-of-set or high-stakes binds use full (A)DR + exception path.
Practical guidance
- Start from Nygard when introducing ADRs to a team — low friction, high readability.
- Add (A)DR fields when the When the Commitment Boundary Needs Reinforcing cell demands — do not wait for catastrophe to invent triggers retroactively.
- Cite honestly — Nygard 2011 for ADR; Genesis for extensions.
- Use the framework — Architectural Decision Log — (A)DR for schema, template, and principle mapping.
Summary
Industry ADR (Nygard 2011) solved motivation capture for architecturally significant decisions in agile repositories — a genuine contribution to cite and reuse.
Corpus (A)DR extends that discipline for consequential binds under uncertainty: named authority, epistemic tiers, hypothesis tables with monitors and triggers, deliberation and contest paths, and L0-grounded supersession — so decisions remain accountable, revisable, and honest when politics and time apply pressure.
The extensions are not a rejection of ADR. They are what Genesis adds when the decision is not only documented, but committed.
Part VII — Scaling Decision-Making turns from record discipline to invariant enforcement at scale — single writers, routing, and reservations without global locks. It opens with One Authority Per Invariant.