Writing ADRs

An ADR exists to stop a settled decision from being re-litigated and to let it be honestly re-evaluated when conditions change. Those two jobs dictate everything below: a conclusion alone can do neither; only the argument - alternatives, kill reasons, costs - can.

ADRs live in docs/adr/, numbered sequentially: 0001-slug.md. Scan for the highest existing number and increment.

Step 1: The gate - should this be an ADR at all?

All three must hold (gate test after Matt Pocock's ADR format); if any fails, stop and say so:

1. Hard to reverse - changing your mind later has meaningful cost.
2. Surprising without context - a future reader would look at the code and wonder why.
3. A real trade-off - genuine alternatives existed and one was picked for specific reasons.

The gate keeps volume low; rigor below is affordable precisely because few decisions pass.

Step 2: Title as an assertion

The H1 states the decision as a full sentence a reader could disagree with - never a topic label.

• Yes: "The deploy script is the test gate, not CI."
• Yes: "Provider access goes through a hand-written LLMClient seam."
• No: "Testing strategy." / "ADR 5: LLM client."

If the title cannot be written as an assertion, the decision is not actually settled yet.

Step 3: Context, concretely

Before drafting, read one or two existing ADRs in the repo and match their voice and density. Open with what is true in the system, using real file paths, function names, and numbers - not abstractions. State the forces that made the decision necessary. A reader should be able to verify every claim against the code.

Step 4: Considered options - mandatory, each rejection named with its kill reason

List every alternative seriously considered, each with the specific reason it lost - one sentence of judgment, not "didn't fit our needs." Mark the chosen option last.

A decision that passed the real-trade-off gate by definition has alternatives worth recording. The named rejection is what prevents the alternative from being proposed again in six months, and the kill reason is the premise to re-check when conditions change.

Step 5: Consequences - mandatory, honest about costs

Record what the decision buys and what it costs, including the permanent costs ("translation is maintained forever"), known limitations, and future obstacles the choice creates. If a consequence names work that must happen before some future change, say so explicitly.

Writing this section is a forcing function: if the costs cannot be written down, the decision is not finished being made. An ADR whose consequences section contains only upside is advocacy, not a record.

Step 6: Cross-reference

Cross-reference related ADRs by number ("the same judgment as the hand-rolled loop, ADR 0004") - decisions form a system, and the links are how a reader discovers it.