From RFC to ADR: Reaching the Decision and Keeping the Reasoning

The decision nobody could reconstruct

The new tech lead asks a reasonable question: why does every service talk to the billing system through that queue? There is an ADR — ADR-014, four sentences, written eleven months ago. Context: "we needed reliable billing integration." Decision: "use the queue." Consequences: "some added latency." It is technically a record. It answers nothing.

You were there, so you know what ADR-014 doesn't say: the three-week argument across two Slack channels and a heated PR thread; the synchronous-API option that lost because of a rate limit that has since been raised; the staff engineer's objection that was answered with a benchmark nobody can find now. The debate happened. The record was written afterwards, from memory, by one person, on a Friday.

This is the documented, near-universal failure mode of a genuinely good practice. AWS's prescriptive guidance and Microsoft's Well-Architected docs both recommend ADRs — and both note the pain: keeping them current takes time, and managing them gets complex as teams and choices multiply. The root cause is structural: the debate and the record live in different places, so the record is always a lossy transcription. The fix is to make them the same place. Nor is the practice engineering-specific, or even ADR-specific. Google requires a design doc — problem, proposed approach, alternatives considered, trade-offs — written and reviewed before significant technical work begins, a practice set out in the company’s own Software Engineering at Google. It is the same discipline as an ADR, applied one step earlier: the ADR records the choice a design doc argued its way to. The two fail the same way for the same reason, and both are fixed by the same move — hold the argument where the record lives, rather than transcribing one into the other afterwards. Read every step below as covering both artifacts.

Why ADRs rot

One sentence from the ADR community's own material carries the whole diagnosis: an RFC is usually about reaching agreement; an ADR records the agreement once reached. Two artifacts, two moments — and everything between them leaks. The alternatives that were "obviously" wrong go unrecorded (until they stop being obvious). The objection that shaped the final design survives only as a PR comment on a closed thread. The context section gets written last, worst, by whoever lost the game of not-it. Meetings that should have produced decisions produce summaries instead, and the reasoning that makes a decision durable — the thing the whole decision quality chain depends on — is exactly what transcription drops.

Step 1–3: The proposal, the context, the options

1. 1State the proposal as the root claim — the proposed decision, not a question: "We will route all billing writes through a durable queue." This sentence is the future ADR's title. Checkpoint: root exists, one sentence, authored by the proposer.
2. 2Context as separate pro-arguments. Each force that makes the decision necessary — the reliability requirement, the billing-system rate limit, the audit mandate — is its own argument under the root. A monolithic "Context" paragraph cannot be challenged; three separate context claims can each be questioned, confirmed, or knocked down individually. Checkpoint: ≥2 context arguments, each one force.
3. 3Every option gets its own node. The queue, the synchronous API, the batch job — sibling arguments, each with its own pro and con children. Pro/con is relative to the parent, so an option's drawbacks hang off that option, not off the decision. Include the options you expect to reject: the rejected sibling is what answers next year's "why didn't we just…". Checkpoint: every option a reader might ask about exists.

Step 4–6: The RFC round that leaves a record

Now the review round — normally the part that scatters across chat, comments and hallways. Here it runs as three kinds of structured exchange, each a four-turn dialogue between a reviewer and the option's author:

Step 7: Deciding — and what the rating is not

Decision-makers rate the options: one labelled rating each. The distribution is genuine evidence — where the room stood, on the record, before the call. But the rating is not the decision. A named human still decides, and if the call goes against the distribution, the decision node is where that gets explained. (Who that named human should be, and how to assign the role before the debate rather than after, is its own discipline — see the decision-rights tutorial.)

Step 8–9: The ADR you did not have to write

Here is the payoff. The record is not a document you write afterwards — it is the chosen option's node plus everything already attached to it: the context arguments (Context), the rejected siblings (Options Considered), the completed chains (the discussion, with authors), the ratings (where the room stood), and the decision argument with its rationale (Decision). Nothing is transcribed, so nothing is lost in transcription.

1. 1Record the consequences you are accepting. Known downsides — the added latency, the operational burden of the queue — go on as con-children of the chosen option, acknowledged by the decider. Writing them down is what makes it a decision rather than a preference. Checkpoint: ≥1 accepted consequence on the record.
2. 2Export if your org requires repo-tracked ADRs. Many do, correctly — the markdown ADR next to the code stays the compliance artifact. Write the four-section summary from the tree (five minutes, not a Friday), link back to the discussion for the full debate. Checkpoint: the repo ADR cites the tree; the tree holds the reasoning.

Disagree and commit, on the record

The pattern Amazon made famous — disagree and commit — has a legibility problem: how does anyone later know the disagreement was real, heard, and answered, rather than steamrolled? The chain mechanics answer it. A Review chain that ran its full four turns and completed without agreement is precisely the receipt: the objection was made, answered, pressed, and answered again, on the record, before the dissenter committed. The dissenter is documented as having been heard — which is what makes committing afterwards reasonable rather than merely obedient.

Step 10: Superseding without deleting

Decisions age. When the rate limit that killed the synchronous option gets raised, the right move is a new decision that references the one it replaces — a new argument linked to ADR-014's node, stating what changed. The old decision stays readable; its reasoning is exactly why the new decision knows what it is overturning.

One honest gap to manage explicitly: there is no built-in ADR status field. Proposed / accepted / superseded is not a first-class state on an argument — supersession is modelled by linking, and the convention is yours to maintain. State it in your team's working agreement rather than assuming the product enforces it.

Honest limitations

• ✗This does not replace ADRs in your repo if your org requires them version-controlled next to the code. Export and commit the summary; use the tree for the part markdown is bad at — the debate.
• ✗No ADR status field. Proposed/accepted/superseded is a linking convention you maintain, not something the product enforces.
• ✗A chain is four turns. Deep architectural disagreement will need a call; the chain is the record of what was already tried before it.
• ✗Ratings are a single labelled value, not weighted multi-criteria scoring.
• ✗It does not make anyone write good context. Structure lowers the cost of a good record; it does not supply the judgment.

Practical lessons

• ✓One RFC, one discussion. Resist the mega-tree covering the whole quarter's architecture — supersession links connect decisions better than nesting does.
• ✓Seed from what exists. A decision-heavy transcript or your old ADR folder, extracted, gives the debate a running start — labelled as imported, so live arguments stay distinguishable.
• ✓Put reviewers' names on their chains and leave them there. The attribution is the accountability; anonymous architectural objections age into folklore.
• ✓The consequences section is the decider's, nobody else's. Accepted downsides written by the person who accepted them carry a different weight than a reviewer's warnings.

ADR-014, the version that answers

Back to the new tech lead's question. In the rebuilt version, ADR-014 is a node: the queue decision with its rationale, three context forces (one now stale — visibly), a rejected synchronous-API sibling whose fatal con names the old rate limit, four completed Review chains including the staff engineer's, and the benchmark attached as evidence. The tech lead reads for ten minutes, sees the rate limit changed, and opens a superseding proposal linked to the old node. Nobody excavates Slack. That is the entire promise: the chains reach the agreement, the tree records it — and the record answers questions you didn't know it would be asked.