Cognitive debt is the growing gap between what a software system does and how well the people responsible for it understand why it works that way.
The term has moved quickly from practitioner shorthand into mainstream engineering discussion. In April 2026, Thoughtworks added codebase cognitive debt to its Technology Radar, describing the widening gap between a system's implementation and a team's shared understanding of how and why it works.
Thoughtworks specifically points to AI-assisted development as one factor that can widen that gap. Code can now change faster than teams build the mental models needed to review, debug and safely modify it.
See the Thoughtworks Technology Radar entry.
That makes cognitive debt different from technical debt.
But there is another distinction worth making.
At Tentaro, we also use the term context debt for a related problem: engineering knowledge that exists, or once existed, but is no longer reliably available when humans or AI systems need it.
The distinction matters because cognitive debt describes what people no longer understand. Context debt describes part of the reason they have to reconstruct that understanding in the first place.
Cognitive debt is not technical debt
Technical debt usually describes compromises inside software: shortcuts, outdated architecture, duplicated logic, fragile integrations or work deliberately postponed.
Cognitive debt can exist in perfectly reasonable code.
A service can be well tested and maintainable while only two people understand why it is structured the way it is. An AI-generated implementation can pass every test while nobody on the team can confidently explain how it interacts with an older subsystem.
The location of the debt is different.
Technical debt lives primarily in the implementation. Cognitive debt lives in the gap between that implementation and the people expected to reason about it.
Thoughtworks makes a similar distinction in its 2026 Radar discussion. Codebase cognitive debt grows when teams accept changes without developing the mental models required to understand them later.
The two can reinforce each other, but they need different remedies.
Refactoring can reduce technical debt.
It does not automatically teach five engineers why the architecture looks the way it does.
Cognitive debt and context debt are not the same thing
The terms overlap, but treating them as synonyms makes both less useful.
Cognitive debt describes a human understanding problem.
Context debt describes an organizational retrieval problem.
At Tentaro, we use the following working definition:
Context debt is the accumulated cost of engineering knowledge that exists, or once existed, but is not captured, connected or retrievable when humans and AI systems need it.
It is deliberately a working definition rather than an established industry standard.
The principal accumulates when decisions, trade-offs and workarounds disappear into people's heads, old tickets, pull-request discussions, commit history or tools nobody knows to search.
The interest appears every time somebody has to reconstruct that knowledge.
A senior engineer explains the same subsystem again.
A new hire spends weeks performing code archaeology.
A reviewer has to work out why an unusual implementation exists.
An AI coding assistant crawls the same repositories and rebuilds the same context on every new session.
That gives us a useful distinction:
Context debt can contribute to cognitive debt.
If important reasoning is difficult to retrieve, every engineer has to reconstruct more of the system independently. Understanding becomes expensive, concentrates around a few experienced people and disappears more easily when they leave.
That is why improving context retrieval does not magically eliminate cognitive debt.
It reduces one of the mechanisms that keeps producing it.
Why AI makes cognitive debt more visible
AI did not invent cognitive debt.
Software teams have always inherited systems they did not fully understand. Engineers leave. Documentation decays. Decisions disappear into Slack threads and closed pull requests.
What AI changed is the relative speed of generation and comprehension.
Faros AI's 2025 telemetry study found that developers on teams with high AI adoption merged 98% more pull requests and completed 21% more tasks, while PR review time increased 91% and average PR size grew 154%.
These are correlations from observational telemetry, not a controlled experiment. But they illustrate the underlying problem: more work can enter the engineering system while the human verification layer becomes more constrained.
Read the Faros AI Productivity Paradox report.
Faros followed that research with its 2026 Acceleration Whiplash report, based on two years of telemetry from 22,000 developers across 4,000 teams.
Comparing periods of lowest and highest AI adoption within the same organizations, median time to first PR review rose 156.6%, average time spent in code review increased 199.6% and median time in review increased 441.5%.
Pull requests merged without human or agentic review increased 31.3%.
See the 2026 report and methodology.
Those figures do not prove that AI caused every downstream change.
They do show why developers are producing more and the organization understands more cannot be treated as the same metric.
Faster coding can mean weaker understanding
The most interesting evidence is not about pull-request volume. It is about what developers actually learn while using AI.
In January 2026, Anthropic researchers published a randomized experiment involving developers learning an unfamiliar asynchronous programming library.
The AI-assisted group averaged 50% on a later comprehension quiz, compared with 67% among participants who coded without AI assistance. The difference was statistically significant.
The AI group finished only about two minutes faster on average, and that speed difference was not statistically significant.
Anthropic published the study and methodology here.
The conclusion is more nuanced than “AI makes developers worse programmers.”
Researchers observed several interaction patterns.
Participants who delegated most of the coding tended to learn less. People who used AI to ask conceptual questions, examine generated code or support their own reasoning retained more.
The underlying paper discusses those interaction patterns in detail.
That distinction matters.
The problem is not AI assistance itself.
It is delegation without comprehension.
Productivity can feel higher even when it is not
METR's 2025 randomized study offers another useful perspective.
Sixteen experienced open-source maintainers completed 246 real tasks in repositories they already knew well.
With AI tools available, they took 19% longer, even though they believed afterward that AI had made them around 20% faster.
METR publishes the methodology and limitations here.
The result should not be generalized to all developers or all AI tools. METR itself has been explicit about the narrow population involved.
But it demonstrates something relevant to cognitive debt:
felt productivity and verified understanding are not reliable substitutes for measurement.
Producing the first answer may become easier.
The cost can appear later, when somebody else has to review, debug, explain or extend it.
Cognitive debt does not mean AI-generated code is bad code
A team can accumulate cognitive debt around entirely human-written software.
AI-generated software can also be clear, well tested and maintainable.
The debt is not determined by authorship.
It is determined by how much verified understanding remains around the system after the code is merged.
That is why banning AI-generated code is not a serious cognitive-debt strategy.
Neither is simply telling reviewers to “review harder.”
The operational question is more useful:
Can the people responsible for this system still explain and safely change what is being shipped?
That question can be measured.
How cognitive debt shows up in engineering teams
You probably will not see a Jira ticket saying cognitive debt increased 14% during the sprint.
The signals appear elsewhere.
One warning sign is change volume rising faster than review capacity. Faros' telemetry makes that mismatch especially visible.
Another is a growing number of changes merged without meaningful review.
But some of the most expensive signals are organizational rather than quantitative.
Architectural questions begin routing to the same senior engineer.
Review comments spend more time reconstructing intent than examining implementation.
New engineers become productive enough to ship code before they become independent enough to reason about the subsystem.
AI tools repeatedly search the same repositories and rediscover relationships another session already found.
Developers successfully ship code they struggle to explain several weeks later.
None of those symptoms proves cognitive debt in isolation.
Together, they tell you something important: implementation is moving faster than shared understanding.
The missing engineering metric is verified understanding
Engineering already has good delivery metrics.
DORA gives teams measures around lead time, deployment frequency, change failure rate and recovery. Engineering organizations track cycle time, throughput, incidents and defects.
What we do not have is an accepted equivalent for:
How much of the system can the people responsible for it actually explain?
That does not mean we need to invent a fake precision score.
Useful proxies already exist.
For meaningful AI-assisted changes, ask who could explain the implementation in a design review without reopening the original agent session.
Track review effort relative to change volume.
Watch the share of changes merged without review.
Measure the bus factor of critical modules based not on who has committed code, but on who could safely make a difficult change.
For context debt specifically, add another set of measurements: onboarding time to independence, senior-interrupt rate and time-to-answer for concrete questions about your own system.
These measures do not create a perfect “debt score.”
They tell you where your organization is paying the interest.
From context debt to context maturity
Context debt becomes easier to manage once knowledge stops being treated as either “documented” or “undocumented.”
There are several levels between those two extremes.
Level 1: Knowledge lives in heads
The system works because certain people know it.
Questions route to names. Onboarding depends on availability. Incidents become easier when the right engineer joins the call.
Typical symptom: “Ask Alex.”
The main risk is obvious: the bus factor is dangerously low.
Level 2: Knowledge is written down
The organization has wikis, runbooks and architecture diagrams.
That is progress, but synchronization becomes the problem.
The code changes continuously. Manually maintained descriptions change when someone remembers to update them.
Typical symptom: “Check Confluence, but verify it with Sarah.”
The risk is stale confidence.
Level 3: Knowledge is anchored to engineering artifacts
Important rationale begins living in ADRs, pull-request discussions, code comments and decision records.
The organization can reconstruct more than what the code does.
It has evidence for why.
Typical symptom: “We can usually find the decision if we know where to look.”
Now the primary cost is discovery.
Level 4: Knowledge is queryable
Engineers can ask structural questions about their own systems and receive answers grounded in the current codebase.
Where is this implemented?
Which services depend on it?
Where is a similar pattern used?
Which files are relevant?
Answers point back to source rather than asking users to trust generated prose.
Typical symptom: “Ask the system first. Escalate judgment questions to the owner.”
Level 5: Context behaves like infrastructure
Current structural context is available to humans and AI tools.
It can travel across IDEs, agents and engineering workflows instead of being reconstructed from scratch inside every session.
People still own decisions.
But routine system knowledge no longer disappears when the person who knows it logs off.
Typical symptom: “Context follows the work.”
At this level, the main problem shifts again. Retrieval is no longer the primary constraint. Governance becomes more important: deciding which context each person or agent should be allowed to access.
Your context maturity is not your AI maturity
A team can use sophisticated coding agents while its organizational context remains at Level 1.
That creates a dangerous mismatch.
Generation operates at one maturity level.
Understanding and retrieval operate at another.
You can test your own organization with a few simple questions.
When an engineer asks how a service works, do they ask its owner, search documentation, inspect engineering artifacts or query maintained repository context?
When code changes, does knowledge change in someone's head, eventually reach documentation or automatically become available through the systems people and AI already use?
When the primary owner leaves, does work stall?
And when an AI assistant answers a question about your software, can anyone verify where the answer came from?
The goal is not to reach the highest level on every dimension.
The goal is to know where your current bottleneck actually sits.
Where Tentaro fits
Tentaro operates around the transition from context stored in engineering artifacts to context that can be queried and reused.
It does not attempt to manufacture reasoning that was never recorded.
If an engineer chose Kafka over another system in 2022 because of a production constraint and nobody captured that decision, the code cannot reveal the complete hidden history with certainty.
That boundary matters.
What current repositories can tell you is where behavior lives, what depends on it, where similar implementations appear and which files are relevant to a question.
Tentaro turns structural repository knowledge into grounded context that engineers and compatible AI assistants can query.
Its product boundary separates context extraction from code generation.
Tentaro supplies context to the tools engineers already use rather than trying to become another coding agent.
Internally, Tentaro has been dogfooded across 100+ repositories built over 15 years of enterprise delivery. That matters because the difficult context problem is rarely one neat demo repository.
It is retrieving useful context from long-lived software estates.
Better documentation does not eliminate context debt
Documentation remains important.
But “write more docs” does not eliminate context debt if those documents become another source that needs continuous manual maintenance.
Different kinds of knowledge need different sources.
Let the code carry the current implementation.
Let ADRs, pull requests and decision records preserve reasoning the implementation cannot reveal.
Let people carry judgment, product knowledge and trade-off decisions.
Then let a context layer handle retrieval.
The goal is not to move every piece of engineering knowledge into a new database.
It is to stop repeatedly spending senior engineering time on questions whose answers already exist somewhere in the engineering system.
Context debt also has a direct AI cost
Historically, much of the cost of missing context was hidden inside payroll.
A senior engineer spends 30 minutes explaining an old subsystem and no separate invoice appears.
AI changes that.
When an AI system does not have the right context about your software, it has to reconstruct more of the problem during each interaction.
It searches more files.
Consumes more input.
Repeats reasoning another session already performed.
That makes token debt a useful way to think about one part of the interest on context debt.
The price per token can fall while total context-related spend still grows if every useful answer requires increasingly large amounts of reconstruction.
A bigger context window does not automatically solve that problem.
The goal is not to send the model as much context as possible.
It is to retrieve the smallest amount of correct, relevant and verifiable context needed for the task.
The goal is not maximum understanding
No engineer needs to understand every line of a large software estate.
That was never realistic.
The real target is sufficient distributed understanding for safe action.
Someone working on a system should be able to identify the right implementation, trace important dependencies, understand current behavior and verify answers against source.
They should also recognize where historical rationale is missing and know when expert judgment is required.
That is a more realistic objective than universal expertise.
It also gives us a useful relationship between the two concepts:
Context debt falls when less engineering knowledge has to be reconstructed from scratch. Cognitive debt falls when more people can safely reason about and act on the system.
One can influence the other.
They are not the same thing.
Run a Context Debt Audit before adding more agents
Pick one system where AI-assisted development is already common.
First, measure how quickly the implementation changes.
Then measure how difficult it is to retrieve the context needed to understand those changes.
How long does a concrete architectural question take to answer?
How often does it require the same senior engineer?
How long until a new engineer can work independently?
How much reasoning has to be reconstructed from old commits, pull requests or conversations?
Finally, ask how many people can independently explain recent changes well enough to modify them safely.
If code generation is accelerating while context retrieval and shared understanding are not, adding more generation capacity may widen the gap rather than close it.
Tentaro focuses on the part grounded in engineering artifacts: turning existing repository context into something humans and compatible AI systems can retrieve, query and verify.
It cannot reconstruct reasoning that disappeared completely.
But it can reduce how often your organization pays to rediscover knowledge it already has.
FAQ
What is cognitive debt in software engineering?
Cognitive debt is the growing gap between a software system's implementation and the team's shared understanding of how and why it works. Thoughtworks added codebase cognitive debt to its Technology Radar in April 2026 and highlighted rapid AI-assisted change as one factor that can increase the gap.
See the Thoughtworks definition.
What is context debt?
At Tentaro, context debt is a working term for the accumulated cost of engineering knowledge that exists, or once existed, but is not captured, connected or retrievable when people or AI systems need it.
It is not currently a standardized engineering metric or universally agreed industry term.
What is the difference between cognitive debt and context debt?
Cognitive debt is primarily a problem of human understanding. Context debt is a problem of knowledge availability and retrieval.
Missing context can increase cognitive debt because engineers must repeatedly reconstruct the reasoning and relationships needed to understand a system.
What is the difference between cognitive debt and technical debt?
Technical debt describes properties of software that make future changes harder. Cognitive debt describes insufficient shared understanding among the people responsible for that software.
Well-written code can still carry cognitive debt if only a few people understand its structure or rationale.
Does AI cause cognitive debt?
Not automatically.
Cognitive debt existed before AI. AI can increase the rate at which software changes, creating a larger gap if review and understanding do not scale with it.
Faros' observational studies found higher PR throughput alongside slower review under high AI adoption, while Anthropic's controlled study found that some AI interaction patterns weakened learning and others preserved it.
How can you measure cognitive debt?
There is no standardized metric.
Useful indicators include review time relative to change volume, unreviewed merges, bus factor, reviewer concentration and the ability of engineers other than the original author to explain and safely modify recent changes.
How can you measure context debt?
Useful proxies include onboarding time to independence, senior-interrupt rate, time-to-answer for questions about internal systems, bus factor on critical paths and the amount of engineering reasoning that must be reconstructed repeatedly.
Can documentation solve context debt?
Documentation helps preserve architectural decisions and rationale, but manually maintained documentation can drift away from the implementation.
A stronger model combines code-derived structural context, engineering artifacts such as ADRs and pull requests, and human judgment.
What is a context layer?
A context layer retrieves organization-specific information and supplies it to people or AI systems when needed.
In software engineering, that can include relevant files, implementations and dependencies grounded in private repositories instead of relying on a model's general knowledge.
How does Tentaro address context debt?
Tentaro makes structural repository context queryable to engineers and compatible AI assistants.
It can reduce the need to repeatedly reconstruct facts such as where logic lives, what depends on it and which files matter to a question while grounding answers in source.
It cannot recover undocumented historical reasoning that no longer exists.
