Comprehension debt is not a reading problem, it is a generation problem. Writing code forces you to produce the solution yourself, and production is what encodes understanding. Reading it back, however carefully, does not do the same work. Closing the gap before you hand agent-written code to a colleague takes active recall, not another close read.
For most of my career, comprehension was a side effect of the job. I could not ship a feature without first deciding every branch, naming every variable, and picking one data structure over its two rivals. Understanding was not something I scheduled. It fell out of the act of writing, for free, every time.
What Is Comprehension Debt?
Comprehension debt is the growing gap between how much code exists in a system and how much of it anyone can actually explain. It is not the same as technical debt, and the difference is what makes it dangerous. Technical debt shows itself: a shortcut here, a TODO there, a slow query someone flags in a retro. Comprehension debt is invisible on the same dashboard. The code is tidy, the tests are green, the PR merges, and understanding quietly drains out of the building while every metric you are watching stays fine.
The debt accrues one approval at a time. An agent proposes 200 lines, you skim them, they look reasonable, you merge. Nothing about that transaction looks risky from the outside; you reviewed the code, you did not skip a step anyone would flag. But reviewing and understanding are different verbs, and only one of them leaves you able to debug the thing at 2am. Do that a thousand times across a codebase and you get a system where every part has an owner on paper and almost no part has someone who can explain it from memory.
What makes this newly urgent, not just a restatement of “always review your code,” is the ratio. For most of software history, the fastest way to get code into a system was to write it, so understanding arrived as a side effect of production. Now the fastest way to get code into a system is to prompt for it, and understanding has to be manufactured on purpose, or it does not arrive at all. Nobody ever understood an entire system fully; that part is not new. What is new is the rate the debt compounds at, because the throughput on the add-code-nobody-understands side of the ledger just went up by an order of magnitude, and the throughput on the build-understanding side did not move with it.
This matters most at the handoff. The moment you share a diff with a colleague, or put your name on a merged PR, you are making an implicit claim: I stand behind this. Comprehension debt is what you are borrowing against every time that claim outruns what you actually verified yourself.
I have written before about the macro fix: build instruments, types, tests, observability, an agent explainer, that make re-comprehension of the whole system cheap on demand, rather than trying to hold it all in your head. This piece is narrower. It is about the five minutes right before a specific diff leaves your hands, the moment the claim actually gets made.
Why Careful Reading Doesn’t Fix This
Cognitive psychology has a name for the thing that just broke: the generation effect. Information you produce yourself is remembered better than information you merely read, even when you spend far more time reading than you would have spent producing it. A related finding, the testing effect, shows the same gap from another angle: trying to recall something and failing builds a stronger memory trace than re-reading the answer one more time. Neither effect is about effort or attention span. You can read a diff twice, slowly, taking notes, and still encode it more weakly than you would have encoded a rougher version you wrote yourself in half the time.
This is the part “review more carefully” misses. Code review used to work as a comprehension mechanism partly by accident, because the reviewer had usually written similar code before, so reading someone else’s implementation was retrieval against a model you already had, not fresh encoding. Agents remove that scaffolding. You are reading code you have no prior generation of, which means careful reading is doing the weakest kind of learning available to you, at exactly the moment the stakes, a colleague trusting your name on the change, are highest.
The fix is not more reading. It is putting a small, deliberate act of generation back between “the agent produced this” and “I am telling someone else it’s good.”
Five Rituals That Force Generation Back In
1. The pre-share quiz
Before I open a PR or paste a diff into a pairing session, I ask the agent to write five to eight pointed questions about its own change: why this branch and not that one, what happens if this argument arrives empty, which of two similar functions I’d delete first and why. Then I close the diff and answer cold. If I cannot clear most of them without looking, I am not ready to put my name on the work, and I go back in before anyone else sees it. This is retrieval practice aimed directly at the PR about to carry my name, not general study.
2. The one-block rebuild
Every diff has one piece doing the real work; the rest is plumbing. I pick that piece and try to rewrite its logic, not verbatim, just the approach, on a blank page or in my head. Then I compare my version against the real one. The gap between the two is exactly the comprehension I was missing, and it is far cheaper to close alone than to discover live when a colleague asks “why not just do X” and I have no answer.
3. Explain-back as the PR description, not a private note
I write the human explanation of the change myself, in my own words, and it becomes the actual PR description, not agent boilerplate I paste in. This makes the forcing function double as the deliverable: the retrieval practice I need and the explanation my colleague needs are the same five minutes, not two separate costs.
4. Trace order, not file order
Scrolling a diff top to bottom in file order is recognition: does this look right. Tracing it in the order it actually executes, entry point first, then whatever it calls, then whatever calls it, is generation: I have to reconstruct the causal story myself instead of pattern-matching against a script I am skimming. Conversational code review gets at the same idea from the tooling side, using an agent that has read the ticket and the diff to answer impact questions. I run the human version of it on the diffs that matter most: read by dependency, not by alphabet.
5. Reject and defend
I ask the agent what the two next-best approaches were and why they lost, then I pick the one I would actually defend if challenged, in my own words, not the agent’s. If I cannot articulate why the shipped version beats the runner-up, I do not understand the decision. I only understand the output.
The Honest Limit
None of these scale to every keystroke, and I do not run all five on every diff. I run the pre-share quiz and the one-block rebuild on anything that touches business logic or a shared boundary, and I let boilerplate pass on a plain read. The point is not to generate your way through everything the agent produces; that would erase the speed advantage entirely. The point is to notice which diffs are about to leave your hands and land in someone else’s trust, and spend the five minutes of generation only there.
One Sentence
You cannot read your way to comprehension you never generated. Before you share it, make yourself produce something, a question answered, a block rebuilt, an explanation written, and let the gap that shows up tell you whether you actually understand what you are about to vouch for.
Related
- Comprehension Debt Is Refinanceable – The broader reframe: build instruments that make re-comprehension cheap, rather than trying to hold everything in your head
- Skill Erosion Is a Choice – The same quiz-yourself and explain-back moves, aimed at long-term capability rather than a single pre-share check
- The Struggle Is the Product – Why skipping generation is a specific, nameable cost, not a vague feeling
- Conversational Code Review – Using an agent to trace impact beyond the diff, the tooling-side version of trace order
- Code Stewardship Over Authorship – Why the system around the code has to carry weight the reviewer’s memory used to carry
