Description
A team spends months decomposing a system into bounded services. The reasoning lives in a whiteboard session, a chat thread and the architect's memory. Two years later an assistant is asked to add a feature spanning two of those services and takes the cheapest route: it pulls the shared logic back into one place and calls across the boundary directly. The code works. The tests pass. The decomposition has been undone, and nothing anywhere registered that anything happened.
An architectural decision is two things: the shape, and the reason for the shape. Only the first is in the code. The second used to survive by other means. A senior engineer who remembered the argument would see new code drifting outside the intended structure and quietly move it back, and every one of those small corrections was an undocumented decision being enforced by hand.
That mechanism is weakening from both ends. The share of changes that are restructuring rather than addition has been falling, so less of the correcting work happens at all, and the people who carry the reasoning are themselves a decaying store. Studies of what leaves a project when people do find that the loss goes well past who can operate the system: rationale decays progressively, including through internal moves, long before anybody notices it has gone.
Which leaves a specific kind of debt. Not debt in the code and not in anybody's calendar, but in what was never written outside a head: the goals and constraints that were supposed to guide the system. People and agents both need that externalised to work safely, and only one of the two can compensate by asking around. What this dimension scores is whether a decision from two years ago is findable where the work happens, and whether anything notices when the code stops obeying it.
The five levels
One question decides which rung you are on: does the system itself act on this, or does a human have to choose to? Each rung carries a tell: the thing that would settle it, so the score is something you checked rather than something you agreed with.
- 1
Blind
There is no written record of architectural decisions. Why a boundary sits where it does, why one library won over another, why a service was split: none of it is written down, so the answer to any of those questions is a person, and it changes when that person does.
The tellSearch your repositories for anything written about a boundary you know was argued over. If the search returns nothing, and the only source is a person who has to be tracked down, you are here.
- 2
Tacit
The decisions live in the handful of people who were in the room. They catch violations in review, they explain the history to new joiners, and the story stays consistent because it is the same people telling it. Nothing outside them holds it, so an agent has no access to it at all.
The tellAsk two long-standing engineers why a major boundary exists. If they agree in detail and neither can point to where it is written, the memory is in the people.
- 3
Visible but inert
Decisions are recorded, often well: a decision log, records in the repository, a wiki with dates. Nothing verifies that the code still matches. A change that quietly reverses a decision merges like any other, so the record stays accurate about what was decided and silent about what is now true.
The tellTake a decision record from two years ago and check whether the code still obeys it. If it does not, and nothing anywhere noticed, the record is history rather than a constraint.
- 4
Acted on
Decisions are captured where the work happens, in version control beside the code, and they are used. A change touching a decided boundary meets the record, in review or in a check, and reversing a decision is a deliberate act with a date rather than a merge that happens to differ.
The tellFind the last change that went against a recorded decision. Something pointed at the record before it merged, and the outcome was either a refusal or a new record superseding the old one.
- 5
Durable
The record stays true while the system changes. Decisions are superseded rather than left to rot, new ones arrive with the change that implements them, and the set stays small enough and current enough that people read it instead of asking, which is the only test that matters.
The tellLook at the dates on your decision records. Recent ones present, and old ones carrying supersessions rather than silence, means the practice is alive rather than a folder somebody made once.
What this dimension rests on
The five levels are observed, from client engagements, and no paper produced them. What the research below establishes is why this dimension is worth scoring at all. No links: the citations carry enough to find them, and they stay findable after a link would have rotted.
Robillard et al., Turnover-Induced Knowledge Loss in Practice (ESEC/FSE 2021)
Studied what leaves a project when people do, and found the loss goes well beyond who can operate the system. Rationale decays progressively, including through internal moves, long before anyone notices it is gone.
Storey, From Technical Debt to Cognitive and Intent Debt (2026)
Argues that alongside debt in the code there is debt in what was never externalised: the goals and constraints that should guide a system. Both people and agents need that rationale outside somebody's head to work safely.
Where this came from
This dimension has a published article behind it, written from client engagements rather than from a greenfield repository.
Read the article on Decision memory (ADRs) →
How to climb this dimension is not written yet. It is the next thing this page grows, and saying so is more useful than a paragraph of generic advice.