Comparisons
Pairs that get conflated in real conversations. Neither column wins — what decides is the situation. Each record leads with the confusion, because the confusion is the reason the record exists.
Outcome vs outputFirst version vs prototypeDecision record vs one-pagerSuccess metric vs guardrailReversible vs irreversible decisionsFeature flag vs long-lived branchNumbers vs conversationsIncident vs bug
Decision record vs one-pager
What people get wrong about this pair
The two get merged into a long document that is written after the fact and read by nobody. A one-pager asks for something; a decision record remembers something. Different readers, different moments, different lengths.
Decision record
Use it when
After a decision, so the reasoning survives the people who made it.
One-pager
Use it when
Before a decision, to get one made by people who will read one page.
| Aspect | Decision record | One-pager |
|---|---|---|
| Written | After the call | Before the call |
| Reader | A future engineer asking "why?" | A stakeholder deciding now |
| Must contain | The rejected options and why | The recommendation and what it costs |
| Length | As long as the reasoning | One page, decision at the top |