Nobody remembers why: recording architecture decisions so they can be reopened

An architect joins an organisation and notices an oddity in its information system. Every exchange with billing goes through a layer of interfaces built around an old software package, while the rest of the estate has been modernised. They ask around. The answers are that “it was decided before”, that “the vendor was in trouble at the time”, perhaps that “the budget never came through”. The architecture diagram is up to date. It shows exactly what exists. It says nothing about what was ruled out, or why.

Two attitudes remain, and both are costly. The first is to respect what exists out of caution: since nobody knows why the choice was made, nobody dares undo it. The second is to challenge it on principle: since nobody can defend it, it looks arbitrary. The organisation swings between these two reflexes depending on who is in post, and the same debate is replayed with every new arrival.

A diagram describes what was built; it does not say what could have been built instead. Recording a decision is not about proving that it was taken, but about making it possible to reopen it on the day its reasons no longer hold — and only on that day. A decision register that does not help answer that question is merely an archive.

What disappears first

An architecture decision leaves lasting traces: a system in production, data flows, contracts. What disappears is everything that surrounded it when it was taken.

The question. The problem the decision set out to solve quickly merges with the solution chosen. A few years later, nobody knows whether the interface layer answered a need for isolation, a deadline, or a skills gap.

The options ruled out. They leave no trace in the system. Yet they are what give the choice its meaning: a decision is only understood by knowing what it was preferred to.

The assumptions. Expected volumes, the durability of a vendor, the state of regulation, the skills available, the intended lifetime of the system. These are the conditions that made the choice reasonable. They are seldom written down, because at the time they went without saying.

The trade-offs. What was knowingly given up by deciding this way. A forgotten trade-off ends up looking like a design flaw, and successors spend time “fixing” what had been accepted with eyes open.

Both attitudes described above stem from the same gap. A decision whose assumptions have been lost can be neither seriously defended nor seriously challenged.

Why existing registers fall short

Many organisations already keep some form of register: committee minutes, architecture documents, sometimes short decision records in the format discussed in the article on architecture governance. The format is not the problem. The conditions under which the register is filled in are what empty it of its use.

The record is written after the decision, to justify it. It is drafted when the case goes to committee, once the choice has been made. The “options considered” section then holds the chosen option and two options built to be dismissed. A future reader cannot tell a serious alternative from a straw man.

It records the conclusion, not the conditions. The decision is stated with care; the assumptions behind it are missing or reduced to a generic sentence. Yet that is the only part that would make it possible, later, to tell whether the decision still holds.

It only covers what goes through committee. The most structuring decisions are often taken elsewhere: in a tender document, a budget trade-off, a contract signed by a business unit. Others are taken by nobody: a postponement renewed year after year ends up becoming a choice. The register then describes part of the architecture, not the part that weighed most.

It is edited rather than replaced. When a decision changes, the record is corrected. The history disappears, and with it the ability to understand why the organisation changed its mind.

Nobody reads it again. A record that is never opened after the committee becomes a compliance document. It proves that a procedure was followed, not that the decision is still valid.

What a decision must record to be reopenable

The drafting criterion changes everything. A record written to be approved tries to convince. A record written to be reopened tries to give a future reader, who knows neither the context nor the people, what they need to judge whether the choice still holds. That takes seven elements, two of which carry most of the weight.

The question, framed as a problem. “How do we keep billing running during the channel rebuild without depending on changes to the package?”, rather than “implementation of an API layer over billing”. A well-framed question makes it possible to recognise the day it no longer arises.

The options genuinely considered. Including doing nothing, which is almost always a real option and almost never written down. For each, the precise reason it was not chosen. If an option was not seriously studied, it is better to say so than to invent it after the fact.

The decision. This is the part everyone already writes; it needs no comment.

The assumptions, dated and verifiable. This is the heart of the record. Each assumption is a fact about the world on which the choice depends: “the vendor supports the current version at least until a given date”, “billing volumes stay in the same range”, “the team that knows this package stays in place”. A useful assumption can be checked: at any given date, one should be able to say whether it is still true.

The accepted trade-offs. What the decision costs, and who bears it: an extra layer to maintain, slower billing changes, a rare skill to retain. Writing them down protects the decision from the criticism of those who will discover these costs later without knowing they had been weighed. The same logic applies to debt that is deliberately never repaid.

