Cognitive Debt: When You Build Faster Than You Understand

There’s an experience I kept having at Popover, the travel startup I co-founded. I’d start my day, open a component I’d built, and realize I was going to have to figure out how it worked again.

I don’t think this is an isolated problem — in fact, I think it’s a problem that almost any software team runs into at some point, and one that occurs earlier and more frequently with AI’s help. Let’s try to give it a name and a bit more texture, in hopes that helps point to a solution.

Moving fast

Popover is an AI-first startup building a travel app. We’re two people with product and design backgrounds, we live in Claude Code, and we wrote 100,000 lines of code in three months. Coming from a much larger organization, it’s hard to describe how joyful it is to just build, without the lossy, high-friction handoffs of software development at scale.

But as we built, we were accumulating complexity just as fast — ironically, because we could build so quickly. You can ship at the speed of a much larger team, but you still have to know what it all does. (And then wake up the next day and keep building.)

Cognitive load

There’s a concept from cognitive psychology called “cognitive load” — basically, how much you can hold in your head at once. Working memory has hard limits. Software teams have always known this intuitively, and the term became ubiquitous in 2018 with the publication of Team Topologies. The book recommends drawing team and technical boundaries around the limits of cognitive load — but what happens when you’re building faster than those boundaries can form?

The email pipeline

Here’s a concrete example. One way to group apps in the travel planning space is email ingestion: there are apps that read your email and create travel records automatically, and apps that don’t. User interviews told us that manual entry of travel plans was a dealbreaker for a lot of users, so we made email ingestion a priority for MVP.

“Turn booking confirmation emails into travel records” sounds relatively straightforward, but it’s actually a surprisingly nasty problem. We needed to wire together three integrations: multiple Gmail API endpoints for access, two rounds of AI-model parsing, and a queue so we could scan a whole 20,000-email inbox in small, independent batches while respecting rate limits. What’s worse, there’s no off-the-shelf solution for most of that scaffolding. We had to build it a lot of it ourselves from scratch.

And that’s just the infrastructure! On top of it, email ingestion introduces a bunch of domain model complexity: How do we decide which trip a flight belongs to? What happens when we see a cancellation? What if an email conflicts with something the user entered manually? It turns out that email ingestion is where a travel app starts to go off the basic CRUD rails real fast.

The tragic part is, all of this is orthogonal to our core domain — we’re a travel app, not an email app. And it’s sensitive: ever since Cambridge Analytica, folks like Google are very touchy about who can read your email. So we had to build something complex, in territory we weren’t experts in, with enough precision and care to pass an external security audit.

Anyway, the number of times I started a work day and had to be like, “dammit, HOW does our Gmail pipeline work again??” — that’s the experience I want to name.

Cognitive debt

There’s actually already an emerging term for this: cognitive debt . John Willshire at Smithery describes it as “where you forgo the thinking in order just to get the answers, but have no real idea of why the answers are what they are.”

Technical debt is about code quality — shortcuts that need cleanup later. Cognitive debt is about understanding. You built it. It works. But you can’t hold the why in your head.

There’s an extra dimension to this that I think is important. Willshire’s post is worrying (reasonably) about all the people who never understand what AI makes for them, who fully outsource their cognitive labor. But I think for a lot of software teams, the problem is more subtle, and one that accumulates over time: for software professionals using AI, the cognitive debt that matters isn’t usually context you were too lazy to pick up the first time — rather, it’s context you lost and have to re-derive every subsequent time.

Why the usual fixes don’t work

This type of cognitive debt has always existed, but historically it’s been an enterprise problem — something that emerges when you have enough complexity and people that “shared understanding” becomes a coordination challenge. Some companies solve it at great expense: technical writers, traceability matrices, whole teams dedicated to making sure specifications stay current. I’m sure those companies would love to have that time and money back (I know I would’ve, when I was managing at that scale). But at least the problem used to emerge at a point in the software’s lifecycle when there were resources to deal with it.

AI-assisted development accelerates everything. A small team can now build at really impressive scale, but they hit enterprise problems before they have enterprise resources. The usual fixes don’t work because they were designed for teams that could afford them:

Documentation goes stale without constant upkeep. It’s a snapshot; the code keeps moving.

Tests prevent regressions, but they don’t transfer understanding. The lean answer to cognitive debt is, “don’t worry about it — the tests pass, and if you want to know what the software does, feel free to use it.” This works for stable areas you’re not touching much, but it’s not super efficient to reconstruct your expected behaviour from test assertions every time you need to change it. It also puts a ton of pressure on the readability of your test code — code that’s already constrained by a bunch of practical factors like component boundaries and tooling limitations. Test code already has one massively important, difficult job to do; burdening it with the additional responsibility to be a concise, transparent source of truth for your behavioural requirements is asking a lot.

And AI doesn’t remember. A human teammate (or better yet, a whole team) who owns the email pipeline builds a mental model of it. They carry that understanding between conversations — you can ask them how it works next week and they’ll still know. An AI coding assistant is stateless by default: every conversation starts fresh. Everything you need it to understand eats precious tokens before you even start working, and eventually you hit context rot or hard limits. So you have to be explicit, thoughtful, and efficient about what it knows.

What the fix probably looks like

Andy Clark and David Chalmers wrote about the “extended mind” in 1998 — how cognition extends into external technologies. Writing outsourced memory. Computers outsourced calculation (among other things). AI is outsourcing reasoning.

So if persistent, recurring cognitive load is the problem, it’s reasonable to imagine a technological fix — some kind of external scaffolding for shared understanding. That scaffolding needs to be:

Persistent. The problem isn’t that you can’t understand the system. It’s that you can’t hold it all in your head at the same time. The understanding needs to live somewhere outside your head, somewhere it survives context switches.

Available to AI. If your coding assistant is going to help you work on the email pipeline, it needs to know what the pipeline is supposed to do. Not just the code, but the intent.

Validated. Stale understanding is worse than none. It gives you false confidence. Whatever captures understanding needs to stay true, ideally by being checked against reality automatically.

What we’re building

This is the problem Popover’s working on with dot•requirements . Requirements that live with your code, are readable by humans and AI, and get validated when your tests run.

If you’ve read this far — if you’ve felt the “how does this work again?” moment — that’s what we’re building. More at dotrequirements.io .