The Architecture Decision Record That Records the Decision But Not the Duress

The ADR is supposed to be institutional memory. What actually gets merged is the clean version. Six months later, a new engineer reads a confident decision and reverse-engineers a rationale that never existed.

SYMPTOM // REVERSE-ENGINEERED RATIONALE

A team I’ll call the Marlow group had a service that handled payment webhooks. Single-tenant Postgres instance, no read replicas, no connection pooling, and a max connections setting that the original engineer had guessed at. When the service started timing out under load, the team wrote an ADR proposing a migration to a connection pooler in front of a multi-tenant cluster. The ADR was clean. Context section, decision section, consequences section. Alternatives listed. Approved. Also fiction.

The migration had been proposed because the original engineer — the one who guessed at the max connections setting — had left three months earlier, and the person who inherited the service didn’t know how to tune Postgres. The ADR framed this as a scaling decision. The actual context was a knowledge gap and a deadline. The dissenting voice in the RFC thread — a backend engineer who had argued for trying pgbouncer on the existing instance first — was overruled in a meeting that wasn’t referenced in the document. Their comments were in the thread. But the reply that closed the discussion — “Let’s go with the migration, we can revisit pooling later” — was timestamped 11 PM on a Friday. The engineer who objected went on vacation the next morning. By the time they came back, the ADR was merged.

Six months later, a new hire read the ADR and concluded that the team had deliberately chosen a multi-tenant architecture for long-term scalability. They built new services on the same pattern. When one of those services hit the same connection exhaustion problem, they assumed it was a different bug — because the ADR said the pattern was chosen for scaling, not because of a knowledge gap. The rationale they inherited was a story the team told after the fact. It was not the reasoning that produced the decision.

I’ve watched this pattern break at least four teams. Not the Postgres part — the documentation part. The ADR, the RFC thread, the technical strategy document: these are supposed to be the institutional memory of why we chose what we chose. But the artifact that gets merged or approved is almost always the clean version. The dissenting comments, the “I disagree but won’t block” caveats, the concerns raised in a side channel that never made it into the thread — that’s the actual decision context. And it’s the part nobody writes down.

§ 1 — WHAT THE ARTIFACT HIDES

The function of an ADR is to preserve decision context across time and team turnover. The failure mode is that the artifact preserves the outcome but strips the duress. Duress is the pressure under which the decision was actually made: the deadline, the missing expertise, the political constraint, the person who disagreed but was too tired to fight. Strip the duress and you leave behind a decision that looks rational and deliberate. The next reader assumes it was.

Google’s SRE book dedicates an entire chapter to postmortem culture and the principle that documenting what actually happened — including the messy, uncomfortable, politically charged reality — is the only way an organization learns from failure rather than repeating it with better confidence. The Google SRE book’s postmortem culture chapter is the closest established parallel to this problem: the gap between the clean summary and the actual timeline is where institutional knowledge dies. The same principle applies to ADRs. A postmortem that records the outage but not the contributing factors teaches nothing. An ADR that records the decision but not the duress teaches the wrong thing.

The specific signals of suppressed dissent are in the artifact itself. You just have to know what to look for.

§ 2 — THE FORENSIC READ

Pull the last five merged ADRs or approved RFCs from your team’s repository. For each one, inspect these four signals:

1. Comment threading depth versus final document depth. Count the nested reply levels in the discussion thread. Then check whether the concerns raised in the deepest branches appear in the final document. If the thread has four levels of nested replies and the ADR’s Alternatives Considered section has two sentences, you have a gap. The deepest branches are where the real disagreement lives — that’s where someone stops arguing with the proposal and starts arguing with the person who made it. If that content doesn’t surface in the ADR, the document is hiding the decision’s actual shape.

In the Marlow group’s ADR, the thread had a branch that went five levels deep on whether pgbouncer in transaction mode would break prepared statements. The final ADR’s alternatives section said: “Connection pooling was considered but deemed insufficient for projected scale.” No mention of prepared statements. No mention that the objection was technical, not strategic. The sentence reads as if pooling was evaluated and dismissed on its merits. The thread shows it was dismissed because the person who understood the tradeoff went on vacation.

