There is a particular kind of friction that every engineer working on a mature system knows well. You are looking at a design that does not quite make sense. The component is there, clearly intentional, clearly load-bearing. But nobody can explain why it was done this way rather than any other way. The person who made the call has moved on. The documentation says what the thing does, not why it was chosen over the obvious alternative. So the team does the only rational thing: they work around it. They add a layer on top. They leave it alone. The original decision, reasonable or not, becomes untouchable — not because it is correct, but because its reasoning is invisible.

This is not unusual. In complex technology environments, it happens quietly over years. Decisions accumulate. Each one, made without recorded rationale, narrows the options available to the next person. What started as a series of deliberate choices becomes a set of constraints that nobody owns and nobody fully understands.

Why context disappears

The loss of decision context is rarely caused by negligence. It is structural. Technology programmes move fast, and at the moment a decision is made, the reasoning behind it is obvious to everyone in the room. The constraints were known. The alternatives were fresh in everyone's memory. The conversation that led to the conclusion felt so clear that writing it down seemed redundant.

Six months later, the people in that room have moved on to different problems. The constraints that shaped the decision may have shifted. The notes from the meeting, if they exist, describe conclusions — not the thinking that produced them. A new engineer joining the team reads the architecture and sees the what. The why is already gone.

There is also a delivery pressure effect. Early in a programme, when options are open and stakes are low, there is time for deliberate thinking. But the decisions made under the most pressure — mid-programme, when something has to change quickly — are precisely the ones whose rationale is hardest to capture afterward. The team is managing the change, not documenting it. By the time the pressure eases, the moment has passed and the reasoning is hazy even to the people who made the call.

The decisions that most need their rationale recorded are the ones made under the most pressure — which is precisely when recording feels least possible.

What happens when rationale disappears

The most visible consequence is what could be called frozen architecture. A design that nobody will change because nobody is confident enough to change it. The cost of reversing it is unknown, so the default is to work around it. Technical debt accumulates not from bad decisions but from decisions whose context has been lost. A good decision with no recorded rationale is functionally indistinguishable from a bad one, because neither can be confidently revisited.

The second consequence is repeated investigation. Every new engineer, every new team, every architecture review starts from scratch — trying to reconstruct the logic behind the current state. This is expensive work, often done under time pressure, and it frequently reaches the wrong conclusion. The reconstruction misses a constraint that was obvious to the original team but invisible in the documentation. A change gets made. Something breaks. The original decision turns out to have been more deliberate than it appeared.

The third consequence is more subtle but more damaging long-term: it erodes the confidence to make good decisions in the future. When teams have seen previous decisions cause problems because nobody understood why they were made, they become cautious about making new ones. The architecture freezes not because it is optimal, but because the cost of being wrong about an old decision felt too high. The environment becomes one where change requires a level of certainty that is rarely available.

Two paths from the same architecture decision Decision with recorded rationale leads to preserved context, confident change, faster onboarding, and revisable design. Decision without rationale leads to invisible reasoning, frozen architecture, repeated archaeology, and risk aversion. Architecture Decision Made RATIONALE RECORDED RATIONALE LOST Context preserved across team changes Assumptions visible, change is confident Design revisable when context shifts Reasoning invisible to new engineers Repeated archaeology, wrong conclusions Architecture frozen, change avoided The same decision. The only difference is whether the reasoning survives.
A decision with recorded rationale stays revisable. Without it, the same decision gradually becomes untouchable — not because it is right, but because its reasoning is invisible.

What good decision memory looks like

Good decision memory is not about documenting every architectural choice. That fails quickly. It becomes too slow to maintain, too abstract to use, and eventually nobody trusts it. The goal is not a complete archive. The goal is enough recorded context that a capable engineer, arriving a year later, can understand why the current design is the way it is and what it would take to change it.

The useful information for any significant decision is narrow. What problem was being solved. What alternatives were seriously considered and why they were set aside. What constraints shaped the choice — budget, timeline, existing systems, compliance, team capability, vendor agreements. What the known weaknesses of the chosen approach are. And under what conditions the decision should be revisited.

That last element is the one most often omitted, and arguably the most valuable. A decision record that says "we chose X because Y and Z" is useful. A decision record that says "we chose X because Y and Z, and this should be reconsidered if A or B changes" is far more useful. It converts the record from a historical document into a living signal — something that tells the next team not just what was decided, but when it is safe to decide again.

A simple decision record pattern

Architecture Decision Records — ADRs — have been a well-established practice for over a decade. The format has been described and refined by many people, and it does not need reinventing. What is worth noting is why most teams abandon the practice, and what keeps it alive in the environments where it works.

The format that tends to survive looks something like this:

Decision Record Pattern Title: A short, searchable name for the decision
Status: Proposed · Accepted · Superseded · Deprecated
Context: The problem being solved and the environment it exists in
Alternatives considered: What else was evaluated and why it was not chosen
Constraints: What shaped the decision — time, cost, compliance, existing systems
Decision: What was chosen and the primary reasons
Known weaknesses: What the chosen approach does not do well
Revisit when: The conditions under which this decision should be reconsidered

The thing that keeps ADR practice alive is not tooling — it is leadership. In environments where senior architects treat decision records as a first-class deliverable, the practice continues. In environments where they are seen as optional documentation to be written later, they do not survive the first delivery crunch.

The timing matters too. A decision record written the week after a decision is made is much less useful than one written the day it is made — or even in the meeting where it is discussed. The reasoning is freshest at the moment of decision. Waiting even a few days means the nuances that made the choice obvious have already started to blur.

Some teams keep decision records in version control alongside the code they describe. Others maintain them in a shared knowledge base. The location matters less than the discipline. What matters is that the record exists, that it is findable, and that it uses status markers — particularly "superseded" — so that a reader knows whether they are looking at current thinking or a historical record of something that has since changed.

Why decision memory matters

Architecture is cumulative. Every decision made today becomes part of the context that constrains or enables the decisions made in three years. The teams that will work on this system then do not yet exist. They will not have been in the room. They will have no access to the conversations that shaped the current state — unless those conversations were written down.

This is not an argument for bureaucracy. A good decision record takes twenty minutes to write. What it prevents can take weeks to reverse, or may never be reversible at all. The investment is small. The alternative — architecture whose reasoning is entirely embedded in the memories of people who have moved on — is one of the quietest and most expensive risks in technology.

A useful test for any architecture decision: could someone who was not in the room understand not just what was decided, but why, and when they should consider changing it? If the answer is no, the decision is not finished yet.

What to carry forward