Your team shipped twelve features this quarter. How many of them could your developers explain to a new hire without looking at documentation?
Margaret-Anne Storey's research introduces a concept called cognitive debt - the accumulation of features that work, but nobody fully understands anymore. And she's proposing we measure it.
The Feature Comprehension Score
Storey's Feature Comprehension Score asks a deceptively simple question: can the people who built a feature explain how it works, why decisions were made, and what problems it solves - without needing to trace through the code or dig through old tickets?
If they can't, that's cognitive debt. The feature exists, it functions, but the reasoning behind it has evaporated. When someone needs to modify it later, they're starting from scratch - reverse-engineering decisions that were once obvious to the original team.
This isn't about documentation. Documentation goes out of date the moment someone commits a change without updating it. This is about whether the team's mental model of the system stays coherent as complexity accumulates.
Why Velocity Isn't Enough
Development teams measure velocity obsessively - story points completed, features shipped, sprint goals hit. These metrics answer "how fast are we moving?" but not "do we understand where we've been?"
The problem with velocity as the primary metric is that it optimises for throughput without accounting for comprehension. Teams ship features quickly, but if nobody can explain them three months later, you haven't built a system - you've built a black box that happens to work until it doesn't.
Cognitive debt compounds like financial debt. Early in a project, everyone understands everything. As the codebase grows, understanding fragments. Eventually, you reach a point where making changes feels like defusing a bomb - you know something will break, you're just not sure what.
How Cognitive Debt Accumulates
Storey identifies several patterns that create cognitive debt:
Pressure to ship fast: When deadlines dominate, teams prioritise getting features out over ensuring everyone understands the implementation. The feature works, but the reasoning isn't shared beyond the person who wrote it.
Team turnover: When developers leave, their mental models leave with them. If that knowledge wasn't transferred before they left, it's gone. The code remains, but the why behind the code disappears.
Complex requirements: Features built to satisfy multiple stakeholders with conflicting needs often result in compromises that make sense at the time but become opaque later. Why does this button behave differently on Tuesdays? Because a client needed it three years ago, and nobody remembers the full context.
Abstraction overload: Developers love abstractions - they make code reusable and elegant. But abstractions also hide complexity. When a system has too many layers of abstraction, understanding how a feature actually works requires tracing through multiple levels of indirection. That's cognitive overhead.
Measuring What We Lost
The Feature Comprehension Score proposes a simple test: ask team members to explain recent features without access to code or documentation. Score their responses on whether they can articulate:
1. What the feature does
2. Why it was built this way
3. What trade-offs were made
4. What could break if you modify it
If they struggle with any of these, comprehension has degraded. The feature is in production, but it's no longer fully understood by the team maintaining it.
This isn't about blame. It's about visibility. If you don't measure comprehension, you can't tell when it's eroding until someone tries to change something and discovers nobody knows how it works anymore.
What This Means for Teams
For technical leads and engineering managers, cognitive debt is a forcing function for culture change. If your team can't explain what they built, you're optimising for the wrong metrics.
Practical steps that reduce cognitive debt:
Pair programming and code reviews: When multiple people build a feature together, understanding spreads naturally.
Retrospectives that focus on learning: Not just "what went wrong?" but "what did we learn that we should capture?"
Architecture decision records: Short documents capturing why decisions were made, not just what was built.
Onboarding new team members: If a new hire can't understand the system in a reasonable time, that's a signal that cognitive debt is high.
The Feature Comprehension Score isn't a KPI to gamify. It's a mirror. Hold it up periodically and ask: do we still understand what we've built? If the answer is no, slow down and rebuild that understanding before shipping more features on top of a foundation nobody comprehends.
The Tension Between Speed and Understanding
This research puts a name to something many developers feel but struggle to articulate: the uneasy sense that the codebase is working, but nobody quite knows why anymore. That's cognitive debt talking.
Measuring comprehension won't solve it automatically. But you can't manage what you don't measure. And if we're only measuring velocity, we're optimising for a system that moves fast but understands less with every sprint.
Storey's work suggests a shift: maybe the goal isn't just to ship features quickly. Maybe the goal is to ship features that the team still understands six months later. That's slower in the short term. It's also the only way to build systems that don't collapse under their own complexity.