Cognitive Debt: A Personal Diagnosis

A friend and former colleague messaged me today. The first line was "i currently hate AI."

We've both been writing software for about three decades. Neither of us is a skeptic. My friend ships with agents every day, and I've spent this whole year writing about the factory I built to do most of my coding for me.

So the conversation didn't go where that opening line suggests. We didn't talk about hallucinations, or jobs, or whether the models are any good. We talked about a feeling. Opening a file you shipped last month and reading it like a stranger wrote it. Getting asked how something works and reaching for the chat window instead of your own memory.

An hour later we had a name for it. Cognitive debt. We didn't coin it, and I'll get to the people who did. The short version: technical debt lives in the code. Cognitive debt lives in your head. It's the gap between what the agents shipped and what you understand.

We were both carrying a lot of it.

The symptom with my name on it

Here's mine.

I ask Claude how my own code works. Not code I inherited. Code that merged under my name, from a task I wrote the spec for, in a repo I'm responsible for.

On TutorPro that's fine. It's my project, and nobody cares if I open a session at 10pm and ask what the notification service does before I touch it. The question costs nothing.

At work it costs something. I joined Madhive in May as a tech lead on a large codebase. When a question comes up about a change I drove, and the honest answer is "let me ask," that isn't a confidence-building moment for anyone in the room, including me. The code was reviewed. The tests passed. I approved it. I just can't walk you through it from memory the way I could have five years ago, because five years ago I typed it.

Review drifted the same way. When agent output lands faster than I can internalize it, review turns into pattern matching. Does the shape look right, do the tests pass, did the linter complain. That's not reading. That's skimming with a merge button.

I should name the tension. In July I wrote about the factory that builds my software, and two weeks ago I wrote about the verification debt that factory runs up. Both posts are about speed and its costs, and both left this cost out. The factory is still running. Ninety-nine pull requests merged into TutorPro in one week this month, and I couldn't give you a confident tour of what most of them changed.

That's the debt. I ran it up on purpose, one pass at a time, and the interest comes due whenever someone asks me a question.

What cognitive debt is

The phrase comes from an MIT Media Lab study published in June 2025 under the title "Your Brain on ChatGPT." Fifty-four people wrote essays over four months, some with an LLM, some with a search engine, some with nothing but their heads. The LLM group showed the weakest brain connectivity on EEG, reported the lowest sense of ownership over their essays, and struggled to quote their own work minutes after writing it. The paper's subtitle calls that "accumulation of cognitive debt."

Struggled to quote their own work. I read that line and thought about the meeting.

Margaret-Anne Storey, a professor at the University of Victoria who studies the human side of software engineering, brought the term to our field in February. Her framing leans on Peter Naur's old idea that a program is a theory held in the minds of its developers, and the source is only the written-down part. Her example is a student team that hit a wall in week seven or eight of a course. They couldn't make simple changes without breaking something, and they blamed messy code. The real problem was that nobody on the team could explain why the system was built the way it was. In her words, "They had accumulated cognitive debt faster than technical debt, and it paralyzed them."

Simon Willison picked it up a week later and admitted the same thing I'm admitting here. After prompting whole features into existence without reviewing them, he found himself "getting lost in my own projects," with no firm mental model of what they could do.

Then there's the experiment that explains why slowing down helps. In January, Anthropic published a randomized trial in which developers learned an unfamiliar Python library with or without an AI assistant. The AI group finished barely faster and scored 17 percent lower on a quiz about the code they'd just written. The interesting part is inside the AI group. People who delegated everything scored around 39 percent. People who generated code and then asked the assistant to explain it scored around 86 percent. Same tool, opposite outcomes, and the difference was whether you asked questions.

(Addy Osmani calls the same thing comprehension debt. Same ledger, different label.)

One more thing from the conversation with my friend. We notice this because we remember carrying the map. For most of our careers you couldn't ship a system without a mental model of it, because you typed every line. Someone five years into a career with agents may never have had that baseline to lose. The debt is the same. The sense that something's missing is ours.

Two loops and a ledger

Here's how I think about it now.

Every pass through the fast loop is a debit. A spec goes in, agents build it, a PR merges, and a little more of the system exists that I never formed a theory of. The code can be clean, tested and reviewed, and the debit still posts. That's Storey's point. The debt isn't in the code.

The interest comes due in three places. Review, where I'm approving code I can't fully reason about. On-call, where the fix starts with "first, learn how this works." The meeting, where the question is simple and my answer is a chat window.

