Comprehension debt: measure it, then pay it down
Your team merges more code than anyone on it fully understands. The gap has a name. This page covers how to measure it and how to pay it down.
The gap has a name
Addy Osmani coined the term: comprehension debt is the gap between how much code exists and how much any human genuinely understands. AI-assisted merges widen it. Nothing breaks on merge day; the cost surfaces later, in debugging, incident response, onboarding, and the next change to code nobody wrote.
What matters is how a team uses AI, not whether. Passive delegation, accepting output that looks plausible, erodes understanding; active inquiry with the same tools preserves it. That makes comprehension debt a ways-of-working problem. A policy memo about careful review decays as soon as delivery pressure returns; small, explicit, measured changes hold.
There is no single number for it, but there are usable proxies: the share of reviews where the reviewer can explain why the approach was chosen, the rubber-stamp rate on AI-assisted PRs, and spot-check scores on recently merged code.
How Aurora Coach addresses it
Comprehension debt lives in Aurora Coach's Engineering domain (code quality, testing, tech debt, AI-assisted development), one of six domains of team effectiveness alongside Foundation, Product, Operations, Workflow, and Alignment. The loop that pays it down has seven stages.
Sense and Analyze. Every team member contributes context. The pattern is inverted: the AI asks structured questions and the team responds in free text. The team's own words are the earliest sensor for eroding understanding; no dashboard sees a developer stop trusting themselves to debug a module. Integrations such as Aurora Coach for GitHub add quantitative signal. The AI then synthesizes the team's collective context into a SWOT and maturity assessment grounded in the team's actual situation, combined with industry best practices and academic research.
Recommend, Refine, and Commit. The AI recommends concrete next steps with rationale, implementation steps, and success criteria. Team members vote, and the team lead refines the recommendation to fit the team's reality; the AI never decides. The team commits to specific improvements, owned by the team and tracked through periods.
Execute and Re-evaluate. The team does the work in its own context, alongside delivery. Next period's analysis sees what changed: progress is visible against previous commitments, the loop continues, and context compounds.
Free-text check-ins keep the loop running whether or not the team had a good week. If review itself is your bottleneck, the code review process page applies the same loop to that problem.
Example commitments
Examples of commitments a team might make in the Commit stage, not best practices:
- A comprehension review: for AI-assisted pull requests, the reviewer explains the diff back before approving. Approval means "I understand this", not "this looks plausible".
- Label AI-assisted PRs and track the rubber-stamp rate: approvals with zero comments inside a time window the team picks.
- A weekly walkthrough rotation: one engineer walks the team through a recently merged AI-heavy area, with a spot-check question or two to confirm it landed.
What is comprehension debt?
Comprehension debt is the gap between how much code exists in your codebase and how much any human genuinely understands. The term was coined by Addy Osmani. AI code generation widens the gap fast, because code can now be produced much faster than understanding of it, and the cost surfaces later: in debugging, incident response, and every change made to code nobody on the team wrote.
How do you measure comprehension debt?
There is no single number. Teams measure it through proxies: the share of pull requests where the reviewer can explain why the approach was chosen, the rubber-stamp rate on AI-assisted PRs, and comprehension spot-check scores on recently merged code. Any one of these, tracked over a few sprints, tells you whether the gap is growing or shrinking, which is the question that matters.
Is comprehension debt the same as technical debt?
No. Technical debt lives in the code: shortcuts, outdated structure, missing tests. Comprehension debt lives between the code and the team: the code can be clean, well-tested, and still not understood by anyone who has to change it at 2 a.m. AI tools tend to reduce some technical debt signals while increasing comprehension debt, which is why it went unnamed for so long.
Pick one example commitment to bring to your team; if you want the business case first, MapROI is free, needs no signup, and produces a tailored ROI analysis in about 5 minutes.