Comprehension Debt Is an Infrastructure Problem
2026-04-26 · George Moon
Addy Osmani recently coined a term for a problem engineering teams keep running into: **comprehension debt**. The growing gap between how much code exists in a system and how much any human actually understands.
An Anthropic skill-formation study found engineers using AI assistance scored **17% lower** on a follow-up comprehension quiz (50% vs 67%) than a control group, despite finishing the task in about the same time.
The usual fix is better specs: write down what you build, make the agent read it. That helps. It doesn't fix the problem, though, because comprehension debt lives between the specs, not inside any one of them.
What comprehension debt actually is
Comprehension debt lives in **shared mental models**, not in code artifacts. Technical debt is about *code smells* like duplication, tight coupling, or dead branches. Comprehension debt is about **knowledge smells**: the moment a developer's mental model decouples from the code.
The accumulation is invisible. Reviewers approve PRs that look fine, tests pass, and another item enters the queue. The assumption that reviewed code is understood code quietly becomes false.
Six months later somebody asks "why did we build it this way?" and the honest answer is: the agent did, the reviewer was busy, the spec didn't say, and now nobody knows whether changing it will break something three layers downstream.
The code is fine. It compiles, it runs, it passes tests. What's broken is the **chain of reasoning from evidence to decision to implementation**.
Why specs alone don't close the gap
Spec-driven development is everywhere right now. GitHub's Spec Kit has crossed 72k stars. AWS built Kiro as a spec-first IDE. OpenSpec, Tessl, BMAD, and twenty-five other frameworks are converging on the same idea: write the spec first, then have the agent build to it.
This is real progress, a step up from prompting an agent with one-line tickets and hoping.
But spec-driven tools optimize for one moment in time: the moment you hand a spec to an agent. They don't answer the questions that matter when the spec was written six months ago by a teammate who left, the research it referenced has been updated twice, and three downstream specs were derived from it before any of that happened.
Specifically, doc-based spec tools don't tell you:
- **What evidence supports this spec?** Not "what's in the prompt." What's the actual research, the prior decision, the customer interview that led here?
- **What other work depends on this?** If I change this spec, which downstream specs are now built on stale assumptions?
- **Has the evidence changed?** If the research that justified this spec was updated, who needs to know?
These are graph questions. Specs are nodes, but nodes aren't enough on their own. You need the **edges between specs, evidence, and code**, and those edges need versions.
The missing layer
Lattice is the graph layer underneath spec-driven development. Where Spec Kit manages spec documents, Lattice manages the relationships:
Sources (research, papers, decisions, customer feedback)
↓ supports
Theses (strategic claims)
↓ derives
Requirements (testable specifications)
↓ satisfied by
Implementations (code)
Every edge records the version of both endpoints at the moment it was bound. When an upstream node changes, downstream edges bound to the old version surface as drift: work that may now be built on outdated assumptions.
| | Spec Kit / Kiro / OpenSpec | Lattice |
|---|:---:|:---:|
| Manages spec documents | ✓ | ✓ |
| Links specs to research | | ✓ |
| Version-bound edges | | ✓ |
| Drift detection | | ✓ |
| Bidirectional feedback (code → spec) | | ✓ |
| Git-native | ✓ | ✓ |
Lattice complements these tools rather than competing with them. You can keep your specs in Spec Kit format and still let Lattice track the edges between them, the research underneath them, and the code on top.
What it looks like
An agent is assigned to update the billing flow. Before writing any code, it queries the graph:
# What exactly is the requirement?
lattice get REQ-BILLING-014
# Why does this requirement exist?
lattice search --related-to REQ-BILLING-014
# Has anything upstream changed since this was written?
lattice drift
```
That third command is the one comprehension debt needs. If the thesis behind REQ-BILLING-014 was edited last month because early data showed the original pricing assumption was wrong, `lattice drift` flags it. The agent (and the human reviewing the PR) sees that this work is built on a thesis that has shifted, and gets a chance to verify before shipping.
When the implementation lands, the graph records what happened:
lattice verify IMP-BILLING-FLOW-002 satisfies REQ-BILLING-014 --tests-pass --coverage 0.91
That edge records what shipped against which version of the requirement, with evidence attached. Three months later when somebody asks "does this still do what we said it does?" the answer doesn't depend on anyone remembering.
And when the implementation reveals the spec was wrong, `lattice refine` pushes the gap back upstream:
lattice refine REQ-BILLING-014 --gap-type design_decision --title 'Refund grace period not specified' --implementation IMP-BILLING-FLOW-002
That's the bidirectional feedback most spec systems lack. Implementation gets to shape the spec, not just satisfy it.
The compounding cost
Anthropic's 2026 Agentic Coding Trends Report describes agent task horizons stretching from minutes to **days and weeks**, multi-agent teams running in parallel on the same codebase, and engineers shifting from writing code to orchestrating systems that write it.
Every one of those trends multiplies comprehension debt:
- **Longer horizons** mean agents make more decisions per session that no human ever reviewed in real time.
- **Multi-agent parallelism** means five agents resolving the same ambiguity five different ways.
- **Orchestration** means humans further from the code, more reliant on whatever institutional knowledge actually got captured.
Without infrastructure that captures intent and tracks changes, the gap widens with every agent run. With it, the system remembers the reasoning so humans can focus on judgment.
One recent piece pushed back on the inevitability framing: *"Context debt isn't an inevitable consequence of AI adoption. It's an infrastructure failure. A failure to build systems that capture, maintain, and surface the institutional knowledge that makes code comprehensible and architecturally coherent."*
The teams building this infrastructure now will have an easier time maintaining their codebases next year. The teams that skip it will keep paying an invisible tax, until something downstream breaks and nobody can explain why.
Where to start
If you're already running spec-driven development, you have the spec nodes. You just need the edges.
# Install Lattice
curl -fsSL https://forkzero.ai/lattice/install.sh | sh
# Initialize the graph in your project
lattice init --skill
```
`lattice init --skill` installs the Claude Code skill so agents can query and update the graph natively. From there, the workflow is incremental: capture the next decision as a source, link it to a thesis, derive requirements, verify implementations. The graph grows as you work.
- [Lattice on GitHub](https://github.com/forkzero/lattice)
- [Live dashboard](https://forkzero.ai/reader?url=https://forkzero.github.io/lattice/lattice-data.json)
- [Forkzero](https://forkzero.ai)