Decision Debt

A team inherits a service where every write goes through a queue even though the caller waits for the result. Nobody can say whether that is load protection, a workaround for a database that was overloaded in 2022, or a decision copied from another service. Removing it might fix a latency complaint or might cause an outage, so nobody removes it, and the next engineer copies the pattern into the next service because it is evidently how things are done here.

That is decision debt: structure without recorded rationale. Like technical debt it accrues silently and charges interest on every change, but the interest is paid in caution and elapsed time rather than in code quality. The system is not badly built; it is unexplainable, and unexplainable systems are modified slowly and defensively.

Why it matters

The cost appears as three measurable symptoms. Onboarding stretches — a new senior engineer takes months rather than weeks to make confident changes, because confidence requires knowing which structures are load-bearing. Changes get wrapped rather than replaced, so a component nobody understands gains a layer instead of losing one. And the same arguments recur, typically every twelve to eighteen months as the team composition turns over.

The failure that makes this worth naming is concentration. Decision debt is usually held by one or two long-tenured engineers who can explain everything. The organisation reads that as strength. It is a single point of failure with a notice period, and the debt becomes visible and expensive within weeks of their departure.

Implementation patterns

• Pay it down by archaeology on the current architecture, not on the wiki. Walk the live components; for each, ask whether anyone can state why it is that way. The list of unexplainable ones is the debt register.
• Bound the backfill. For a system of three years, expect 15 to 30 decisions that still constrain code, at roughly 2 hours each. Writing more is a documentation project with no reader.
• Mark reconstructions as reconstructions, with the date and the evidence used. An invented rationale is worse than an admitted gap, because it will be cited.
• Attach the record to the code, in the repository, so it is found by the person changing the thing rather than by someone searching a wiki.
• Record non-decisions too. "We looked at splitting this service and chose not to" is high-value and almost never written, because nothing shipped.
• Use the exit interview. The cheapest moment to extract a decade of context is the four weeks before someone leaves.

Industry example

The pattern is most visible in long-lived open codebases. Projects that record decisions in the repository — the Rust RFCs, the Kubernetes enhancement proposals, the architecture decision records many teams adopted after Michael Nygard's 2011 post — let a newcomer answer "why is it like this?" without finding a maintainer. Projects without that record depend on maintainers answering the same question repeatedly on mailing lists, and the answer degrades as the original participants move on. The difference is not documentation quality; it is whether the reasoning survives the people.

Failure scenarios

• Chesterton's fence at scale: a mechanism nobody understands is removed and takes down a path it was silently protecting.
• The inverse: a workaround for a database that was replaced in 2023 is preserved for years because removing it feels risky.
• Cargo-culting: an unexplained pattern is copied into new services, multiplying the debt.
• Consultant rewrite: an external team sees no rationale, concludes there is none, and rebuilds in a way that reintroduces the problems the original design was avoiding.
• Bus-factor discovery: the person who could explain the system leaves, and a routine change becomes a three-week investigation.

Trade-offs

Paying down decision debt costs roughly an hour per record plus the time to work out which decisions matter, and the payoff is diffuse — shorter onboarding, faster reviews, fewer repeated arguments — none of which appear in a quarterly metric. Recording everything is its own failure: a hundred records with no bar buries the ten that carry the architecture, and readers stop looking. The judgement is entirely in the threshold, not in the format.

When not to use it

A team of four on a product under a year old should not run a decision-record practice. Everyone was in the room, the system is small enough to hold in one head, and the records would have no reader. The trigger to start is the first person leaving, the second team depending on your choices, or the first time an argument is repeated — any of the three, and not before. Starting earlier produces a tidy directory nobody reads, which is then cited as evidence that records do not work.

Interview question

Q: You join as a staff engineer. The system works, the team is capable, and nobody can explain why any significant part of it is shaped as it is. What do you do in your first two months, and what do you deliberately not do?

What a strong answer covers: do not start a documentation programme. Pick the three components that are currently blocking changes and reconstruct their rationale with the people still present, marked as reconstructions. Interview the longest-tenured engineer with specific questions rather than open ones. Start writing records for new decisions immediately, since today's choices are tomorrow's debt and they are free to capture now. Name the bus-factor risk explicitly to leadership, because it is the part with a deadline.

Quick check

Quiz: What are the three observable symptoms of decision debt? — Onboarding that takes months instead of weeks, changes that wrap components instead of replacing them, and the same architectural arguments recurring every twelve to eighteen months.

Flashcard: Why is a team's "one person who can explain everything" a liability rather than an asset? — The explanation exists only in memory, so the debt is invisible while they are there and becomes urgent within weeks of their departure, usually during a change that cannot wait.