Which section is missing from most architecture decision records, and why does it matter?
Show the full answer Hide the answer
What is being tested
Whether you know that decisions are rarely wrong when made and frequently wrong later.
Why revisit conditions matter
Most decision records state context, options, choice and consequences, and stop. But architectural decisions are trades whose terms depend on scale, team size and business context — all of which change.
A decomposition that was correct at 200 engineers becomes expensive at 4,000. A shared database that was fine with two teams becomes a bottleneck with eight. In each case the original decision was right and the situation moved.
Without written revisit conditions, the revisit is triggered by an outage or a new CTO rather than by evidence, and by then the correction is expensive.
What a good one looks like
"Revisit if the average service has fewer than two committers, if cross-service changes exceed a third of our features, or if operational overhead per service exceeds X engineer-days per quarter."
Specific, measurable, and checkable by someone who was not present when the decision was made.
The other section that carries the weight
Options considered, with the reasoning for rejection. This is the valuable half of any decision record — without it, the next person re-litigates every settled question and frequently re-makes a mistake that was already discovered and avoided.
A record with only the chosen option documents an outcome, not a decision.
What makes records work
- Written at the time. Reconstructed afterwards they are rationalisation.
- One page. Longer records are not written and not read.
- Immutable — a superseded decision is not edited; a new record supersedes it, preserving the history of reasoning.
- Stored with the code, so they are found by people working on the system.
- Reserved for decisions that are expensive to reverse or non-obvious. A record for every library choice devalues the whole set.
The consequences section
State what gets worse, not only what improves. A decision with no stated downside has not been understood, and the record will not be trusted by anyone who has thought about it.