Seif Mamdouh

Two Ways Out of Cognitive Debt

TL;DR

Hot take: understanding code is as important as shipping it.

  • I was shipping a CRM feature with 10 parallel agents and hit the moment where I was reading my own PRs going "...is this good?" I had lost the map of my own feature.
  • That's cognitive debt: code exists in your repo that no human genuinely understands. Last post I named the problem. This post is how I pay it down.
  • Two ways I understand things now:
    1. Explanations: an agent-generated doc with background, intuition, interface figures, and most importantly quizzes. I do not send a PR before I take the quiz.
    2. Microworlds: because I'm lazy and I don't want to read. Build a tiny interactive version of the system and learn it by poking it, the way you'd learn French by living in France.

The moment I lost the map

I was building a feature called Audiences for our CRM: you can edit audiences based on EMR attributes, then build automations on top of them. Classic segmentation + auto triggers work.

I did everything "right." PRD ready before a line of code. Clear decomposition. I spawned 10 agents, each with its own PR.

Then at some point, and I genuinely forgot where I was.

I was reading PR number six or seven, and I caught myself scrolling through the diff thinking:

"hmmmm do I understand this?"

That's cognitive debt getting collected in real time.

I've landed on two mechanisms.

1. Explanations (with quizzes I can't skip)

The first is a skill by Geoffrey Litt, a design engineer whose work I've admired for a while. The idea: instead of reviewing a raw diff, you have the agent generate a self-contained explanation document for the change. Mine come out with three sections:

  • Background: what the surrounding system looked like before this change, so the diff has somewhere to land in your head.
  • Intuition: the core idea of the change explained with toy data and concrete examples before any implementation detail.
  • Interface figures: diagrams of the boundaries. What flows in, what flows out, before/after panels of the data shapes. Not ASCII art; actual figures you can look at.

All of that is nice. None of it is the point. The point is the last section:

Quizzes.

The explanation ends with multiple-choice questions about the change. And here is my rule, the one that has actually changed how I ship:

I do not send a PR for review before I take the quiz.

The quiz is the difference between reading and understanding, and it's brutal about exposing which one you did.

When I pick wrong, that's the system working. A wrong quiz answer on my own PR is the cheapest possible place to discover I don't understand my own feature. It's infinitely cheaper than discovering it in an incident channel or god forbid a prod bug!

Here's what it looks like in practice:

2. Microworlds (because I'm lazy)

The second mechanism exists because of an uncomfortable truth: I don't want to read. Even a great explanation doc is still a document, and my honest attention budget at 4pm after 12 PRs is not "document."

So: microworlds.

The idea comes from Seymour Papert, the MIT researcher behind Logo and constructionism. His famous framing, from the Squeakers DVD:

"Most kids in French class don't learn much French, but we don't say that they're not Frenchly minded. We don't say they don't have a head for French because we know that if they grew up in France, they'd learn French perfectly well. I think that my image of learning mathematics is if we all learned mathematics in Mathland, we would all learn mathematics perfectly well."

Now flip it to code review. Reading a diff is French class. It's the symbolic, decontextualized version of the system, and my comprehension of it is about as good as my non existent French (Allez leues Bluez 🇫🇷)

A microworld is the France of your feature. It's a tiny, interactive, self-contained version of the system where you learn the behavior by interacting with it instead of reading about it.

For Audiences, that meant a little playground: fake patients with editable EMR attributes on one side, the audience rules in the middle, and the automations that would fire on the right. Drag an attribute, watch which audiences the patient enters and leaves, watch which automations trigger.

Five minutes of poking at that taught me more than an hour of diff-reading, because I wasn't verifying code. I was interacting with how the thing was supposed to behave, and every surprise ("wait, why did that automation fire?") pointed me at exactly the code I actually needed to read. T

he microworld doesn't replace reading; it tells you what's worth reading!

Here's the Audiences microworld:

Understanding is the job

Ten agents will happily out generate your ability to understand, forever. That asymmetry only gets worse. The fix isn't reading faster. It's changing what "review" means:

  • Explanations turn a diff into something with background, intuition, and figures, and the quiz turns "I read it" into "prove it."
  • Microworlds turn the system into a place you can live in for five minutes, so the understanding comes from your hands instead of your eyes.

The PRD & 10 agents setup wasn't the mistake. Shipping was never the hard part of that week. The hard part was staying the person who could answer "is this good?" with something better than a shrug, and that's the part of the job that never got automated.

Take the quiz. Build the world. Then hit merge.

Sources: Geoffrey Litt's explanation skill · Seymour Papert on Mathland (The Daily Papert) · Papert, Mindstorms (1980)