2. Edit timestamps versus comment timestamps. Most RFC tools and wiki platforms expose edit history. Compare the document’s last edit time to the last substantive comment. If the document was edited after the last comment without that comment’s content being incorporated, you’re looking at a decision that was finalized by editing, not by discussion. The edit is where the author quietly resolved the disagreement by removing it from the record.

This is the most common suppression pattern I see. Someone raises a concern. The author agrees to “address it” in the document. The edit that follows doesn’t address it — it reframes it. The concern about prepared statements becomes “transaction mode limitations.” The concern about timeline pressure becomes “phased rollout recommended.” The original objection is gone. In its place is a passive-voice recommendation that nobody is accountable for.

3. The gap between Approved and the last substantive objection. Measure the time between the final substantive technical objection and the approval. If it’s under 24 hours, and especially if it’s under 4 hours, the approval happened before the objection could be resolved. This doesn’t mean the decision was wrong — it means the process didn’t include the objection. The objection existed, was recorded, and was overridden by time pressure, not by argument.

In a healthy process, the gap between the last objection and the approval reflects the time it took to address the objection. In a broken process, the gap reflects the time it took for the objector to give up. You can’t tell the difference from the document alone — but if the document doesn’t mention the objection at all, you can infer which one happened.

4. The conspicuous absence of certain voices. Cross-reference the list of people in the meeting where the decision was finalized against the list of people who commented in the RFC thread. If someone was in the meeting but not in the thread, their position on the decision is unrecorded. If that person is the most senior engineer on the team, or the person who owns the system the decision affects, their silence in the artifact is a signal. They may have agreed. They may have been overruled. You can’t tell — and that’s the problem.

The absence is the hardest signal to detect because it requires knowing who should have been in the thread. But it’s the most reliable indicator of duress. When the people who have the most context on a decision don’t appear in the written record, the written record is incomplete. The decision was made somewhere else. The document is a backfill.

§ 3 — THE REVERSE-ENGINEERED RATIONALE

Here’s what happens six months later. A new engineer — call them the inheritor — reads the ADR. They see a clean decision with a context section, alternatives, and consequences. The document reads as if the team evaluated the options and chose deliberately. The inheritor doesn’t have access to the thread. Or the thread has been archived. Or the tool has changed. Or the comments are in a Slack channel that was deleted when the workspace was reorganized. The inheritor does what engineers do: they reverse-engineer the rationale from the decision.

If the ADR says “We chose a multi-tenant architecture for long-term scalability,” the inheritor assumes the team had evidence of scaling problems. They build on that assumption. They extend the pattern. They cite the ADR in their own RFC as precedent. The original decision was made under deadline pressure by someone who didn’t know how to tune a database. The inheritor’s new decision is made under no pressure by someone who thinks they’re following a proven pattern. The fiction has become infrastructure.

This is how teams accumulate architectural decisions that nobody can explain. Not because the original decision was bad — it might have been fine under the circumstances. But because the circumstances weren’t recorded, the decision can’t be evaluated, only inherited. Every inherited decision narrows the space of what the team considers possible. And none of them can be questioned because none of them have a recorded rationale that can be examined.

The result is a codebase that feels inevitable. Why is everything multi-tenant? Because the ADR said so. Why did the ADR say so? Because that’s what we decided. The circularity is invisible because the duress that broke the circle was stripped from the record.

§ 4 — THE SAME FAILURE IN NARRATIVE PLANNING

This isn’t an engineering-only problem. Any team that maintains long-form written decision records faces the same core issue: the artifact that survives is the one that’s been cleaned up, not the one that’s true.

