Decision Record

Definition

A decision record is a short, dated note made at the time of a decision: the options considered, the evidence and assumptions used, what was chosen and why, and what would change the choice. It lets others, and your future self, judge the decision by what was known then.

In plain terms

Software teams use architecture decision records, a format proposed by Michael Nygard: a title, a status, the context, the decision and its consequences, kept as small files next to the code. The same habit works for any decision that will later be questioned: a threshold chosen, a source dropped, a rule changed.

Records are added to, not rewritten: when the decision changes, a new record supersedes the old one, which stays (compare Append-only Ledger). Recording expected outcomes with probabilities lets the team later check its Calibration, and recording the data version used allows the same evidence to be seen again. This is the antidote to Outcome Bias and Hindsight Bias.

Example

2026-10-20  Hold the price for 48 hours
Context:     Competitor price fell 10% (data as of 09:00, snapshot s-2041).
Options:     match / hold / undercut.
Assumptions: The drop is a promotion: it fell twice before and recovered within 3 days.
Decision:    Hold.
Expected:    We lose under 2 points of share (70% confident).
Review on:   2026-10-22.
Would change: The drop is still in place on 2026-10-23.

On review, the outcome is compared with the expectation and the assumption, not just with the result: was the drop a promotion? Was the loss under 2 points? Were we right about the 70%?

Common misunderstandings

• “Decision records are paperwork.” They take minutes, and they are the only way to review a decision fairly later.
• “When we learn more, edit the record.” Add a new record that supersedes it; the old one shows what was known then.
• “They are only for software architecture.” Any recurring or consequential decision benefits.