Decision Archives

A platform team spends forty minutes in a design review arguing about retry strategy for a new internal service — cap attempts at two and fail fast, or back off exponentially with jitter and give the downstream dependency more room to recover. Reasonable people disagree; both approaches have real tradeoffs, and the meeting ends with a decision, a Slack thread nobody will find again, and a faint sense that this exact argument felt familiar. It should have. Seven months earlier and three repositories over, the payments team had the identical argument, reached the identical tradeoff analysis, and settled on the backoff-with-jitter approach for reasons specific to how their downstream dependency behaves under load — reasons that would have shortened this meeting to five minutes if anyone in the room had known to ask.

The frustrating part is not that the payments team’s reasoning is gone. It is not. This Library’s Volume II described the discipline that would have captured it — Decision Memory, decisions persisted as first-class, queryable records of what was decided, why, and what it superseded — and if the payments team was working inside a system that practices it, that reasoning exists right now, correctly captured, linked to the file it touched, sitting in a table somewhere. The platform team’s forty minutes were spent anyway, because a record that exists and a record that can be found are not the same thing, and nothing about capturing a decision inside one project tells a completely different team, working in a completely different repository, that it is there to be asked.

The gap capture didn’t close

Decision Memory, as Volume II defined it, solved a real and specific problem: the reasoning behind a session’s choices used to evaporate the moment the session ended, and now it does not. What it was never built to solve, because the problem sits one layer up, is discovery across a boundary the record was never scoped to cross. A decision captured inside the payments project’s session history is invisible to the platform team by default — not because anyone hid it, but because nobody outside that project has a reason to know which of dozens of repositories to search, and a keyword search of Slack or a wiki for “retry strategy” does not reach a structured decision table that a different team’s tooling wrote to a different team’s database. The record did its job. The organization around it did not do the corresponding job of making that record reachable from anywhere except the one place it happened to be written.

What org-scale ADR practice already tried

This is not a new problem, and organizations that predate agentic development have already tried to solve a version of it with the format Volume II traced back to Michael Nygard: the Architecture Decision Record. In December 2025, the UK Government Digital Service published an ADR framework meant to apply across the public sector rather than inside any one department, explicitly aimed at decisions that “cross team boundaries” — the exact failure mode this chapter opened with, at genuine organizational scale, for an institution that by its own account makes thousands of technology decisions a year. The framework was piloted across the Department for Science, Innovation and Technology and other departments before publication, which is as close to a real, dated example of cross-team ADR practice as exists in the public record.

What the framework does not describe, in its own published account, is how a team in one department finds a relevant decision made in another — no shared index, no cross-department tagging, no search. Its guidance is to “share” a decision with the rest of the organization, which is a distribution instruction, not a query capability, and distribution only reaches the people who happened to be on the list. The developer-platform world has been building toward the other half: Backstage, the CNCF-hosted internal developer platform, ships an ADR plugin that links decision records to the specific services they affect through the software catalog and lets an engineer “discover ADRs across other entities using Backstage Search” — a decision made against one service becomes findable from an entirely different one, by the person who actually needs it, without already knowing where to look. It is a narrow slice of the problem, scoped to whatever a team bothered to catalog, but it is aimed at exactly the gap the GOV.UK framework leaves open.

The decision graph — Decision Memory past one project’s fence

Volume II’s own chapter on knowledge graphs as context made an observation worth taking further: Decision Memory is graph-shaped even when it is stored as flat rows in one project’s database, because a decision links to the artifact it touched and to the decision it superseded, and “why does this look like this” is already a two-hop traversal wearing the costume of a database query. What this chapter is describing is what happens when that same shape stops being fenced to a single project’s session history and spans an organization instead — not one project’s decision log, read start to finish, but a decision graph: a structure where a decision made in service A can be found from service B, referenced by it, contradicted by it, or shown to have already settled the question B’s team is about to reopen. The primitives do not change. Decision, artifact, supersession — Volume II already built all three. What changes is the boundary the graph is willing to cross, and the query patterns that only become possible once it does.

That distinction matters because the value of a graph, as opposed to a log, was never really about storage format. A team can store every decision it has ever made as flat, well-structured rows and still have nothing but an unusually tidy per-project log if the only way to use it is to already know which project to open. The graph earns its name specifically at the moment a decision’s reach extends past the boundary where it was made — the moment the payments team’s retry reasoning becomes something the platform team’s tooling can surface on its own, unprompted, because the structure connecting them exists independent of either team remembering the other one exists.

What a graph needs that a single record doesn’t

Three capabilities separate an organizational decision graph from a well-run pile of per-project Decision Memory records, and each one is a direct answer to a way the pile, however faithfully each project maintains its own, still fails a team that isn’t the one that wrote a given decision.

The third row is easy to underweight because it sounds like a UI feature rather than a structural requirement. It is not optional dressing on top of the graph — it is the difference between having built the graph and having built something a team can actually use under deadline pressure. “Has anyone on this team decided anything about X before, anywhere, ever” is a single question with four different useful entry points — topic, system, author, currency — and a structure that only supports “browse everything from project A” has quietly reduced the organizational graph back down to the per-project log it was supposed to improve on.

The graph is only as good as what feeds it

None of this is free of the problem this volume examines directly in its next chapter, Institutional Memory, on what organizations forget and what that costs in aggregate. A decision graph is a precise answer to one slice of that forgetting — the reasoning behind a specific choice — but it inherits the larger chapter’s central failure in miniature. A graph fed by three projects out of thirty has the same blind spots as a wiki nobody kept current; it just has better data structures sitting on top of the gap, which if anything makes the gap harder to notice, because a structured, confident answer that happens to be incomplete reads as more trustworthy than an obviously stale document does.

The second honest challenge is sharper, because it is not a coverage problem at all: a decision graph nobody queries is not a neutral, wasted asset sitting quietly unused. It is an active liability dressed as an achievement, because building it took real engineering effort and produced nothing. Ikujiro Nonaka’s account of how organizations actually create and retain knowledge — already load-bearing earlier in this volume — describes tacit understanding becoming explicit as only half of a cycle; the value is not realized until that explicit record gets combined with other knowledge and internalized back into how people, or agents, actually decide. Capture is externalization. A graph nobody queries before starting new work never reaches combination or internalization at all, and the payments team’s retry decision sits in a table, correctly linked, correctly superseded when it needs to be, and completely inert — worth exactly as much as if it had never been written down, to the platform team spending its own forty minutes rediscovering it from zero.

A decision graph nobody queries has all the cost of the archive and none of the value of the memory.

The only version of this that reliably survives contact with a team under deadline pressure is the one Operon’s own field data points at: move the query from a habit someone has to remember into a default the system performs before the question is even asked. A decision graph that requires an engineer to pause, mid-design-review, and think to go search it will lose to deadline pressure most of the time, the same way any optional best practice does. A decision graph that surfaces the payments team’s retry reasoning into the platform team’s session automatically, scored by relevance to the goal already being worked, does not depend on anyone remembering it exists — which is the only property that actually matters once a decision graph has to survive a real organization’s real Tuesday.