Decision Record Log¶
Document — instantiates Decision Commitment and Closure
Preserves why a decision was made — its rationale, assumptions, recorded dissent, and the strongest rejected alternatives — so later reviewers can reconstruct and calibrate.
The Decision Record Log is the durable memory of a decision's reasoning. When a choice closes, the log captures why it was made, the key assumptions it rested on, the dissent that was voiced, and the strongest alternatives that were considered and rejected — and then it stays fixed, so that a year later a reviewer can reconstruct the thinking as it actually was rather than as the outcome makes it look. Its defining idea is that it explains a decision without binding it: the log is not proof that anyone had the authority to decide, and it does not change operational state. It answers "why did we do this, and what did we give up?" — never "who was allowed to?" That question belongs to a different artifact.
Example¶
An architecture council settles a long-running argument and commits the platform to an event-driven design over a simpler request/response one. The moment they close, they write an Architecture Decision Record.[n1] It states the rationale (expected write-throughput and team autonomy), the load-bearing assumptions (that traffic will grow past a stated point, and that teams can absorb the operational complexity of a message bus), the dissent (one senior engineer's recorded objection that the throughput assumption is speculative and the complexity underrated), and the forgone option (request/response, rejected for coupling reasons, with those reasons written down). Two years later, when throughput has not grown as projected, the ADR lets the team ask a precise question — "the traffic assumption was wrong; does the rest of the rationale still hold?" — instead of re-arguing the whole thing from scratch or quietly pretending the original call was obvious. The dissenting engineer's objection is there in the record, not erased by the passage of time.
How it works¶
The log writes one structured entry per decision, authored at the moment of closure while the reasoning is fresh, and thereafter treated as append-only: corrections are added as new notes, never edits that overwrite the original. Each entry carries the rationale, the assumptions marked as load-bearing (so a later monitor can watch them), the strongest forgone option and why it lost, and any dissent captured close to verbatim and attributed per the team's norms. The discipline that makes the log worth anything is that it is written before the outcome is known — its value is precisely that it cannot be quietly retrofitted to whatever happened.
Tuning parameters¶
- Capture depth — how much reasoning is recorded. Deep entries preserve nuance but cost time; shallow ones are cheap but decay into "we chose X because it was best."
- Dissent attribution — whether objections are named or anonymized. Named dissent carries weight and accountability; anonymized dissent lowers the cost of speaking up.
- Immutability — strict append-only versus editable. Append-only protects the record from being rewritten around the outcome; editable is tidier but corruptible.
- Template rigor — a fixed schema versus free prose. Schemas ensure assumptions and forgone options are never skipped; prose reads better but drops fields under time pressure.
- Indexing — how entries are made findable later. An unindexed log is written but never consulted.
When it helps, and when it misleads¶
Its strength is calibration: because the original assumptions and opportunity costs are preserved unaltered, a later review can compare what was expected against what happened and improve future judgment — rather than, in the archetype's words, rewriting history around whichever outcome occurred. It directly guards two failure modes: dissent erasure and hidden opportunity cost, both of which quietly disappear when reasoning is not written down.
Its failure mode is log theater — records dutifully written and never read, so the reasoning exists on paper but informs no future decision. The classic misuse is the retrofitted rationale: an entry composed after the outcome is known and shaped to make the original call look inevitable, which destroys exactly the calibration value the log exists for. The guarding discipline is to write at the moment of closure, keep the record append-only, and actually re-open it at review time.
How it implements the components¶
rationale_and_assumption_record— the log's core: the reasons and the load-bearing assumptions, fixed at closure.forgone_option_record— it preserves the strongest rejected alternatives and why they lost, so forgone options don't vanish from memory.dissent_and_appeal_channel— recorded dissent stays inspectable in the entry rather than evaporating once the decision is made.
It is not the binding instrument: decision_owner_and_authority, explicit_commitment_statement, and emergency_authority_override belong to Signed Commitment Authorization, its document twin. The log explains and preserves the choice; the authorization actually closes it and proves who was empowered to.
Related¶
- Instantiates: Decision Commitment and Closure — the log preserves the reasoning, dissent, and forgone options the archetype requires to remain inspectable.
- Consumes: Option Comparison Matrix supplies the rejected options it records; Precommitment Challenge Session supplies the dissent.
- Sibling mechanisms: Signed Commitment Authorization · Decision Clock · Reopen Trigger Monitor · Go/No-Go Commitment Gate · Option Comparison Matrix · Precommitment Challenge Session · Execution Handoff Checklist · Reversibility and Exit Check
Editorial Notes¶
Form Classification¶
Form family: Record, Log & Register
Rationale: Decision Record Log operates as a durable record, ledger, register, or trace whose value depends on preserving actual state or history because it preserves why a decision was made — its rationale, assumptions, recorded dissent, and the strongest rejected alternatives — so later reviewers can reconstruct and calibrate.
Independent corroboration: The frozen evidence defines Decision Record Log as 'Preserves why a decision was made — its rationale, assumptions, recorded dissent, and the strongest rejected alternatives — so later reviewers can reconstruct and calibrate', so its operative form is Record, Log & Register.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Software architecture cohered architecture decision records that preserve a choice's rationale, assumptions, alternatives, dissent, and consequences without themselves conferring authority.
Related originating lineages:
- Organizational & Management Science — Decision logs and journals generalized reconstructable reasoning to nontechnical governance choices.
Review resolution: Software architecture cohered architecture decision records that preserve a choice's rationale, assumptions, alternatives, dissent, and consequences without themselves conferring authority.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
[n1] An Architecture Decision Record (ADR), popularized by Michael Nygard, is a short document capturing a single architectural decision, its context, and its consequences — kept alongside the code so future maintainers can see why the system is the way it is. ↩