Write down decisions, with the reasoning and the alternatives
A short record of what was decided, what was rejected, and why, prevents the most expensive class of rework: undoing a constraint whose reason was never written and is discovered by reintroducing the original problem.
Do this firstNothing. This is a place to start.
Not the design. The decision: what was chosen, what was not, and what would have to change for the answer to be different.
The value is asymmetric and shows up late. Nobody needs this in the month it is written. Eighteen months later, someone reasonable looks at a strange constraint, sees no reason for it, removes it, and rediscovers the reason in production. A page that costs twenty minutes prevents that, and it is the cheapest control on this site by a wide margin.
The decoy
Documentation of how the system works. It describes the current state, which the code also does and does more accurately, and it says nothing about which constraints are load-bearing — so the next person removes one.
Evidence
- Blameless PostMortems and a Just Culture — IVArgues that letting engineers give a full account "without fear of punishment or retribution" surfaces the real mechanisms behind a failure rather than stopping at human error, framed using Dekker's Just Culture and Hollnagel's treatment of human error as an effect rather than a cause.
- Postmortem Culture: Learning from Failure (SRE Book, ch. 15) — IVDefines the practice: "For a postmortem to be truly blameless, it must focus on identifying the contributing causes of the incident without indicting any individual or team for bad or inappropriate behavior."
What would settle it
Frequency of decision-reversal-and-reversion in codebases with and without decision records. Hard to measure without reading a lot of history by hand, which is probably why nobody has.
Last reviewed 2026-08-19.