Measure comprehension debt before it becomes an incident

You measure comprehension debt per area, not per codebase: for each part of the system, how much of what shipped has a recorded reason someone on the team can explain. Start with an estimate inferred from git and PR history, cap it, and let it rise only on evidence. Backthread produces that reading continuously for teams whose agents write the code, as knowledge coverage per area, so a leader sees where understanding is thin.

What is comprehension debt, and who named it?

The term belongs to Addy Osmani. He defined it on his own blog on 14 March 2026 as "the growing gap between how much code exists in your system and how much of it any human being genuinely understands", and O'Reilly Radar carried the essay on 13 April 2026. His sharpest observation is not the definition but the failure mode: unlike technical debt, which announces itself through slow builds and tangled dependencies, comprehension debt "breeds false confidence". It is the aggregate of hundreds of reviews where the code looked fine, the tests passed, and there was another PR in the queue.

Margaret-Anne Storey reached the same place from the research side a month earlier. Her 9 February 2026 essay calls it cognitive debt: the debt from going fast "lives in the brains of the developers", and it shows up "through a silent loss of shared theory" rather than through failing builds. Her follow-up on 18 February adds what repayment looks like: "capturing intent, the rationale behind decisions, key constraints, and how the architecture supports change."

Two names, one phenomenon. Osmani's is the one people search for; Storey's is the one with the research programme behind it. Neither essay proposes a per-area measurement, which is the gap this page is about.

Why does it not show up in the metrics you already run?

Osmani puts it plainly: "nothing in your current measurement system captures it." Velocity is up, DORA is green, coverage is fine. That is not a weakness of those metrics. They measure the code and the pipeline, and the debt is not in either. It is in the distance between what the system does and what the people responsible for it can say about it.

The signals that do exist are all lagging. A Forbes Technology Council piece from 8 July 2026 lists four that engineering leaders notice from the inside: review time falling faster than complexity, fewer architecture decision records despite constant change, post-mortems that cite "unclear original intent", and senior engineers hedging when asked to explain a system they nominally own. All four are real. All four are also things you find out after the debt has come due. The post-mortem is the bill, not the balance.

The other reflex is to reach for authorship. Which modules have the most AI-written code, whose names are on the commits, how much of the repository was written by someone still employed. Those numbers are cheap to compute and, under agents, they measure the wrong thing. A merged pull request is not evidence that anyone understood it, and a June 2026 position paper argues that authorship-based knowledge metrics are "invalidated as a class". A living-authorship percentage tells you whose name is on the code. It cannot tell you whether that person, or anyone, holds the model.

How to measure comprehension debt per area

The measurement has three parts: the unit, the estimate, and the earned figure above the estimate. Each one is a choice, and the choices are what make the number honest.

1. Pick the unit: areas, not files

A codebase-wide number hides the thing you are looking for. Comprehension debt is never spread evenly; it concentrates in the subsystems that were built fastest, by the fewest people, with the most agent involvement. So the unit is an area the size of one person's mental model: checkout, the ingest pipeline, auth and sessions, the notification fan-out. A team of forty usually has between fifteen and forty of them.

If you cannot name an area in three words it is two areas. If two engineers draw different boundaries, that disagreement is itself a finding: the team does not share a theory of what the system is.

2. Define the denominator: what shipped, with or without a reason

For each area, the denominator is the set of merged changes that mattered, and the numerator is the subset with a recorded why: the decision that was made, the alternative that was weighed, the trade-off accepted. Not the diff, and not the commit message. The reason.

This is where most teams discover the debt is larger than they assumed. We measured it on our own repository: 62 percent of decisions made inside agent sessions carried no alternative and no trade-off at all, and most of that reasoning never existed to begin with. A denominator built from "changes that shipped" and a numerator built from "changes anyone can explain" gives you the gap in one line per area. Where the numerator is empty, write nothing on record here. Do not write zero. Zero is a measurement, and you have not made one.

3. Build the estimate from history, and cap it

You will not have the reasoning for the last two years of changes on day one, and asking people to reconstruct it is how these efforts die. So start with the prior that history can honestly support: who authored and who reviewed changes in each area, and how recently. Having been in an area is worth something.

It is never worth everything, so cap it. We cap the inferred figure at 50 percent and label it an estimate wherever it appears. The specific number is a judgement call; that there is a cap is not. An uncapped figure inferred from commits is exactly the authorship metric that stopped meaning anything when the agent started writing the commits.

4. Let it rise only on evidence

Above the cap, the figure moves when someone demonstrates they hold the reasoning for an area, and the demonstration has to arrive inside work they are already doing. A review comment that names the trade-off rather than the typo. A written why on a pull request. A design discussion where an engineer argues correctly about an area they have never committed to. An incident diagnosed by someone who did not write the code.

What does not work is a questionnaire. We have watched the quiz-shaped version of this rejected by every team we put it to; it reads as an exam, it competes with asking a colleague, and without a mandate participation lasts about two weeks. The method for building this picture by hand, area by area, is in how to find out who on your team understands each part of the codebase; the per-person view of the same data is the overview of who knows what.

5. Read the table for shape, not for the total

Once every area has a row, the total is the least useful number on the page. Read the rows.

Rerun the reading after any large merge and after anyone leaves. The number that matters is not the level but the direction per area over a quarter.

What do the other measurements give you?

Several tools now sell a comprehension-debt number, and they are worth knowing so you know what you are buying.

• Living-authorship scores (Grasp is the visible one) scan git metadata and report the share of a repository authored by people still on the team, with the openai-python repository at 12 percent and curl at 96 percent in their published benchmark. It is deterministic, needs no access to source, and answers a real diligence question. It is also authorship, and authorship is the proxy that agents broke.
• Countervailing metrics. The Allstacks essay (29 January 2026) recommends tracking incident resolution time, onboarding ramp time, review depth and architecture-decision documentation alongside velocity. Sound advice, and every one of those is whole-organisation and lagging.
• Behavioural warning signs. Storey's DX piece (22 April 2026) names hesitation to change the system, reliance on tribal knowledge held by one or two people, and a system becoming opaque to its own team, and says openly that measurement "remains an open research question".
• Per-area knowledge coverage, which is what Backthread does: a live map of the system with a coverage figure per area, inferred from git and PR history at first, capped at 50 percent and labelled an estimate, and rising above that only as the reasoning behind merged changes is captured from agent sessions and PR discussion and explained back. Areas with nothing captured say so. The leader reads the map; the engineers never fill in a form.

None of these replaces the others. The first three tell you the debt exists. The per-area reading tells you where.

When should you measure it?

Before the incident, which means now, and specifically at three moments: when the ratio of agent-written to hand-written changes crosses half, because that is when the authorship prior stops tracking reality; before a key engineer's last day, because after it the one-name rows cannot be repaid; and before a subsystem rewrite, because a rewrite of an area nobody can explain is a rewrite of the wrong thing.

Osmani's essay ends on the line that "the comprehension work is the job." The measurement is how you find out which parts of the job are not being done, and by how much, before the system tells you the hard way.

Connect one repo and the per-area reading is there the same day, with the inferred part capped and labelled as the estimate it is; the trial runs fourteen days with everything on.