Understanding Is the New Bottleneck — and Your AI Agent Can Fix It

Recently I came across a short talk by Geoffrey Litt [6] with a title that stuck with me: “Understanding is the new bottleneck” [1]. I have felt the thing he describes without having a name for it. An agent hands me a change that is larger than anything I would have written by hand, the tests pass, it looks right, and I approve it. Then a week later something breaks in that area and I realise I do not actually understand the code with my name on the commit. The writing was never the hard part. Keeping up with what got written is.

Litt’s talk is the clearest articulation of that gap I have seen, so this post is my attempt to take his idea and make it concrete on the tools I use every day. The reframe is his. The working demo is mine, and I will show you exactly what it produced.

The bottleneck moved from writing to understanding

The common story about AI coding is that “code review is the new bottleneck.” In that story the human is a correctness checker: does this match the spec, will it take down production, is it well architected. Litt’s point is that this role is shrinking, and he is fine with it. Agents, he argues, are getting better at running their own verification loops, so the thumbs-up-thumbs-down part of the job is being automated away from under us [1].

The durable reason to understand the code is not to catch the agent’s mistakes. It is to participate. In his words, when you review what happened and get into the loop, you come away changed, and that understanding is the foundation for having the next idea [1]. Rich structures in your head are what let you take a creative leap without round-tripping to the agent for every step. Lose them and you can still ship, for a while, but you stop being able to lead.

There is a name for what you accumulate when you skip that step. Litt calls it cognitive debt, an analogy to technical debt he credits to researcher Margaret-Mary Storey and a post by Simon Willison [1]. You vibe-code long enough, you get away with it, and then one day you wake up unable to participate in your own system. The interest comes due later, which is exactly what makes it easy to ignore now.

Three ideas borrowed from teaching

The part of the talk I keep coming back to is that Litt does not treat this as a discipline problem. He treats it as a tooling problem, and he borrows the tools from education [1]. Three of them stood out, and the first two are what my demo implements.

The first is explanations. Instead of reading a raw diff, you have the agent write an explainer for the change, structured the way a good teacher would: background first, intuition before details, then the actual code walked through in prose rather than dumped. Litt says he literally prints these and reads them at a café like a textbook about his own pull request.

The second is quizzes as a comprehension gate. He credits Andy Matuschak’s “Why books don’t work” and Michael Nielsen’s writing on spaced repetition for the idea that reading something is not the same as understanding it [1]. So every explainer ends with a short quiz, and his rule is blunt: don’t send a PR for review unless you can pass the quiz about what your agent wrote. It is a speed regulator, so you move at the speed of understanding rather than the speed of generation.

The third is microworlds: small inhabitable simulations the agent builds so you can feel how a system behaves, an idea he traces to Seymour Papert. It is the most ambitious of the three and I am leaving it out of the demo on purpose. Explainers and quizzes are the two you can adopt this week, so those are the two I built.

Turning that into a Kiro skill

Litt shipped his version as a skill called ExplainDiff, published as a gist [2]. A skill in this sense is just a markdown file with instructions the agent loads when the task matches. His instructions tell the agent to produce four sections, in order, as a single self-contained HTML file: Background, Intuition, Code, and Quiz [2].

That format ports cleanly to the agent I actually use, Kiro CLI, because Kiro has the same primitive. A Kiro skill is a folder with a SKILL.md file: YAML frontmatter with a name and a description, then markdown instructions. The description is how the agent decides when to activate it [3]. So porting ExplainDiff was mostly a matter of dropping Litt’s instructions into a SKILL.md, keeping his four-section structure, and adding a credit line back to his original.

Here is the whole skill definition. This is the entire mechanism, not an excerpt:

The ported explain-diff skill, Litt’s four-section structure as a Kiro SKILL.md:

---
name: explain-diff
description: Use when the user asks for a rich, interactive explanation of a code
  change, diff, branch, or PR. Produces a single self-contained HTML explainer with
  Background, Intuition, a Code walkthrough, and a comprehension Quiz.
---

# Explain Diff

Produce these sections, in order:

- Background — the existing system relevant to this change (deep background for
  beginners, then narrow background for the change itself).
- Intuition — the core idea, essence not detail, with concrete toy examples and figures.
- Code — a literate walkthrough of the actual changes (prose before each file, not a dump).
- Quiz — five multiple-choice questions that test real understanding; clicking an
  answer shows correct/incorrect with feedback.

There is a second Kiro primitive that makes this more than a manual command: hooks. A hook lets you run a command at points in the agent’s lifecycle, including right after the agent finishes using a tool, and you can match it to a specific tool such as the file-write tool [4]. In plain terms, you can have the agent run a command automatically after it edits code. Point that at the explainer skill and the comprehension step stops being something you remember to do and becomes something that just happens on every change. I have not wired the automatic version into my daily loop yet, so I want to be clear that is the direction rather than a finished habit. The manual skill is what I actually ran.

What the skill actually produced

I did not want to describe this in the abstract, so I ran it on a real change. The sample is a tiny fictional Zen-garden renderer, a Python module that projects grid tiles to screen coordinates. The change swaps a flat top-down projection for an isometric one and adds a correct draw order. It is small but genuinely conceptual, the kind of change that looks trivial in the diff and is easy to approve without really following the geometry.

