Comprehension debt: measure it, then pay it down
Your team merges more code than anyone on it fully understands. This page has three ways to measure that gap and three commitments that close it, free to copy. At the bottom, a worked example: a team lead asks Aurora Coach the measurement question, and the run ends in a merge check her team can vote on.
The gap has a name
The code can be clean, well-tested, and still not understood by anyone who has to change it at 2 a.m. That gap, between how much code exists and how much any human genuinely understands, is what Addy Osmani named comprehension debt. AI-assisted merges widen it fast, and nothing about the merge looks wrong at the time.
What matters is how a team uses AI, not whether. Accepting output because it looks plausible erodes understanding. Asking the same tools why, and reading the answer, preserves it. So this is a ways-of-working problem, and a memo about careful review decays the moment delivery pressure returns. Small, explicit, measured changes hold.
Nothing breaks on merge day. The cost surfaces later, in debugging, in onboarding, and in the next change to code nobody wrote.
Three ways to measure it, free
There is no single number for comprehension debt. There are proxies. Pick one, run it this sprint, and run the same one again next sprint.
- Explained-approval rate At approval, ask the reviewer one question: why was this approach chosen? Count the share who have an answer beyond "the checks are green". Twenty sampled reviews a sprint is enough. You do not need every one.
- Rubber-stamp rate on AI-assisted PRs Count approvals with zero comments, under a time threshold the team agrees on. Ten minutes from opened to approved is a common threshold for a non-trivial diff. Report it each sprint as a share of AI-assisted PRs, which means labelling those PRs first.
- Spot-check score on recent code Pick a service merged last quarter and ask someone who did not write it to walk the team through it. Score 2 if they can explain the design decisions, 1 if they can only describe what it does, 0 if they cannot. Two services a month gives you a trend inside a quarter.
None of them is exact. Tracked across a few sprints, any one of them answers the question that matters: is the gap growing or shrinking.
Three commitments that move those numbers
What a team might actually commit to. Take them as raw material; the numbers and thresholds only mean something once your own codebase sets them.
- A comprehension review On AI-assisted pull requests, the reviewer explains the diff back before approving. Approval then means "I understand this", not "this looks plausible". If the review queue is already the bottleneck, that tradeoff is worked through on AI code review process.
- Labels on AI-assisted PRs Nobody can count a rubber-stamp rate without knowing which pull requests were AI-assisted. Put the label in the pull request template so it is one click, not a judgement call. Labels first, then the number means something.
- A weekly walkthrough rotation One engineer walks the team through a recently merged AI-heavy area, fifteen minutes, rotating each week. Two questions from the room afterwards confirm it landed. Take the oldest area nobody has explained yet first.
What is comprehension debt?
Comprehension debt is the gap between how much code exists in your codebase and how much any human genuinely understands. Addy Osmani coined the term. AI code generation widens the gap because code can now be produced much faster than understanding of it.
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.
From measurement question to merge check: a worked example
Simulated team · Real product output The team is the seven-person platform team at Vantora Labs, a fictional Series B SaaS that funded coding agents for every engineer eighteen months ago. We scripted the inputs and ran them through Aurora Coach in production. Everything below is the product's real output.
1Sense and analyze
Every team member answers structured questions in their own words, and can take any thread further with the coach in a check-in. Below, the same debt surfaces twice: once from the lead's chair, once from the engineer who wrote the code and lost it.
The measurement question, answered
The team lead types in the question this page is built around: how do you measure how much of your codebase anyone still understands. The coach frames the incident as “the second-order consequence of the same structural shift”, code production scaled faster than comprehension, then gets practical. Start with a leading indicator: have engineers walk through the five most critical services in 15-minute sessions, and whatever they cannot explain is the gap. Then track time to diagnosis against deployment frequency; if one trends up while the other stays high, the team is accumulating comprehension debt.
The same debt from the engineer's chair
An engineer opens with a bug in a service he shipped two months ago, whose code he had to read like a stranger's. He asks whether the fix is reading every generated diff line by line, which would cost him the speed he uses agents for. The coach refuses both extremes: read the risky parts closely, and read to understand rather than to verify. Its closing line is the point of this whole page: “That encoding step is what makes it yours again when you need to debug it at 2am.”
2Recommend, refine, commit
What both chairs described separately comes back as one suggestion the whole team votes on and commits to. The AI informs the decision, it does not make it.
Explain-back, as something the team can commit to
A peer comprehension check before merging any AI-generated or complex code, opened in full: implementation approaches, action steps, success metrics, discussion questions, a one-week timeframe. The Context field does not speak in generalities: it names this team's tripled output, the pair programming that got eliminated, and the six-hour incident that traced directly to the gap those two things opened. No measure on the list above knows any of that; the suggestion exists because this team's own answers argued for it, down to the outcome it names, restored collective code ownership within four weeks. The vote buttons and Commit sit at the bottom, so the team decides.
3Execute and re-evaluate
The team runs the check alongside delivery, and the next analysis reads progress against what it committed to, while the measure you picked gets its second data point. Vantora has run one period; the trend starts when the second one lands.
This is one use case. How the full product works is on the product overview.
Not ready to change anything today? You already have the three measures and the three commitments above, copy buttons and all. If you want one improvement loop like these in your inbox each month, leave your email.
What this page cannot tell you is which of it applies to your team, this quarter. Aurora Coach works that out from your team's own words, recommends next steps with the reasoning, and the next period shows whether it held.
Both are free. The ROI mapper needs no signup and takes about two minutes. What team members write stays private to them: see AI governance.