Cognitive debt

What it means

“Cognitive debt” has two meanings.

The newer one comes from a 2025 study by Kosmyna et al. (arXiv 2506.08872), “Your Brain on ChatGPT: Accumulation of Cognitive Debt when Using an AI Assistant for Essay Writing Task.” The debt belongs to the human: participants who wrote with an LLM reported the lowest ownership of their essays and struggled to quote their own work.

The older idea, not under that name, belongs to software maintenance. Peter Naur wrote in 1985 that “the program text and its documentation has proved insufficient as a carrier of some of the most important design ideas.” Ward Cunningham was blunter: keep adding features without reorganizing the code to reflect your understanding, and “eventually that program simply does not contain any understanding.”

This page and Enji Guard’s audit follow the second sense: the intent, rationale, constraints, and expected behavior that a future maintainer cannot recover from the repository.

Cognitive debt vs technical debt

Martin Fowler defines technical debt as cruft, “deficiencies in internal quality that make it harder than it would ideally be to modify and extend the system.” Cognitive debt is the missing “why” behind the code, and tidy code can carry plenty of it.

Aspect	Technical debt	Cognitive debt
What is absent	Internal quality: structure, duplication	Recoverable intent: goals, constraints, rationale, proven behavior
Symptom	Changes take longer than needed	Changes made without knowing what must not break
Paid down by	Refactoring	Durable evidence of intent

More documentation does not pay it down. Michael Nygard’s 2011 case for architecture decision records warned that a project that “accumulates too many decisions accepted without understanding” ends with a team “afraid to change anything.” Recoverable intent looks like an ADR that “captures a single AD and its rationale,” an acceptance criterion, a runnable example, or a test stating expected behavior rather than implementation.

Why it matters for AI-written code

A coding agent produces working code faster than anyone records the reasoning behind it, so the distance between code and rationale grows with each accepted change. The agent’s account of a change ends with the session; no theory in Naur’s sense survives in anyone’s head.

That study measured essays, not code, but the pattern it found, lower ownership and weaker recall of one’s own output, is the human side of the same debt. A reviewer who cannot say why accepted code is shaped that way leaves the next agent free to optimize an unexplained constraint away.

How Enji Guard helps

The audit, listed in the catalog as “Run cognitive debt audit,” starts with an inventory, not a score. Its first stage lists intent-bearing artifacts, from README and ADRs to agent instruction files, and records whether each is current, linked from an entry point, stale, or contradictory. Then executable intent: tests, specs, and examples that encode intended behavior, not test coverage.

Analysis scores five dimensions 0–10 (intent clarity, executable intent, understanding recoverability, agent intent context, alignment), weights them to 0–100, and states confidence. The runbook’s rule: “Treat cognitive debt as proxy evidence.” A repository cannot fully prove what people know.

Discoverability is scored as a product-intent signal, not an AI-tooling score, so an agent file listing only commands does not qualify. An unreadable Jira or Notion link counts as a coverage limit, while a bare “see Jira” with no owner or summary scores as a weak repository-side bridge.

Candidate fixes stay bounded: an ADR for a named decision, an executable spec for a named behavior, a constraint documented beside the code it governs. Once the fix merges, the next run checks whether that intent is findable from an entry point; that recurring check holds this part of the green zone.

Enji Guard reads the repository and stops there: no documentation written, no pull request opened, no published improvement paired with the audit. The score covers accessible repository evidence; unwritten knowledge stays outside it.