assessing-comprehension-debt

Assessing Comprehension Debt

Use this skill when code is arriving faster than anyone is reading it, and every other quality signal still looks fine.

Comprehension debt is the gap between the code that exists and the code the team actually understands. Tests pass, coverage holds, lint is clean - and nobody can explain why the pricing module works. When an agent writes the implementation and the tests, both signals go green without a single human forming a mental model. That is the debt this skill makes visible.

It is advisory, permanently, on purpose. Understanding lives in people's heads and cannot be proven by any signal. What can be measured is the risk of comprehension debt and the absence of evidence of understanding. A gate that claims to measure understanding is lying, and once someone notices, every finding it ever produced loses credibility.

When to Use

• an AI-assisted or agent-generated codebase is growing faster than the team reads it
• reviews are fast, approvals are frequent, and nobody asks questions
• a module ships weekly and no one volunteers to explain it
• a bus-factor conversation needs evidence instead of anecdote
• a quarterly quality review should cover more than test coverage
• onboarding is slow in a codebase that looks well-tested

Operating Principles

• Never blocks. Findings cap below the project's blocking threshold. State that ceiling in the report, every time.
• Measure absence of evidence, not understanding. Say it in those words. The band is a proxy; treat it as a prompt for a conversation, not a score.
• The risk band is directional, not precise. It says "this change is the shape of one nobody understands", not "nobody understands this change".
• AI provenance is a signal, never a penalty. The useful figure is AI-authored and unattested. AI-authored and well-understood is a good outcome, and if trailers are not in use the honest answer is "unknown".
• A human explanation lowers the band. An Intent: trailer or an ADR is evidence that somebody thought about it. That is exactly the behaviour to reward.
• Teach-back beats approval. "I approve" is a click. "I can explain what happens when the provider retries this webhook" is comprehension.
• Never blame individuals. A high band on a module is a system outcome: review load, delivery pressure, tooling. Naming people converts a useful signal into something nobody will run twice.
• Trend over snapshot. One reading is noise. Direction over a quarter is the finding.