ADR(A)DRArchitectural Decision Recordarchitecture decision recordsdecision record

OrganisationCommitment & authorityEpistemology

Architecture Decision Record

Industry ADR (Nygard 2011) and corpus (A)DR — durable decision rationale with optional hypothesis closure

MARKO ŽIVKOVIĆ In review

An Architecture Decision Record (ADR) is a short, durable write-up of one significant decision — why it was made, what was chosen, and what followed. In engineering culture the term and the usual template come from Michael Nygard (2011). On this site (A)DR names the same family, extended for Genesis: any consequential organisational choice, bound as L0 where stakes require, with hypothesis closure at bind.

Full comparison and field rationale: Architectural Decision Records. Interactive schema: Architectural Decision Log — (A)DR.

Industry ADR — origin and template


Who to cite (primary)	Michael Nygard, Documenting Architecture Decisions (2011)
Predecessor (context)	Philippe Kruchten — decision registers and rationale in Documenting Software Architectures; thanked in Nygard’s post
Secondary pointer	Martin Fowler — ADR bliki; adr.github.io for community templates (MADR, tooling)
Standard?	No formal standard — convergent practice around Nygard’s five sections

Nygard template:

Section	Content
Title	Short noun phrase
Context	Forces — technical, political, social, local
Decision	“We will …”
Status	proposed · accepted · superseded
Consequences	All outcomes — positive, negative, neutral

Scope (industry): architecturally significant decisions — structure, non-functionals, dependencies, interfaces, construction techniques. Form: markdown in the project repository; supersede old records; do not reuse numbers.

What industry ADR solves: future readers understand motivation — neither blind acceptance nor blind reversal when context changes.

Corpus (A)DR {#corpus-adr-adr}

(Architectural) Decision Record — (A)DR keeps the durable rationale idea and adds what Genesis requires for committed truth under uncertainty:

The markdown is the human-readable face of an L0 commit — not meeting notes, not ticket closure, not a slide deck archive.

Extension cluster	What (A)DR adds	Failure when missing
Authority	Named decision owner; quality mechanisms; reversibility class	Accountability without commitment; unprincipled bind epilogue
Epistemics	Assumptions + tiers at bind; evidence refs; “no assumptions → claiming certainty”	Inference-as-fact; confident deck
Hypothesis loop	Observables, monitors, falsification triggers, test protocol, revision on trigger	Commitment-as-immunity; politics replaces mechanics
Deliberation	Options considered; dissent recorded pre-bind	Groupthink; buried findings
After bind	Contest path; supersession chain	Decisions as one-way streets; correction as personal attack
Ground truth	L0 event + supersession — not silent edits	Mutable history; non-propagating refutation

Industry ADR Context / Decision / Consequences map to (A)DR Context & problem, Decision & rationale, and Consequences & follow-ups — the corpus does not replace those sections; it surrounds them with bind discipline and operational feedback (closed-loop control, experiment architecture).

Side-by-side

	Industry ADR (Nygard)	Corpus (A)DR
Cite	Nygard 2011	Genesis + Decision principles
Scope	Architecturally significant technical choices	Any consequential org choice when framework says so
Core sections	Title, Context, Decision, Status, Consequences	Same plus authority, hypothesis table, deliberation, contest
Uncertainty	Implied in “forces”	Explicit assumptions, tiers, triggers
After accept	Status / superseded	Monitors fire → mandatory revision path
Storage	Markdown in repo	Markdown and L0 commit where stakes require
Proportionality	One size fits arch decisions	Decision Strategy Framework + reversibility class

Compatibility: teams may write Nygard-shaped ADRs for in-set architecture inside platform guardrails. (A)DR is the required superset when uncertainty, stakes, or organisational bind demand hypothesis closure — e.g. enterprise map row it2 (major architecture decision).

Why the additions matter

Industry ADR answers: What did we decide, why, and what did it cost?
That is necessary and often sufficient for low-stakes, reversible, well-understood architecture.

It is not sufficient when:

The decision is a bet under uncertainty — without assumptions and triggers, revision reopens as politics (Principle 4).
Ownership is diffuse — “we decided” erases who is accountable at the commitment boundary.
The record is not ground truth — wiki edits and ticket states are not immutable facts; supersession must propagate.
Correction has no channel — dissent after bind becomes personal combat without contestability.
Platform and org scale — MOE/MOP and LLM-enabled review need structured binds to attach effectiveness signal to hypotheses, not only to activity metrics.

(A)DR is therefore ADR + Genesis closure: same readability Nygard optimises for, plus machinery so honest decisions survive time, rank, and incentive pressure.

Corpus stance

Adopt A2 — working stance: cite Nygard (2011) for industry ADR; cite Kruchten for decision-documentation lineage; use (A)DR when this site’s extensions apply. Do not attribute falsification triggers, tiers, or L0 binding to Nygard.