Rejected-Option Record

The code shows what was chosen. The system shows how it behaves. Nothing shows what was considered and rejected, and that is the information a future reader needs most: to reopen a decision intelligently, to avoid re-proposing something already dismissed, and to know what has changed since.

An ADR that lists a decision and its benefits is a justification. One that records the options rejected, the reasons, and the conditions under which those reasons would no longer hold is a decision record.

Why it matters

Architecture decisions are revisited, and they are revisited by people who were not present. Without the rejected options, the revisit starts from zero — and frequently arrives at the option that was dismissed for a reason nobody remembers.

It also makes the record credible. A document listing only benefits reads as advocacy, and readers respond by hunting for the omitted downside.

Implementation patterns

• Include the option that was nearly chosen, with an honest account of why the margin was narrow.
• State the negative consequences of the chosen option. An ADR with none is not credible.
• Write the conditions that would make this wrong — the most valuable and least written section, because it tells a future reader what to watch for and converts the record into a monitoring instruction.
• Record dissent with its reasoning. Consensus language conceals the most useful signal in the document; a recorded disagreement is worth more than recorded agreement.
• Place it beside the code it governs, in the repository, referenced from the code where the decision is visible — so someone looking at an odd retry policy finds the ADR from the code rather than by searching a wiki.
• Index by the question it answers, not by number, so a reader with a question can find whether it has been decided.

Industry example

Product engineering organisations such as Linear and Vercel that ship continuously with small teams cannot maintain current-state documentation and do not need to. What they need is the reasoning: why sync works the way it does, why this queue is deliberately not a distributed broker, which specific failure the unusual timeout exists to prevent.

That content is stable for years, because reasoning outlives structure — which is the whole argument for prioritising it over descriptive documentation.

Failure scenarios

• Only the chosen option recorded, so the decision cannot be reopened intelligently.
• No negative consequences listed, making the document read as advocacy.
• Consensus language, concealing the disagreement.
• Stored in a wiki nobody searches, so it exists and is never found.
• Written after the fact to satisfy a process, which produces a reconstruction rather than a record.

Trade-offs

Writing the rejected options takes time at exactly the moment a team wants to start building, and some of that writing will document options nobody would ever reconsider.

The mitigation is proportionality: write an ADR only for decisions that are expensive to reverse. A record for every choice produces an archive nobody reads and devalues the ones that matter. Ten well-written records across a system's life are worth more than two hundred perfunctory ones.

Interview question

"Show me a decision your team made two years ago that you would now question. What would you need to have written down at the time to reopen it properly, and what do you actually have?"