The learn loop is the credit side. Spend time understanding an area before changing it, and the next pass through the fast loop in that area costs less. I write a better spec. I review the output as a reader instead of a skimmer. I can answer the question.

The fast loop is still right for most of my work, and the factory posts stand. A bug fix in an area I know, a dependency bump, a help article rewrite, a feature in a module I've already walked. Those go straight to the queue. This post is about the rest.

When I slow down

The rule I've landed on has two triggers, and either one is enough.

I'll own it afterward. If the change is one I'll be asked about, paged for, or expected to extend by hand, I learn the area first. Reviewing isn't enough. Reviewing is how I got here.

I don't know the area yet. At Madhive the codebase is big enough that this is the common case. New ticket, new corner of the system, and the fastest path to a bad spec is writing one for code I haven't read.

If neither fires, the factory runs. If either does, I open a session and type /learn.

/learn: exploring before the work

I wrote /learn for that moment at Madhive, and I've since used it on my own projects when the second trigger fires. It's a Claude Code skill, and the full file is a public gist. Its one-line description is "guided codebase exploration for understanding how something works or what a ticket will require."

The input is a Jira ticket ID, a free-form question, or both. The output is a conversation, not a document, and that distinction is the whole design.

It runs in stages. First an orientation: what part of the system this touches, the question in plain language, and the order we'll explore it in. Then chunks, one at a time. Each chunk is a heading, one to four file references with line ranges, a few sentences on what those files tell us, and a prompt to continue. After the last chunk comes a synthesis: what I now understand, what the ticket will likely require, the gotchas, the open questions. From there I can save notes to disk or hand off to my implementation skill.

A chunk looks like this:

## How a request gets authorized

📄 internal/auth/middleware.go : lines 41–88
→ What to look for: `RequireScope`, and the order it checks the token claims
→ Why it matters: the ticket adds a new scope, and this is the only place scopes are enforced

📄 internal/auth/scopes.go : lines 12–30
→ What to look for: the `Scope` enum and the comment above it about ordering
→ Why it matters: new scopes get appended, not inserted, or existing tokens break

The middleware runs before every handler and checks scopes against the fixed list
in `scopes.go`. Nothing else in the service reads that list, so the ticket's change
is contained to these two files plus the tests beside them.

> **Next:** reply **next** to continue to *how the token gets issued* — or ask me
> anything about this chunk.

The paths are made up. The shape is real.

A few of the rules in the skill came out of watching myself skim.

Claude leads. I don't pick where to go next. The skill decides the exploration path from the ticket and walks me down it. If I were choosing, I'd skip the parts I think I already know, and those are usually the parts I'm wrong about.

One chunk at a time. Dump the whole system on me and I'll skim it, which is the behavior we're trying to fix. Four file references and a paragraph is about what I can read with attention.

Reference, don't reproduce. The skill cites file and line ranges and tells me what to look for. I read the code in my IDE, not in the chat. That's the line between Anthropic's 86 percent group and its 39 percent group. I'm reading the code, with help, instead of reading a summary of it.

Read-only. The skill never edits anything. Exploration and implementation are different sessions on purpose.

Checkpoints in text, not dialogs. This one cost me a few broken sessions. The harness only reliably renders the last message of a turn, so anything printed before a tool call, including a question dialog, can collapse into a "thinking" entry and vanish. Early versions lost whole chunks that way. The skill now has an output contract near the top: a turn either delivers a chunk or asks a question, never both, and the checkpoint is a plain line of text at the end of the chunk.

A /learn session on a mid-sized ticket takes me twenty to forty minutes. That's time the factory would have spent building. It's also time I'd have spent anyway, later, in smaller and more embarrassing pieces.

Results TBD

I sent my friend the gist before I started writing this. They're going to try it. I don't know yet whether it does for them what it does for me, and I'll report back when I do.

I want to be careful about what I'm claiming. /learn doesn't make me faster. On the days I use it, I ship less. It doesn't pay the whole debt either. Nothing I do in forty minutes does.

What it does is narrower. It makes me the person in the room who can answer the question, for the parts of the system I've decided I need to own. For a grizzled vet adjusting to the new way of doing things, that turns out to be most of what I was missing.

My friend still hates AI, currently. Ask again next month.

The skill, as it actually runs: /learn. One file. Drop it in ~/.claude/skills/learn/SKILL.md, open a session in a repo you shipped something to last month, and type /learn with a question. The Jira hook needs acli; a plain question needs nothing.

Take it, run it on your own code, and tell me whether you could explain that code afterward.

–Jeremy