Overview

The decision and the ask. A reader who stops after the first sentence -- which is most readers, most of the time -- still gets the one thing they actually needed; a reader who has to read further to find it either stops before they get there or resents the time it cost.

A reader who stops after the first two paragraphs still has the document's conclusion. Supporting detail sinks to the bottom, where a reader who doesn't need it can skip it.

Headings, bolded phrases, and first sentences -- read only those, nothing else, within about thirty seconds, and the decision plus the next action should both be present.

Problem, context, options considered, decision, trade-offs, and open questions. The rule: no item in Open Questions may be phrased as a decision already made (and, symmetrically, no already-decided item should hide inside it).

Every open question raised during review carries an explicit resolved-or-deferred annotation. Simply posting the document is not enough -- an RFC nobody commented on has not earned "Accepted."

It records more than one decision. An ADR is well-formed only if it captures exactly one decision with its context and consequences -- a second, unrelated decision folded in is a sign to split it.

The original text is never edited. A new ADR is written, the old one's status field updates to "Superseded by ADR-000X," and the new one states that it supersedes the old -- a link in both directions.

In the same repository as the code it governs, dated, and never edited after acceptance. Colocation ties the document's discoverability to the exact place a future reader is most likely already looking -- the code itself -- rather than requiring them to know which wiki space to search.

What, why, how verified, and where to look first. The fourth element directs a reviewer's limited attention to the riskiest part of the diff instead of spreading it evenly across every changed file.

A timeline, an impact statement, a root cause, and owned follow-ups, all in actor-neutral language. The root cause must trace to a systemic condition -- a missing safeguard, an untested assumption -- never to an individual's mistake.

A reader must be able to state the flow or structure faster from the diagram than from equivalent prose, and every name the diagram uses must also appear in the surrounding prose, and vice versa.

One diagram overloaded to answer two different readers' questions at once -- for example, a context diagram that also shows internal containers. The fix: stay at exactly one C4 level per diagram.

The keywords (MUST, SHOULD, MAY, and their negatives) carry this precise meaning only when written in ALL CAPS -- a lowercase "should" in the same document reads as ordinary English, not as the RFC 2119 keyword, so the capitalization itself is load-bearing.

Removing dilution, not content -- editing is removal, not addition. The test: every remaining sentence still reads as a complete, standalone claim, with every hedge (I think, sort of) and filler word (just, really, basically) gone.

Vocabulary, level of technical detail, and framing differ, each calibrated to what that audience needs to decide or do next. The underlying decision or fact being communicated stays identical -- it's the same truth, written twice.

The decision's stakes and reversibility -- not habit or a team's default format. A reversible, low-stakes call gets a lightweight artifact; an expensive-to-reverse, high-stakes call gets the full RFC/ADR treatment.

Dated, version-controlled, and colocated with the code it describes. A stale wiki page is dangerous, not merely outdated, because it reads with exactly the same confident, authoritative tone whether it is accurate today or two years stale -- a reader has no way to tell just by reading it.

