Why should an Architecture Decision Record document the alternatives that were rejected and the negative consequences of the chosen option, rather than just stating what was decided?

## Terms used here - **ADR (Architecture Decision Record)** — a short document recording one significant architecture decision, typically with sections for Status, Context, Decision and Consequences. - **Rejected alternative (a.k.a. "considered option" or "option not taken")** — a candidate solution that was genuinely evaluated and not chosen, recorded together with the reason. - **Consequence** — anything that becomes true because of the decision: a benefit, a cost, a new constraint, or a door now closed. - **Architectural debt** — accumulated downsides consciously (or unconsciously) accepted, which later cost effort to work around or unwind. ## Why rejected alternatives earn their space ### 1. They stop decision churn Without a record, a plausible-sounding option resurfaces every time someone new joins. Each round costs meeting time and goodwill. "We evaluated a message broker in ADR-0012; rejected because our operations team was two people and we had no on-call rota" ends the conversation in ten seconds — or restarts it deliberately, on new grounds. ### 2. They make the decision *revisitable on evidence* This is the deepest reason. Every rejection has a **disqualifier**: a fact that ruled the option out. Facts expire. "Rejected: no managed offering in our region" is a rejection with a shelf life; "rejected: violates our data-residency obligation" may not be. By naming the disqualifier, you give future readers a *trigger condition* — the exact thing to watch for that would make the option worth reconsidering. A record that says only "we chose X" gives them nothing to test. ### 3. They separate reasoned choice from accident Much of a system's shape is accidental — whatever the first engineer knew. Recording alternatives makes the boundary visible: the decisions where real trade-offs were weighed versus the ones where nobody looked. Teams treat those two categories very differently, and should. ### 4. They expose the evaluation criteria To say why B lost, you must state what you measured — latency, operational cost, team familiarity, licence terms. Those criteria (MADR calls them **decision drivers**) are often more reusable than the decision itself; the next similar choice can start from the same list. Criteria also make bias visible: if every option was scored on "what we already know", say so. ### 5. Credibility and compliance Regulated environments and due-diligence reviews ask "show that this was considered". An ADR listing options and their disqualifiers is exactly that evidence. Internally it counters the perception that architecture is handed down by fiat. ## Why negative consequences earn their space ### 1. Every architectural choice is a trade — the ADR must show both sides Choosing strong consistency costs availability under partition. Choosing a modular monolith costs independent deployability. If an ADR lists only gains, it is not describing an architecture decision; it is describing a wish. ### 2. Negatives are the Context of the *next* decision When an ADR is eventually superseded, the successor's Context is usually a list of the predecessor's negative consequences that finally became intolerable. Writing them down at decision time means the future team is reading a prediction that was made honestly, not reconstructing it under pressure. ### 3. They convert hidden debt into tracked debt A negative consequence written down ("we now need a nightly reconciliation job", "free-text search will require a second system later") can be scheduled, monitored, or accepted deliberately. Unwritten, it surfaces as a surprise incident. ### 4. They set expectations for people who inherit the system Much on-call pain comes from operators meeting a constraint nobody warned them about. "Consequence: every environment including CI now needs this database running" is a warning delivered years in advance. ### 5. They discipline the decision itself The act of writing three honest negatives frequently changes the decision. It is the cheapest form of review: if you cannot name a single downside of your chosen option, you have not understood it, and the ADR draft exposes that before the code does. ## How to write them well - **Per option, state the disqualifier, not a verdict.** "Too complex" is a verdict; "requires operating a 3-node quorum with no existing on-call rota" is a disqualifier a future reader can test. - **Include the strongest rejected option, and be fair to it.** Straw men destroy the record's credibility. If the runner-up was close, say it was close — that flags a decision worth revisiting cheaply. - **Record the do-nothing / status-quo option** when it existed; it is often the honest baseline. - **Do not fold rejections into Context.** Context describes forces; alternatives describe candidate responses to those forces. Mixing them makes both harder to scan. MADR gives alternatives their own "Considered Options" and "Pros and Cons of the Options" sections precisely for this. - **Keep negatives concrete and testable.** "Adds complexity" says nothing. "Adds a network hop of ~5 ms to every read and a second failure domain" can be checked against reality later. - **Distinguish accepted-and-permanent from accepted-for-now.** A downside you plan to mitigate is different from one you plan to live with; say which. ## Common failure modes - **The retro-justified ADR.** Written after implementation to bless what was built; alternatives are listed but were never evaluated. Readers can smell this, and it poisons trust in the whole log. - **The consequence section that is a copy of the benefits slide.** All plus signs, no minus signs. - **Endless option lists.** Ten options each with a paragraph turns a one-page record into a report nobody reads; three to five real candidates is typical. - **Rejections without a reason** ("Considered: Kafka, Redis Streams, SQS" — and nothing else). This is worse than useless: it implies evaluation while providing zero information to act on.