The core of the diff is two ideas. The projection changes from a direct grid-to-pixel mapping into an “isometric” one in the game sense, strictly speaking an axonometric projection, and with the usual squashed tile a dimetric one, where each screen coordinate mixes both grid axes:

The projection change at the heart of the sample diff:

# before: flat top-down
screen_x = gx * TILE
screen_y = gy * TILE

# after: isometric (rotate 45 degrees, squash vertically)
screen_x = (gx - gy) * (TILE_W // 2)
screen_y = (gx + gy) * (TILE_H // 2)

The second idea is draw order. Once tiles overlap in an isometric view, you have to paint the ones in back first, so the change sorts by gx + gy before drawing, the painter’s algorithm, for this flat grid of equal tiles, that one scalar key is all the depth ordering needed. Neither line is hard on its own. Together they are exactly the sort of thing you nod along to and then cannot reconstruct later.

I ran the ported skill with a single Kiro CLI command pointed at the sample and the diff. It produced one self-contained HTML file, about nineteen kilobytes, no external dependencies. It opens with background on projections for a reader who has never done graphics, narrows to what this specific change does, gives the intuition with a small inline SVG figure showing the grid rotating, walks the actual code in the order that makes sense rather than file order, and ends with five multiple-choice questions. Clicking an answer tells you whether you were right and why.

Reading it, I understood the painter’s-algorithm sort in a way I had skimmed past in the raw diff. That is the whole point. The agent wrote the code and then, on request, rebuilt my understanding of it. And the quiz did its job as a gate: I would not have passed question four on the first read, which is precisely the signal Litt is arguing for.

The whole thing, the skill, the sample, and the generated explainer, is on GitHub so you can run it yourself or point it at your own diff [5].

The speed regulator

The rule that comes packaged with all this is the part I would keep even if I dropped everything else: don’t ship a PR you can’t pass the quiz on. It reframes speed. The promise of AI coding is usually framed as going faster, and it does let you generate faster. But if the goal is to keep leading the system rather than just feeding it, the useful speed is the speed of your understanding, and a quiz is a cheap, if noisy, check on that.

I want to be fair about the limits. This is one developer’s technique, not a benchmark, and Litt is careful to present it as his own daily practice rather than a proven result [1]. A generated explainer or quiz is only as good as the model that wrote it, an explanation can confidently misdescribe what the code actually does, and the comments on Litt’s own gist point out real failure modes: early versions leaked the answer by always making the correct option the longest or putting it in the same position, which the community fixed by randomising option order [2]. A quiz you can pass by pattern-matching the phrasing measures nothing, and passing it doesn’t replace review and tests; it is a comprehension gate, not a correctness gate. So this is a practice to adopt with your eyes open, not a switch you flip. But the underlying move, using the agent to rebuild your understanding rather than only to write code, strikes me as sound regardless of how polished any single quiz is.

If You’re Running This on AWS

The explainer skill lives on your machine and reads a local diff, which is all the input it needs. Be clear about the boundary, though: the skill file and the diff are local, but the inference is not. Kiro CLI sends the prompt and the diff content to a hosted model, so the code you are diffing does leave the machine, and that round trip is where the latency and the token charges come from. If you want to run the generation on managed infrastructure, Amazon Bedrock is the natural direction: the skill is plain markdown, so any agent wired to a Bedrock-hosted model could produce the same explainer and quiz, with model choice and structured output as platform features, though I haven’t wired that variant up, so treat it as a direction rather than a tested recipe. That is a capability you can reach for when you want it, not something the technique depends on. The interesting design question is not where the model runs but what you do with the output: a PostToolUse-style hook that regenerates an explainer whenever an agent touches a file, or a team habit of attaching the explainer to the PR so reviewers inherit the same background instead of reconstructing it. The infrastructure is the easy part. The comprehension gate is the part worth building on.

Where is your understanding actually lagging your agent right now, and what would it take to make the agent close that gap instead of widening it?

Sources

• [1] Geoffrey Litt, “Understanding is the new bottleneck” (AI Engineer, 2026), the talk this post builds on: verify versus participate, cognitive debt, and the three education-inspired techniques.
• [2] Geoffrey Litt, “explain-diff-html” skill (gist), the original ExplainDiff skill: Background, Intuition, Code, Quiz as a self-contained HTML file, plus community notes on quiz-answer randomisation.
• [3] Kiro CLI documentation, Agent Skills, how a Kiro skill is a folder with a SKILL.md (name + description frontmatter, markdown instructions) that the agent loads by matching the description.
• [4] Kiro CLI documentation, Hooks, running a command at agent-lifecycle and tool-execution points, including after a tool such as the file-write tool runs.
• [5] Sample code on GitHub, explain-diff for Kiro CLI, the ported skill, the sample diff, and the generated HTML explainer.
• [6] Geoffrey Litt, background and further work from the talk’s author.

About the Author

Stefan Christoph is a Principal Solutions Architect at AWS, focused on agentic AI, media & entertainment, and helping builders move from demo to production. He writes about AI architecture, developer productivity, and the future of software.

This is a personal blog. Opinions expressed here are my own and do not represent the views or positions of my employer.

Learn more →

• AgenticAI
• AICoding
• DeveloperExperience
• Kiro
• LLMs