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:
- 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.
- 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.
- 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:
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.



