ADR Recovery

Overview

You introduce the practice today. The decisions were made over the previous several years, by people who may have left, for reasons nobody wrote down.

This topic is about reconstructing them — and about the discipline that separates a useful reconstruction from a fabrication, which is the whole difficulty.

Why it is worth doing at all

Module 8’s size argument: past about a hundred and fifty engineers, nobody holds the whole picture. The accumulated effect is that every cross-cutting change begins with an archaeology phase, and the same architectural questions get re-litigated because their answers were never recorded.

Recovery attacks that directly. But it is expensive and the value is uneven, so the selection matters more than the technique.

Recover the decisions that are currently being questioned. A record that stops a recurring argument pays for itself immediately. A record of a settled decision nobody disputes is archaeology for its own sake.

That one heuristic does most of the work: follow the arguments, not the architecture.

The method

graph TD
  A["<b>1 · Pick decisions being<br/>re-litigated now</b>"] --> B["<b>2 · Reconstruct the<br/>constraints of the time</b><br/><i>not today's</i>"]
  B --> C["<b>3 · Interview whoever<br/>was there, separately</b>"]
  C --> D["<b>4 · Mark it reconstructed</b><br/>with evidence and confidence"]
  D --> E["<b>5 · Record 'no rationale<br/>found' where true</b>"]

  classDef first fill:#5B8FB9,stroke:#4A7A9E,stroke-width:2px,color:#ffffff
  classDef hard fill:#E8A33D,stroke:#C4832A,stroke-width:2px,color:#ffffff
  classDef honest fill:#7D9A4E,stroke:#5F7A38,stroke-width:2px,color:#ffffff
  class A first
  class B,C hard
  class D,E honest

Five steps. The second is where most recoveries go wrong, and the last two are what make the output trustworthy rather than merely plausible.

Reconstruct the constraints of the time. The hard step. A decision that looks indefensible today was often correct against constraints that no longer exist — a dependency that has since been removed, a deadline that has passed, a team that no longer exists, a product requirement that was dropped. Judging a past decision against present constraints produces a record that is both wrong and insulting to whoever made it.

Sources that help: the commit history around the change, the dates, what else was happening that quarter, and whatever written trail exists in tickets or chat.

Interview whoever was there, separately. Module 8’s technique: the differences between accounts are informative. Two people remembering different reasons usually means there were two reasons, or that the real reason was something neither wants to state.

Mark it reconstructed. Non-negotiable. A recovered record carries a visible label — reconstructed from commit history and two interviews; confidence moderate — and never presents itself as contemporaneous. A reconstruction passed off as a record is a fabrication with a template, and when it is found to be wrong it discredits the entire set.

Record “no rationale found” where that is the truth. The most useful finding and the most politically delicate.

When there was no decision

Some things turn out to have no reasoning at all. Nobody chose; it accreted. A boundary exists because of the order two people happened to work in, and Module 8’s Conway analysis predicts exactly this.

Recording that is valuable: it tells a future engineer that the arrangement is not load-bearing, which is precisely what they need to know before changing it. A boundary with a recorded reason must be respected; a boundary with “no rationale found; appears to follow the extraction order” can be reconsidered on its merits.

The delicacy is in the framing. “No rationale recorded” is a statement about the documentation. “This was done badly” is a statement about colleagues, it is probably unfair given the constraints of the time, and it will cost you the cooperation you need for the next twenty records. Module 8’s consistency point applies: you are building a record, not an indictment.

Where AI helps, and where it does not

Module 7 covered this and it applies directly. A model pointed at a repository will propose candidate rationales quickly — it can read the code, the history and the structure, and generate plausible reasons a boundary exists.

Treat the output as hypotheses to verify, not findings. It is confidently wrong in ways that are hard to detect precisely because the output is plausible, and a reconstruction is the worst possible place for a fluent guess. The verification is a human who was there, and where no such human exists, the honest status is “no rationale found”.

What it is genuinely good for: speed on the mechanical part — enumerating what decisions appear to have been made, so you can choose which to pursue.

What to recover, and what to leave

Two bodies of decisions, and they need opposite treatment.

Your own, from Modules 3 to 7 — recover all of them, now. Roughly eight: the two-service split, hosted in-region inference, retrieval over fine-tuning, the action boundary and its tiers, the four bounds on the agent loop, the eval gate with its corrected threshold, the degradation ladder, and the chunking and metadata strategy.

These are weeks old and you made them, which makes this the easy case — and it is still uncomfortable, because some of the reasoning has already faded. The Module 4 chunking decision in particular involved a chain of reasoning about context windows, retrieval precision and cost that was clear at the time and is now partly reconstructed rather than remembered. That experience is the point of the exercise: if your own decisions decay in weeks, decisions from three years ago are gone.

The twenty Go services — mostly do not. The reasoning is genuinely lost, reconstructing it would take weeks of Ivan Petrov’s time, and Module 8’s Conway analysis predicts the honest finding for most of them is “shaped by whichever team extracted this slice”. That is worth knowing once, not twenty times.

So: one record covering the extraction pattern as a whole, marked reconstructed, stating that service boundaries follow extraction order rather than domain analysis, with the evidence being the commit history and the migration’s sequence. That single record tells every future engineer the thing they need — these boundaries are not load-bearing — at a fraction of the cost.

And the exception worth the time: any service boundary that is currently being argued about. Those get individual recovery, because a record that ends a recurring argument pays for itself. Following the arguments rather than the architecture is the whole selection heuristic.

The one to approach carefully. The 2023 routing feature was switched off with no postmortem, and Module 8 established that the absence is itself the cultural finding. A reconstructed record of that decision — what was built, what degraded, what was absent — would be the most valuable document in the set and the most politically loaded. It needs Ivan’s agreement and Maya Ortiz’s sponsorship before it is written, and it should be framed as the origin of the regression gate rather than as an account of a failure.

Feeds the workbook

This is the ADR set artifact, which is meant to be uncomfortable. Mark every reconstructed record as such, and include at least one honest “no rationale found” — that entry demonstrates the discipline better than a dozen confident ones.

Check your understanding

1. Reconstruct one of your own decisions from two weeks ago without looking at your notes. What had already faded?
2. A boundary in a system you know has no recorded reason. Write the two framings — the one about documentation and the one about colleagues. Which would you file?
3. A model proposes a plausible rationale for a decision nobody remembers. What do you do with it?

---

→ Records explain. Something still has to describe how the system actually works. — The HLD and the proposal