SA-301c · Module 3

Decision Debt

3 min read

Technical debt is well understood. Decision debt is not — but it is equally corrosive. Decision debt accumulates when architecture decisions are deferred, made without analysis, or made with analysis that was never documented. The symptom is familiar: the team cannot explain why the system is designed the way it is. Every modification requires reverse-engineering the original intent. Design reviews become archaeological expeditions.

Do This

  • Track undocumented decisions in the Technical Debt Ledger — they are debt with compounding interest
  • Allocate time to retroactively document critical decisions that were made without ADRs — the cost of documentation is less than the cost of relitigation
  • Measure decision debt by counting the times the team asks "why is it this way?" and cannot find an answer

Avoid This

  • Accept undocumented decisions as normal — they are debt that compounds with every team member who cannot find the reasoning
  • Assume institutional knowledge substitutes for documentation — institutional knowledge walks out the door when people leave
  • Defer ADR writing to "when things slow down" — things never slow down, and the decision context fades with time