The State of Comprehension Debt 2026

The number your dashboards don't have

In March 2026, Addy Osmani gave a name to something engineering leaders had been feeling for a couple of years. He called it comprehension debt: the growing gap between how much code exists in your system and how much of it any human being genuinely understands. AI assistants write more of the code. Humans review less of it, and the authors move on to other things. Meanwhile every dashboard you own says things are fine, because velocity and DORA metrics measure output, and output is the one thing that keeps improving.

The term caught on. The measurement didn't exist, so I built it.

The Grasp Score is computed entirely from data every repository already has (git history and pull-request metadata, with no source code contents required). For every module it asks four questions:

1. Living knowledge: What share of recent lines were written by humans still active in the last 90 days?
2. AI attribution: What share carries hard evidence of AI authorship, meaning agent co-author trailers and bot accounts?
3. Review depth: Were large changes actually reviewed by a human? Approved in minutes? Or only ever reviewed by other AIs?
4. Heat and concentration: Is poorly-understood code still changing, and how few people hold what remains?

Then I ran it on 22 well-known repositories across five groups: AI-era agent tools, AI-era applications, AI vendor SDKs, modern human-led projects, and pre-AI controls.

Finding 1: The most-installed AI libraries are machine-written on purpose

The client libraries millions of developers install first, openai-python and anthropic-sdk-python, scored 3% and 5% living commit-authorship. Roughly 64% of their lines are attributable to automated codegen pipelines and bot accounts in the public repository history. Seven active human contributors on one, eleven on the other.

I want to be careful about what that means. Both repositories are produced by automated code generation from API specifications. That is a deliberate, industry-standard engineering choice, not negligence, and it is not evidence that anyone's engineers fail to understand their products. What it demonstrates is a structural blind spot for every company adopting generated code: when the pipeline is the author, human comprehension migrates out of the repository and into the generator and the spec, where repository-level metrics, code review records, and every conventional dashboard simply cannot see it. The world's most-installed AI client libraries happen to be the clearest public example of a pattern that is becoming normal, and that no standard tooling can audit. For contrast, the third SDK in that group (vercel/ai) is largely hand-written. It scores 72%.

Finding 2: Comprehension debt is older than AI

My pre-AI control group split cleanly in two, and this was the part that surprised me.

I expected curl to score near the bottom. It is 25 years old and hundreds of contributors have come and gone from it. Instead it came back the healthiest repository of the 22 I scanned: 94% living knowledge, 55 active contributors. My first assumption was a bug in my own engine. The number survived every recheck I could throw at it, including a variant that widens the analysis window to thirty years. Requests scored 86% and Flask 84%, so well-maintained old projects turned out to be a pattern, not a fluke.

Express is the other half of the split. The framework sitting under an enormous fraction of the web scored 15% living commit-authorship, with 85% of its recent lines written by contributors no longer active (10 active humans, out of 389 who ever contributed). Gin scored 11%. To be clear, none of this criticizes the current maintainers. The score describes how much accumulated authorship has aged out from under them, which is precisely the burden they carry.

So age defends nothing, in either direction. The oldest project in the benchmark is the best-understood, and a 15-year-old pillar of the npm ecosystem is nearly authorless. Comprehension debt turns out to be a maintenance phenomenon. AI just puts it on a faster clock.

Finding 3: The more AI-native the project, the less of it any present human wrote

Median living knowledge by group:

Two more numbers stopped me. LangChain has had 3,683 human contributors and 41 are still active, a 99% authorship-attrition rate on the most-forked AI framework of the decade. And in a review-depth sample from one fast-moving AI-era repo (34 merged PRs, deliberately weighted toward the largest merges), 41% showed no recorded human review at all, and 35% were reviewed only by AI bots. That sample includes a 2,077-line change merged 24 minutes after it was opened. The review record has real limits here. Pairing, pre-coordinated work, and review done outside GitHub are all invisible to it, so treat these as process signals from a sample rather than verdicts on any contributor.

Put the three findings together and you get the 2026 stack: AI-assisted code, increasingly reviewed by AI, sitting on frameworks whose original authors have moved on. No dashboard in standard use measures any layer of that.

What this means if you run an engineering org

Every metric you watch was designed to measure output. Comprehension debt is a stock rather than a flow. It accumulates silently while the output metrics improve, and it eventually presents as incidents nobody can explain, onboarding that takes longer every quarter, and the specific reluctance everyone feels about touching certain modules.

Both failure shapes from the open-source data exist inside companies too. There is dark code: fast-growing, AI-heavy modules with no living author, where the review record shows comment-free or AI-only approvals. You meet that one during an incident. Then there is concentration risk, where the knowledge is alive but resides in exactly one person, and you meet it the day that person resigns.

Neither shows up in a velocity dashboard. Both are computable this afternoon from data you already have.

Method and limits

Metadata only: commits, authorship, timestamps, diff stats, PR review events. Never file contents. AI attribution counts only hard evidence (co-author trailers and bot accounts), which makes it a floor. Squash merges strip trailers, so the true AI share is higher everywhere. "Departed" in open source includes drive-by contributors, which overstates attrition relative to a company repo with a real roster. And living authorship is a proxy for comprehension. Treat every score as a potential indicator that tells you where to look, not a diagnosis.

I will also be explicit about something most metrics never admit: this one will age, by design. Living authorship is the right comprehension proxy today because authorship is still where comprehension mostly comes from. As agent-written code becomes the default, that assumption expires. In a mostly-agent-written repo, low human authorship becomes true of healthy teams too, and comprehension migrates into review, steering, and specification. When that happens, authorship share retires as the headline number and engagement share replaces it: human review depth on AI-authored change, steering patterns, authorship of specs and rules files. The engine already collects those signals. The formula is versioned and will change. The question it answers, who still understands this system, will not.

I also computed everything twice, using two weighting schemes that err in opposite directions. Line-weighting matches "what share of the code by volume has a living author," but it lets verbose and generated authorship dominate. Touch-weighting counts each file-touching commit once, which is closer to how comprehension actually forms, though it prices a 3,000-line generated commit the same as a one-line fix. The findings hold in both modes. The codegen SDK repos score 3–5% line-weighted and 1–4% touch-weighted; curl scores 94% and 95%; the group-by-group gradient does not move. When two differently-biased instruments agree, the conclusion is stronger than either alone. Full methodology and per-repo data are in the report.

Scope of claims: every number derives from publicly available repository metadata analyzed with the disclosed method. Nothing here asserts misconduct, negligence, or lack of competence by any contributor, maintainer, or company, and nothing here is a claim about the quality, security, or fitness of any software. Project names identify public data sources; all trademarks belong to their owners. Believe a number is wrong? Contact support@graspscore.com. I correct verified errors and version this report.

The Grasp Score is the first instrument for the Comprehension Index. The methodology is published in full because the aim is a public standard, one anyone can scrutinize. Scan your own repos at graspscore.com.