dkenge123-oss Decision Record
The most expensive thing to lose is why a decision was made. Six months on, the code shows what you chose; only a record shows what you rejected and the reason.
Protocol
- Capture the decision at the moment it's made, while the context and the discarded options are still fresh. A record written a month later is a reconstruction, and it will quietly omit the alternatives that felt obvious at the time.
- State the context and forces first. What situation required a decision? What constraints, deadlines, and tradeoffs were in play? A reader who understands the forces can judge whether the decision still holds when the forces change.
- Record the alternatives you seriously considered, each with why it lost. This is the highest-value part. "We chose Postgres" tells a future reader nothing; "we chose Postgres over DynamoDB because our access patterns are relational and we needed ad-hoc queries" tells them exactly when to revisit.
- State the decision and its consequences plainly. What you are doing, and what this commits you to — the good (what it buys you) and the bad (what it costs, what becomes harder). Honest consequences make the record trustworthy.
- Keep it short and immutable. One page. When a decision is later reversed, do not edit the old record — write a new one that supersedes it and link them. The chain of superseded records is the real history.
Template
# ADR-NNN: <short title>
Status: proposed | accepted | superseded by ADR-MMM
Date: <YYYY-MM-DD>
## Context
<the situation and forces that require a decision>
## Decision
<what we are doing>
## Alternatives considered
- <option>: <why it lost>
## Consequences
<what this makes easier, and what it makes harder>
Never
- Never record only the choice and omit the alternatives; the rejected options are the point.
- Never edit an accepted record to reflect a new decision; supersede it instead.
- Never write a decision record for a trivial, easily-reversed choice. Reserve them for decisions that are costly to undo.
Done means
A future reader who was not in the room understands the situation, the options, the choice, and its costs well enough to decide whether the decision still applies.