BLOG/SOFTWARE

In scaling teams, it's decision debt that piles up, not code

In scaling teams, it's decision debt that piles up, not code

We talk about technical debt, but nobody measures the cost of decisions that were never written down. Yet in growing teams, the most expensive thing is that no one knows why something was done that way six months ago.

What is decision debt?

Technical debt is the interest you'll pay later on a shortcut you took deliberately. Decision debt is when the reasoning behind a decision isn't recorded anywhere. You can read the code, but you can't read why it was written that way.

At Termohaus, we saw that what new developers lost the most time on in their first month wasn't the codebase but hunting for the answer to "why is it like this?"

Every decision left unwritten is a meeting you'll have to hold again.

A cheap fix: short decision records

The fix isn't a heavy documentation process. For every significant decision, we keep a half-page record: the context, the options, the path chosen and the known downsides. It takes fifteen minutes to write.

The records live in the repository, next to the code. On three separate projects, we've seen that once they move to a separate wiki, nobody reads them.

Three things that make a record useful

For decision records to get read:

  1. Keep it short. We don't write records longer than half a page; a long justification usually means the decision hasn't really been made.
  2. Keep it next to the code. The record lives in the repository, beside the module it concerns; a record kept in a separate system is a dead record.
  3. Write down the downsides. Every record includes its known drawbacks; a record that lists only the upsides can't be trusted.

What we measured

The two quarters after we put decision records into practice:

15 minTime to write a decision record
-%44Questions from a new developer in the first month
%29Shorter code review time

What we learned

As teams grow, the reasoning is the easiest thing to forget. Writing it down spares the future team from having today's argument all over again, and it costs fifteen minutes.

SEE THE PROJECT

The Termohaus mobile app project

Go to project

Related Articles

Design

Why do design systems collapse in year two?

Jul 28, 2026 · 9 min
Software

The first 60 seconds in a mobile app

Jul 14, 2026 · 6 min
Strategy

Stop managing digital transformation like a project

May 21, 2026 · 10 min