Comprehension debt
Free. No email required.
Work getting done faster than you understand it.
- Comprehension debt is the gap between what your systems actually are and what you actually still know about them. Addy Osmani named a narrower version of this, scoped to engineers reading their own code; I use it wider, because on a team running agents, the debt shows up in anyone expected to answer for a system, not just the people who used to write it by hand.
- I borrow Ward Cunningham's technical-debt idea and Martin Fowler's quadrant of it (deliberate or inadvertent, prudent or reckless), but that grid has no box for two things I keep running into: sliding between quadrants without noticing, and a region that's just unknown-unknowns, work you forgot existed at all.
- There's no version of this where the debt gets fully paid down. Nobody gets back to fully understanding these systems at the speed agents write code now. Comprehension is something you keep managing.
- The practice that actually pays it down: periodic walkthroughs. Sit with one agent and have it explain the system end to end, never just the code, so at least one part of its account gets checked against something outside itself, instead of resting only on what it says.
- Insolvency is the point I watch for: nobody — not the person, not the agent, not a test suite — can answer for what a system actually does anymore.
- This is also why the AI Operating Model lists delivery-state visibility as a standing practice: pay down comprehension debt, never rubber-stamp. The same balance, described at team scale.
What's Behind This Card
This essay grew out of an earlier, shorter piece. The fuller argument is at Comprehension Debt Is a Debt.
This is one of six cards today. The field guide maps seventeen practice areas, and I'm growing this set as each one earns its own depth.
This is a fit question, not a recipe. Where your team actually sits against this list, and what that's costing, is what the Engineering Ways of Working Diagnostic is built to find.