Consider a writing team that maintains editorial outlines — plot decisions, character arc rationales, structural choices documented for collaborators and for future reference. The same suppression pattern appears. The outline says “We chose a non-linear timeline to create thematic resonance between the two storylines.” The actual decision was made because the first draft had a pacing problem in act two and the editor suggested restructuring rather than rewriting. The outline doesn’t say that. Six months later, a collaborator reads the outline, assumes the non-linear structure was a deliberate artistic choice from the start, and builds subsequent plot decisions on top of a rationale that was never artistically intended — it was a fix that got promoted to a principle.

The Authors Guild’s guidance on writing practices emphasizes preserving the original voice, thinking, and creative reasoning that shape a work — the reasoning behind a decision is part of the work, not just the output. When editorial decision records strip that reasoning, they strip the same thing a duress-free ADR strips: the context that makes the decision legible to the next person who has to build on it.

The bridge is narrow and honest: teams that use AI novel writing software that preserves the decision trail alongside the draft face the same temptation to clean up the artifact. The tool can record the reasoning, the alternatives considered, and the disagreements — but only if the team treats the decision record as part of the work, not as paperwork to be filed after the work is done. The failure mode is identical whether the artifact is an ADR in a git repo or a narrative outline in a writing tool: the cleaned version becomes the official version, and the real context is lost.

§ 5 — ONE REVERSIBLE EXPERIMENT

For the next ADR your team writes, add a section called Decision Context — distinct from Context, which describes the technical situation. Decision Context records the conditions under which the decision was made. It answers four questions:

What deadline or pressure was active when this decision was finalized? Not the project deadline — the decision deadline. If the decision had to be made by Friday because someone was going on vacation, that’s the context. If it had to be made before a funding round, that’s the context. If there was no pressure and the team had unlimited time, write that — it’s the most important signal of all.

Who disagreed, and what was their objection? Name the objection, not the person. “An objection was raised that transaction-mode pooling would break prepared statements used by the webhook consumer. The objection was not resolved before approval.” That sentence tells the next reader everything they need to know: the decision was made with an unresolved technical concern, and the concern is specific enough to investigate.

What was the strongest argument against this decision? Not the alternatives that were considered — the strongest case for not doing it at all. If the ADR can’t articulate the best argument against itself, the ADR wasn’t written by someone who understood the tradeoff.

What would make us revisit this decision? The conditions under which the decision should be re-evaluated. Not “if requirements change” — that’s meaningless. “If the webhook service exceeds 500 connections per second, the pooling decision should be revisited because the current rationale was based on projected load of 200 cps.” That gives the inheritor a concrete test, not a vague disclaimer.

The experiment: add the Decision Context section to one ADR. Don’t mandate it for all ADRs. Don’t change the template. Don’t announce a process change. Write one ADR with the section and see what happens when the next engineer reads it. If they ask better questions about the decision, the section earned its place. If nobody reads it, you have a different problem — your ADRs aren’t being read at all, and the duress issue is downstream of a documentation culture that doesn’t exist yet.

Rollback: if the section creates friction — if people spend more time arguing about what counts as duress than making decisions — remove it. The section is a diagnostic, not a process. Its value is in what it reveals about the decision, not in its compliance as a template field. If it becomes a checkbox, it’s failed. A good Decision Context section reads like a person writing honestly about what happened. A bad one reads like a form being filled out. The difference is obvious.

§ 6 — THE ARTIFACT IS THE EVIDENCE

The ADR is not a record of what the team decided. It’s a record of what the team was willing to write down about what they decided. Those are different things. The gap between them is where the next team’s confusion lives.

When you read an ADR, read it forensically. Look for the threading depth that didn’t make it into the summary. Look for the edit that came after the last comment. Look for the approval that came too fast. Look for the voices that aren’t there. The document is telling you what happened — but it’s telling you by what it omits, not just by what it says.

And when you write one, write the duress. Write the deadline. Write the objection that wasn’t resolved. Write the argument against your own decision. The clean version is the one nobody learns from. The messy version is the one that saves the next engineer from building on a rationale that never existed.

The ADR is not a record of what the team decided. It’s a record of what the team was willing to write down about what they decided.