This item is not actually open -- the parenthetical is a decision already made, misfiled as a question (co-04's rule: no undecided item stated as a decision, and symmetrically, no decided item hidden inside Open Questions). It should be promoted to its own Decision statement elsewhere in the doc, leaving Open Questions to contain only genuinely undecided items.

It fails co-06's one-decision rule -- two unrelated decisions (a database migration, a deploy-pipeline change) are folded into one record. If the deploy pipeline changes again later, the ADR's status field has no clean way to represent "half of this record is superseded, half isn't." It should split into ADR-014 and ADR-015.

This violates co-07's lifecycle rule -- a changed decision must produce a new ADR that supersedes the old one, with the old one's status field updated to "Superseded by ADR-0XX." The fix: write the new ADR recording the webhook decision, mark ADR-009's status as superseded and link forward, and update the code comment to cite the new ADR.

Co-08's colocation-and-immutability rule twice over -- it doesn't live in the repository next to the code it governs (a future reader of the payment-gateway code has no way to discover it), and "draft, WIP" in a shared Google Doc invites ongoing silent edits rather than a dated, immutable record. It should be a dated, accepted ADR file in the repository.

It fails co-09 entirely -- no what, why, how-verified, or where-to-look-first, and "see commit messages" pushes the work of reconstructing the change back onto the reviewer. For a 22-file, three-service diff, the "where to look first" element matters most: the author should name the one or two files carrying genuinely new logic, distinct from the mechanical changes elsewhere.

This violates co-10 twice -- it names an individual, and it stops at "forgot," a personal-mistake framing rather than a systemic one. A blameless rewrite asks why the deploy process didn't structurally catch a missing rate-limit check (a 5-whys chain, per Worked Scenario 20) and lands on a systemic gap -- for example, "the deploy checklist has no required rate-limit-capacity step" -- with an owned follow-up to add one.

This violates co-11's consistency rule -- Service C is named in the prose but missing from the diagram, and the diagram shows a direct call that doesn't match the prose's described event-driven flow at all. The diagram should be corrected to show Service C and the actual event-publish relationship, matching the prose exactly in both directions.

This is co-13's exact failure mode -- "should" and "should probably" leave the requirement's actual strength ambiguous, and the engineer's reading, while defensible given the vague wording, was not what the author intended. The fix: "Passwords MUST be hashed with argon2id or equivalent before storage. Sessions MUST expire after 24 hours of inactivity" -- ALL-CAPS RFC 2119 keywords stating the exact, unambiguous requirement strength.

This violates co-16's proportionality rule -- a trivially reversible, single-file rename does not need a 40-page RFC; the review attention it consumed was borrowed from a future decision that actually needed that scrutiny. A one-line PR comment or, at most, a short PR description would have been proportionate.

This fails both co-01 (the decision/outcome isn't in the first sentence) and co-02 (a reader who stops after two paragraphs has no conclusion, only retro detail). The fix: open with "Checkout redesign shipped and is meeting its SLA" as the first sentence, and move the sprint-retro detail below it, in descending order of importance.

This fails co-12 in two ways: the boxes name no technology (what is "Backend" actually built with, and what protocol connects it to "Frontend"?), and using one under-detailed diagram for both onboarding (which may only need context-level detail) and an on-call runbook (which needs real container-level detail with technology and protocol) forces one artifact to serve two different readers' questions poorly. Each container needs its technology named, and the two audiences likely need two diagrams at two different C4 levels.

After:

Decision needed today: roll back the "estimated delivery date" widget. It renders a blank date for international addresses (a timezone-parsing bug), which correlates with Tuesday's 2% checkout conversion dip. No deploy or A/B test change explains the dip -- this widget is the confirmed cause.

Root cause: the decision and the ask are stated only in the final sentence, after three paragraphs of investigation narrative -- co-01 requires both to appear in the literal first sentence. A reader scanning a busy channel is likely to miss the ask entirely.

After: add a Status: Accepted line (with a date) directly beneath the title, before Context.

Root cause: co-07 requires every ADR to carry a status field -- without one, a future reader has no way to tell whether this decision is still live, was rejected after review, or has since been superseded by a later ADR. The context/decision/consequences content alone is not enough; the lifecycle state is a required, separate element.

After: add a fourth element -- "Where to look first: fulfillment/retry_policy.py's new compute_backoff() function. The other 11 files are call-site updates threading the new backoff parameter through; this is the only file with new logic."

Root cause: co-09 requires all four elements, not three -- what, why, and how-verified alone leave a reviewer facing 12 files with no guidance on where the actual risk is concentrated, and likely to spread limited review attention evenly across all of them instead of concentrating it where it's needed.

After: "Root cause (5 whys): disk usage alerting only fires at 95% full, leaving a narrow window between alert and actual exhaustion; the on-call engineer had no earlier warning to act on while already engaged with a separate, concurrent incident. Systemic root cause: no alert exists at an earlier utilization threshold (e.g., 80%) that would give on-call time to act even while handling something else."

Root cause of the drill itself: the "before" version violates co-10 -- it names an individual and frames the cause as a personal attentiveness failure ("should have been more attentive") rather than tracing to a systemic gap (the alerting threshold itself). A blameless rewrite asks why the system didn't make the problem visible earlier, not why a person didn't notice it sooner.

After: add a Human Reviewer Queue node and an escalates to edge from Fraud Review Service to it, matching the prose exactly.

Root cause: co-11 requires every name the prose uses to also appear in the diagram, and vice versa. A reader relying on the diagram alone would conclude escalation to a human reviewer doesn't exist in this system -- a materially incomplete picture that looks authoritative precisely because it is a diagram.

After: "Consumers MUST validate the webhook_signature header before trusting the payload. Clients SHOULD retry on a 5xx response using exponential backoff."

Root cause: co-13 requires ALL-CAPS RFC 2119 keywords for unambiguous requirement strength -- "should probably" and "should ideally" leave a reader to guess whether skipping the behavior is a minor style deviation or a security gap. Signature validation is genuinely non-negotiable (MUST); retry behavior is a recommendation with room for judgment (SHOULD) -- the rewrite makes that distinction explicit instead of blurring both into the same vague register.

An RFC that refuses to ship until every conceivable question is answered never ships -- pragmatism means capturing the trade-off that matters now and naming what remains genuinely open, not achieving false completeness. Forcing a premature answer to a genuinely undecided question produces an answer nobody actually believes, which is worse for the document's trustworthiness than an honest "undecided, deferred, tracked as a follow-up."

The ADR's job is durable, cheap citability, not completeness -- the RFC it always links back to preserves the full deliberation for whoever genuinely needs it. Pragmatism here means matching each document's completeness to how often it is actually consulted: most future readers only need "what was decided and why it still holds," and making that answer cheap to get is what keeps people actually citing the decision instead of skipping the reference entirely.

It is not "always document less" -- a genuinely high-stakes, hard-to-reverse decision still gets the full RFC/ADR treatment, in full. The pragmatism is calibration in both directions: under-documenting a genuinely hard decision is just as much a proportionality failure as over-documenting a trivial one. The discipline this topic teaches is matching weight to stakes, not minimizing weight on principle.

Cohesion, in code, means a module does one coherent thing. A document trying to do four unrelated jobs at once -- deliberation record, decision record, operational runbook, onboarding material -- bundles concerns that each have a different audience, a different update cadence, and a different lifecycle; editing the runbook content risks silently changing the decision record sitting right next to it in the same file. Splitting into separate documents is the documentation equivalent of decomposing a low-cohesion module into focused ones.

An ADR recording two decisions couples their lifecycles together -- you cannot mark one superseded without the document somehow representing that only half of it actually changed, and its single status field structurally cannot hold two different lifecycle states at once. One-decision-per-ADR decouples each decision's lifecycle from every other decision's, for exactly the same reason a class doing two unrelated things resists being safely changed or replaced independently of the other thing it does.

A combined diagram couples two different readers' concerns -- an executive asking "what does this talk to" and an engineer asking "how is this built" -- into one artifact. A change relevant only at the container level (adding a new internal service) forces re-touching the same diagram a context-level reader also depends on, and vice versa. Separate diagrams at separate levels let each reader's question, and each diagram's own update cadence, change independently -- the same benefit co-16 and co-06 give the document formats themselves.