ADRs Nobody Reads (And How to Fix That)

We pick Nygard or MADR, create /docs/adr/, write five records in the first sprint, and announce that decisions are now documented. We link the folder in onboarding slides. We paste the template into Confluence for visibility. We backfill two ADRs after a painful refactor and call the program mature. Then the folder goes quiet — and stays quiet — while the same debates reopen in every PR about session storage, consistency, and API shape.

The template wasn't the failure. Nobody wired ADRs into the workflow that actually moves code.

That's the rot pattern — not missing markdown, missing hooks.

Documentation Rot — Symptoms Teams Misdiagnose

The failure modes are familiar. ADRs swell to ten pages because someone confused completeness with rigor. Records land in a wiki space PMs can see but engineers never open during review. Status stays proposed forever, so the corpus has no authority. Accepted ADRs get edited in place when reality shifts, and the audit trail becomes fiction.

Teams respond by shopping templates. MADR vs Nygard vs Y-statement vs arc42 section 9 — as if the right section headings would fix trust. Templates help. They're not why your folder died.

The misdiagnosis is always "we need better documentation." The honest diagnosis is "we never decided when an ADR is mandatory, where it lives in daily work, or how supersession works in review." Format chosen; operating model skipped. Q1 enthusiasm; Q2 silence.

Load-Bearing Decisions — The Filter That Keeps the Corpus Trusted

Michael Nygard's original bar still fits: architecturally significant means structure, non-functional characteristics, dependencies, interfaces, or construction techniques — decisions that constrain what the system can become. Not every choice clears that bar.

Watch what teams actually write. ADRs for Tailwind vs Bootstrap. ADRs for "we will be cloud-native." ADRs missing for the choices that burn people: session state in the database instead of Redis, eventual consistency on orders, keeping the monolith because split timing is wrong. The folder fills with trivia and vision statements while the load-bearing middle stays tribal.

More ADRs can reduce trust.

Documentation volume is not institutional memory. A noisy corpus trains engineers to ignore the directory entirely — worse than an empty one with a clear filter.

Use a simple test before you create the next file: would a new senior engineer be confused or burned by not knowing why this was done? If the decision is trivial, reversible, and local — skip it. If reversing it would hurt multiple teams or poison the next quarter — write.

The Orders Consistency Miss

Picture a payments squad six months in. ADR-003 argues for cloud-native transformation. ADR-011 records the Tailwind adoption. Nobody wrote why order totals are eventually consistent across services.

A senior arrives, sees stale reads in support tooling, and "fixes" it with synchronous cross-service calls. Finance reconciliation breaks on the next deploy. The code showed what. Nothing in /docs/adr/ showed why eventual consistency was accepted — or what was rejected. The expensive lesson wasn't missing documentation. It was documenting the wrong decisions loudly and the right ones not at all.

The Decision Hook — Where ADRs Live in Daily Work

Discoverability is the product — not a polish pass after the template workshop.

ThoughtWorks didn't recommend source control because git is fashionable. They recommended it so the record stays in sync with the code it describes. An ADR reachable only from a wiki tab is shelfware at decision time.

The Decision Hook is the set of places engineers already look:

• Beside the service code, versioned with the change that implements it
• Linked from the PR that enacts or challenges the decision
• Referenced in review checklists when a diff touches the decision's boundary
• Marked superseded — with a link forward — when the bet changes, never silently edited

Contrast two onboarding paths. Path A: "Read our ADR wiki space when you have time." Path B: PR #884 implements rate limiting; description links docs/adr/007-rate-limit-store.md; reviewer asks whether this supersedes ADR-004's in-memory assumption. Path B is how ADRs stop being write-once/read-never.

Trigger rules beat enthusiasm. Define mandatory moments: new external dependency, consistency model change, security boundary move, anything that would make a staff engineer ask "why on earth did we do it this way?" in month six. Optional ADRs are ADRs you won't write — and a trigger list posted in #architecture doesn't count if nobody checks it at PR time. Write the list. Enforce it in review.

Supersede, Don't Edit

Immutability sounds fussy until you've watched someone "refresh" an accepted ADR and erase the reasoning that explained a production incident. Nygard's rule holds: keep the old record, mark it superseded, point to the replacement. Freshness through replacement, not revision. Git history already tells you when the story changed — if you let it.

Minimum Viable ADR — One Page Under Sprint Pressure

Nygard sized ADRs at one or two pages written to a future developer. The MADR template is a ceiling, not a floor — Context, Considered Options, Decision Outcome, Consequences is enough for most bets.

Cut the rest when the sprint is loud:

• Long vendor comparison matrices belong in spikes, not the ADR
• "More information" links without rejection rationale
• Options you didn't seriously consider

Keep what future-you can't recover from code: binding constraints, rejected alternatives with reasons, accepted downsides.

Worked Shape — API Versioning Under a Ship Date

Context: Public mobile clients can't all update weekly; billing integration is frozen until audit week.

Decision: URL-path versioning (/v1/) for public APIs this quarter; header negotiation deferred.

Rejected: Header-only versioning — ops couldn't trace routing failures fast enough during incident week.

Consequences: Route sprawl risk accepted; backward compatibility becomes a release gate; ADR-012 will revisit header strategy after audit.

That's one screen. A reviewer can challenge it in five minutes. Six months later, someone can see why /v2/ wasn't vanity — it was a deadline trade, documented before the routes landed.

Rollout Without Architecture Theater

Programs die from ceremony, missing triggers, and tooling friction — not from missing markdown. You don't need a council approval chain for every ADR. You need a default low-friction path: numbered file in repo, PR review, status moves from proposed to accepted when merged.

Treat architectural decisions like code: versioned, discussed in writing, reviewed in context, merged when the team accepts the trade. Meetings become the exception — when the reversal cost is high enough that async text isn't enough.

"Read" doesn't mean "everyone opened the wiki." It means the ADR shows up where decisions get challenged — PR comments, onboarding walkthrough of one load-bearing example, postmortems that link superseding records instead of rewriting history.

If your /docs/adr/ folder is quiet, don't run another template workshop. Pick one load-bearing decision your team re-debated this month. Write one page before the next PR merges. Link it from that PR. Mark the next reversal superseded, not edited.

That's the orders-consistency ADR you never wrote — the one that would have saved a senior from "fixing" eventual consistency on a Tuesday afternoon.