Skip to main content

Context, Decision, Consequences: The Three Required Sections

What This Concept Is​

Every ADR, regardless of template, has three load-bearing sections.

  • Context - the forces acting on the decision: constraints, non-negotiables, alternatives considered, what was tried before. This is the why this choice even had to be made section.
  • Decision - what we chose, in direct declarative language. No passive voice. No hedging.
  • Consequences - what becomes true because of the decision: gains, costs, risks, newly impossible things, newly easy things. This includes negative consequences in writing.

Miss any of the three, and the record becomes useless in a distinct way.

Why It Matters Here​

ADRs rot silently. The symptoms differ depending on which section is thin:

  • Thin context: future readers cannot tell if the decision still applies. They re-litigate from scratch.
  • Thin decision: nobody is sure what was actually decided. Implementations diverge.
  • Thin consequences: nobody planned for the downsides. Surprises appear in incident post-mortems.

The phrase "decisions without consequences" is the classic tell: the ADR lists positives only. Treat that as a draft, not a finished document.

Concrete Example​

ADR-0034: Adopt idempotency keys for public POST endpoints

Status: Accepted, 2026-02-20

Context. Our public API receives duplicate POSTs from clients retrying on timeout. We have observed duplicate charges twice in 90 days. The payment team handles this manually via a deduplication job that runs nightly - fragile and after-the-fact. Alternatives considered: (a) server-side fingerprint dedup; (b) require clients to use PUT with natural keys; (c) require an explicit Idempotency-Key header per Stripe's convention. Option (b) breaks existing clients; option (a) adds hidden behavior clients cannot reason about.

Decision. Require an Idempotency-Key header on all public POST endpoints that create resources. Store the first response for 24 hours keyed by (account, key). Return the stored response on duplicates.

Consequences.

  • Positive: idempotent retry is explicit; duplicate-charge incidents become a client contract violation, not a silent defect.
  • Positive: ops can stop the nightly dedup job in Q3.
  • Negative: clients must adopt the header; partners with older SDKs need 90-day notice and a fallback window.
  • Negative: storage cost for idempotency records; estimated +0.5% on primary Postgres, reassessed at 3 months.
  • Risk: clients may reuse keys across different requests; we must reject on payload mismatch and document the failure mode.

Every section earns its place. None is optional.

Common Confusion / Misconception​

"Decisions without consequences." An ADR that lists only benefits is propaganda. If you cannot name at least one real cost, you have either not thought about it or have not understood the tradeoff. Send it back.

"Context = history." Context is not a timeline of everything the team did. It is the operative constraints right now plus the alternatives seriously considered. Trim anecdotes.

"Consequences = a to-do list." Consequences are what becomes true about the system. "We will update the docs" is a followup, not a consequence. Put followups in a separate section.

How To Use It​

When writing:

  1. Start with Context. If you cannot state the forces, you are not ready to decide.
  2. Write Decision second, in one or two sentences. If it is longer, split the ADR.
  3. Write Consequences third, and force yourself to name at least one negative and one risk. A "no negative consequences" ADR is a draft.
  4. Re-read Context last. Does the decision actually address the forces named? If not, the Context or the Decision is wrong.

When reviewing:

  • Ask: if I had to supersede this decision in two years, what would I need from this record? Then check whether it is there.

Check Yourself​

  1. For one of your team's recent ADRs, delete the Context and re-read. Is the Decision still interpretable? (Probably not.)
  2. Name one ADR pattern-of-failure you have seen: missing context, missing consequences, missing decision. What was the downstream damage?
  3. If Decision is empty, what does that imply about the review meeting where it was discussed?

Mini Drill or Application​

Critique an ADR (yours or one found on GitHub). For each of the three sections:

  • give it a score 1-3: (1) present in name only, (2) present but weak, (3) load-bearing
  • identify one specific sentence that should be added, removed, or rewritten
  • write a single-sentence verdict: is this ADR safe to rely on for a future supersede?

Read This Only If Stuck​