TL;DR: The gap between what your system does and what you actually understand about it now has a name — comprehension debt — and the usual prescription is some version of "document more." That prescription fails, because documentation inherits the exact gap it's supposed to close. What pays the debt down is different: re-authoring your understanding as an evidence-linked artifact, one behavior at a time, with the uncertain parts marked as uncertain.
The pain finally has a name. Addy Osmani calls it comprehension debt: the widening gap between what a system does and what the people responsible for it actually understand about it. O'Reilly Radar picked the term up, and it's spreading through the AI-coding discourse for a simple reason — everyone building with AI recognizes it instantly. Code is now generated faster than any human reviews it. The system grows; the understanding doesn't.
I arrived at the same phrase independently before I found their writing, which tells you something about how universal the experience is. When I launched Stewie Reflect, a dozen founders replied with their own version of the same confession: it works, users pay for it, and I couldn't explain it under oath.
So the diagnosis is settled. It's the prescription I want to argue with.
The cure everyone reaches for
Read the discourse and the advice converges on three moves: review more carefully, slow down, and — above all — document more. Generate docs as you go. Keep a wiki. Have the agent write explanations alongside the code.
It sounds obviously right. Comprehension debt is missing knowledge; documentation is written-down knowledge; therefore write more of it. Case closed.
Except I've watched this fail — in my own projects and in every inherited codebase I've been handed. It fails for three reasons, and they're structural, not a matter of effort.
1. Docs are authored from inside the gap. Who writes the documentation for a system nobody fully understands? Someone who doesn't fully understand it — or an AI summarizing code whose intent it's guessing at. Either way, the document is a projection of the current level of comprehension. It records the gap; it doesn't close it. A confident paragraph about your billing flow, written by someone who never traced what happens when a renewal fails mid-downgrade, isn't knowledge. It's the absence of knowledge wearing knowledge's clothes.
2. Docs drift the moment they're written. The whole reason comprehension debt exists is that generation outpaces review. Documentation loses that same race. Every agent session that touches the code widens the distance between what the doc says and what the system does — silently, with no failing test to tell you. Six months in, your wiki is a museum of things that used to be true, and now you have two comprehension problems: the code, and the docs about the code.
3. Prose can't be verified. A sentence like "users can cancel anytime and keep access until period end" reads the same whether it's true, half-true, or aspirational. There's no way to check a paragraph. So documentation accumulates unverifiable claims, and the reader has no way to tell which statements were traced to real code and which were vibes. Reading it produces the feeling of understanding — which is more dangerous than knowing you don't.
This is why "document more" is comprehension debt's comfort food. It feels like paying the debt while actually compounding it.
What paying it down actually looks like
The fix isn't a bigger pile of prose. It's a different kind of artifact — and three properties make the difference.
Evidence-linked, not free-standing. Every claim about what the product does should point at the code that makes it true — this file, this handler, this check, at this specific commit. The link is what turns a sentence from an assertion into something inspectable. If a claim can't be traced to source, that's fine — but then it must say so. Which is the second property.
Uncertainty made explicit. This is the part every documentation effort skips, and it's half the value. Real understanding of a real system is a spectrum: things you've verified, things you believe but haven't traced, things you flat-out don't know. A document that renders all three in the same confident tone is worse than no document. The honest artifact marks them differently — supported by source, inferred, unverified — so that the unknowns stop hiding. Knowing exactly where you don't understand your product is most of the cure; the debt thrives on those unknowns staying invisible.
Behavior by behavior, not file by file. Comprehension debt is a product problem wearing a code costume. What you need to understand isn't the repository structure — it's what happens when a subscription lapses, what an admin can see, what gets deleted when a user asks. Organize the artifact around behaviors someone depends on, and suddenly it's reviewable by the person who actually owns those decisions — you — without reading every line.
Notice what this artifact is not: it's not generated repo documentation, which orients an agent in the code but grades nothing. And it's not a test suite, which verifies the behaviors someone already understood well enough to test. It sits in the layer between — owned understanding, with receipts.
Try it by hand this week
You don't need any tool to start. Pick the one flow in your product that scares you — billing, auth, data deletion. Write down every behavior you think it has, as separate claims. Then trace each claim to the code and mark it: verified, inferred, or unknown. Most people who do this find the ratio humbling — and find that the two or three unknowns they surface are worth more than the twenty confirmations.
That marked-up list is worth more than any wiki page you could generate, because it's the only artifact that tells the truth about what you know.
Doing this for a whole product is real work — that's the honest cost of the cure. It's the work Stewie Reflect does for you: it reviews a pinned snapshot of your repository and produces a source-grounded owner's manual — what the code supports, what's inferred, what remains uncertain, and which decisions only you can make. The debt stops compounding the moment the unknowns have nowhere left to hide.
The discourse gave the problem its name. Naming the cure matters just as much: not more documentation — re-authored understanding, with evidence attached.