The review condition. This is the other decisive element. A review date is not enough: a decision reviewed every year for no particular reason is usually renewed without examination. The review condition is an observable signal drawn from the assumptions: an end-of-support announcement, a volume threshold crossed, the departure of the team concerned, a regulatory change. As long as the signal does not appear, the decision need not be reopened; as soon as it does, it must be.

The owner. A person or function with the authority to reopen the decision, and whom the signal must reach. Without an owner, a broken assumption is noticed by everyone and handled by no one.

Written this way, the record stays short. One page is almost always enough. It takes less writing than candour: it is harder to write “we think the vendor will last three years, without being sure” than to produce a sales pitch.

It is the assumptions that need tracking

Most architecture decisions do not become wrong. The context that made them right changes. A vendor is acquired, a regulation is revised, a team disperses, volumes double. The decision stays in place, frozen in the system, while its foundations have shifted.

A register organised by decision handles this poorly. When an event occurs, the useful question is not “what does this decision say?” but “which decisions rested on what has just changed?”. Answering it requires assumptions to be recorded so that they can be found, and a single assumption to be linked to every decision that depends on it.

The example shows what the register brings when kept this way. The decision to keep billing, the decision to postpone the reference data rebuild and the decision to build the portal on the existing interface were not taken by the same people, nor in the same year. Yet they rest on the same assumption. Without a register, the end-of-support announcement would be treated as a billing issue; the portal and reference data teams would discover the problem later, at their own expense.

This reading has a practical consequence: assumptions are best written consistently from one record to the next, with the same words for the same facts — the name of the vendor, the version, the regulation concerned. The humblest search tool is then enough to answer the question. It is also this link that makes possible the exercise of testing principles against past decisions: a decision whose reasons are written down can be re-read; a decision reduced to its conclusion can only be observed.

Replace, never rewrite

A recorded decision is not corrected. When it is revised, a new decision replaces it, with its own question, options and assumptions, and an explicit reference to the one it supersedes. The old record remains readable, marked as superseded.

This rule has two effects. It preserves the history of the reasoning, which is often more instructive than the end state: an architecture is understood by seeing which steps it went through, just as a roadmap is understood by looking at its transition states. It also changes what a revision means. Replacing a decision is not admitting a mistake; it is acknowledging that its assumptions have stopped being true. The register makes it possible to tell a badly taken decision from a well-taken decision in a context that has changed.

Two categories of decision deserve particular attention.

Decisions not to act. Keeping a system, postponing a migration, not repaying a debt. They commit the organisation as much as any other, and they have assumptions, often more fragile ones. They are also the ones most easily renewed without examination. The conditions for retiring a system follow the same logic: written at go-live, they turn an indefinite postponement into an owned decision.

Reconstructed decisions. When a register is created, most of the architecture already exists, and its reasons are lost. Reconstructing everything is neither possible nor useful. But when an old choice becomes an issue — because someone wants to undo it, or because it turns out others depend on it — it is worth writing a record for it, stating clearly that it is reconstructed and that its assumptions are inferred rather than known. An inferred assumption, flagged as such, is better than no assumption at all.

What to record, and what to leave out

A register that tries to cover everything ends up like overlong lists of principles: nobody reads it. Two criteria are usually enough to decide whether a decision deserves a record.

The cost of going back. A decision that can be undone in a few days, within a single team, does not need to be recorded at the level of the organisation. A decision that commits a contract, a shared platform, reference data or a hosting arrangement does, because it will not be undone without significant effort.

The number of those who depend on it. A decision that constrains teams other than the one that took it must be readable by them, and by those who will succeed them.

Two housekeeping rules complete these criteria. The record is written by those who decide, when they decide, not reconstructed afterwards by an architect from meeting minutes. And it lives somewhere it can be found without knowing its author: close to the teams’ work, but accessible to everyone the decision affects.

Changing one’s mind without disowning oneself

The decision register is often presented as a memory tool. That is true, but it is its least important function. Its real use is to make revision legitimate. An organisation that does not keep the reasons for its choices has only two options when facing an old choice: keep it because it exists, or undo it because nobody understands it any more. Either way, the decision rests on nothing.

A decision that records its question, its options, its assumptions and its review condition escapes that dilemma. It can be kept knowing why, or replaced knowing what changed. And the organisation can change its mind without anyone having to admit a fault: it is enough to show that the assumption behind the choice is no longer true. That is what a well-kept register makes possible, and it is the question to ask of one’s own: reading it, could you say which decisions would have to be reopened tomorrow if the main vendor in your information system changed its strategy?