Comprehension debt is deferred understanding needed to explain, maintain, modify, or operate a system within a specified responsibility. The unit is a team doing defined work under stated conditions. It is not a property of the code, and it cannot be read off a repository.
The consequence for transfer is direct: a system can pass every acceptance test and still be untransferable, because acceptance measures the system and comprehension is measured on the other side of the handover.
Where the term comes from
External usage exists and predates any coinage this corpus could claim. Published work uses comprehension debt for gaps between produced software and human understanding — framed as deferred understanding effort, as a team’s maintenance difficulties, and as a construct examined in student projects.
That evidence is qualitative and bounded. A single-team account and a student-diary analysis both describe problematic reliance on generated code and, in the same breath, uses of AI explanations that supported understanding. Both acknowledge design and generalisation limits, and neither establishes a validated numerical scale.
So the honest status is a working diagnostic with documented prior use, not a measured quantity.
Measure it as tasks
Understanding is defined relative to a task and a role, not as memorisation of a codebase. Four indicators, each with the confound that has to be checked alongside it.
Behaviour prediction. Explain the expected outputs and side effects before running a probe. Confound: prior domain knowledge and task familiarity.
Diagnosis. Locate and explain a seeded or known failure. Confound: tool access and the quality of diagnostic signals.
Change capability. Make a bounded change and justify the tests chosen. Confound: general engineering skill and task difficulty.
Operation. Perform a scoped operating exercise. Confound: permissions, documentation, and assistance.
Record errors, time, assistance, and confidence separately, compare equivalent tasks across occasions, and retain failed and abandoned attempts. Before combining indicators into a score, check whether the proxy predicts the later outcome it is standing in for. Code size and self-reported confidence do not define the construct.
Diagnose before remediating
The recurring error is reading a failed exercise as a knowledge gap.
A recipient who explains recovery steps accurately and cannot begin the restore because the backup role has not been granted has demonstrated understanding and hit an access blocker. The record separates the two, and their restore performance stays unobserved until access is resolved. Marking the attempt as incompetent, or as verbally passed, discards the distinction.
Four causes need separating: missing knowledge, missing access, defective instructions, and missing authority. Each has a different remedy, and each remedy needs an owner and a repeatable verification task.
Missing assessment evidence means understanding is unassessed. It does not establish a deficit.
The practices that build it
Start from the recipient’s actual duties and baseline experience. Walk a representative request or data flow, explaining the constraints and the prior decisions behind it. Then have the recipient predict behaviour, make a bounded change, or handle a controlled failure, and compare the outcome against the prediction.
Sending-team assistance stays available within the authorised arrangement, and every use of it is recorded. Assistance that is available and logged is compatible with independent operation; assistance that is invisible is not evidence of anything.
Discovered gaps become documentation, access, or training work with named owners, and an appropriately varied task is repeated to check whether the gap closed. Untested duties remain flagged as untested.
The on-call training model that this follows combines practical exercises with documentation and staged participation, and the staging is the mechanism — participation increases as demonstrated capability does, rather than on a date.
Why generated code makes this worse
Generation removes the slowest part of building, which was also the part that produced understanding as a byproduct. Someone who writes a parser knows why it handles dates that way. Someone who accepts one does not, and nothing in the acceptance process asks.
The debt is invisible at handover because every artifact exists. The code is there, the tests pass, the documentation was generated too. What is missing is the reasoning, and it is missing on the side that will be paged at three in the morning.
A team that can run the service and cannot trace why a changed rule affects a customer outcome has exactly this gap. The assessment identifies the specific reasoning and evidence gap — after first checking that access and task clarity were not the real constraint.
The rule
What stays fixed is that comprehension is demonstrated by the receiving team, on the tasks it will own, under the access and assistance conditions that will apply after the builder leaves. What changes is which tasks matter, and that follows from the responsibilities being transferred rather than from the size of the codebase.
Not to be confused with
Technical debt. A debt ledger records what the system cannot do. Comprehension debt records what the team cannot explain. A clean ledger and an untransferable system coexist comfortably.
A capability judgement. Difficulty during an exercise is a signal to investigate. It is not evidence about the people, and treating it that way ends the investigation at the least useful point.