How a Notion engineer reads code

Why reading diffs breaks first

A diff is a line-by-line list of what changed and where. When humans edited code in small increments, reading that list was the review. Changes were small and you were the person who made them, so the list alone was enough to reconstruct the picture.

Agents break both assumptions at once. Dozens of files change in a single pass, and you did not write any of it. That is why scrolling to the end of the list leaves nothing behind — not because information is missing, but because it is not in the order understanding requires.

A common misreading follows. People assume humans must understand code in order to verify it: agents do dumb things, so someone has to keep them in line. But verification is exactly the part agents keep getting better at. Give them a good verification loop and the machine judges correctness more reliably than you do.

The real reason is different. You understand in order to participate. Understanding this change becomes the raw material for the next decision. Rich conceptual structures in your head are what let the next idea appear, and that is the human share of the work. Skip understanding and you can keep passing judgment, but you stop being able to propose anything.

There is a name for the cost: cognitive debt, a term proposed by Professor Margaret-Anne Storey of the University of Victoria and popularized by Simon Willison. It pairs with technical debt. Technical debt accumulates in code; cognitive debt accumulates in people. Static analysis can see the first. The second stays invisible until the bill arrives as "this is my project and I understand it least."

What order a good explanation follows

So what do you read instead of a diff? Litt's framing question: if you sent a team away for a year to build a personalized curriculum explaining this one code change to you, what would that curriculum look like?

The explain-diff document is his answer. It has four parts, and the order is the pedagogy. It is what good math teachers do — give the feel before throwing details at you.

The talk uses a real example: a game where you draw Zen gardens, changed from a top-down view to an isometric one. The document does not open with what changed. It opens with the game engine in use and the shape of the coordinate system, with a note that you can skip ahead if you already know.

Then comes intuition: "the goal of this commit is to make the garden feel three-dimensional using only 2D drawing tricks." Think of it as a well-written commit message with one more layer of depth. The essence arrives before any code does.

Code is third, ordered not by file listing but by what makes sense to read first, with prose ahead of each file explaining what is about to happen. Litt calls this a literate code diff, and says he prints them out and reads them at a coffee shop — work that used to require being glued to an IDE has become textbook reading.

What a skill is and where it lives

explain-diff is not a program. It is a single skill file — which is precisely what confuses people hearing about it for the first time, because there is nothing to install in the usual sense.

In Claude Code, a skill is a markdown document describing "in this situation, do it this way." Put it in the right place and it gets pulled in when it is needed. There are two places: ~/.claude/skills/ in your home folder for everything on your machine, or .claude/skills/ inside a repository for that project only.

The filename must be SKILL.md, and the folder name becomes the skill name. In other words the path ~/.claude/skills/explain-diff-html/SKILL.md is itself the registration step. No config file, no rebuild.

At the top of the document sits a short frontmatter block. name is the skill's name; description says when to use it. That description matters — even if you never call the skill by name, an agent will read the document when your situation matches it. explain-diff-html's description reads: use when the user asks for a rich explanation of a code change, diff, branch, or PR.

Everything below the frontmatter is plain human language: which sections to include, what voice to write in, how to draw diagrams, where to save the file. Not a line of code. That is why customizing it, later in this article, is just editing a document.

---
name: explain-diff-html
description: Use when the user asks for a rich explanation of a code change, diff, branch, or PR. Produces HTML output.
---

Installing it: two commands

The source is one public gist by Geoffrey Litt containing two files. explain-diff-html.md produces a single HTML page; explain-diff-notion.md produces a Notion page. Install either or both — with both installed, whichever fits the request gets pulled in.

Installing means creating a folder and downloading the file into it under the name SKILL.md. Paste the commands below into a terminal. No admin rights, no package manager.

The mistake people make here is the filename. Saving it as explain-diff-html.md will not be recognized. The folder name is the skill name and the file is always SKILL.md — which is why the path after -o looks the way it does.

To confirm it landed, print the frontmatter. If you see the name line, you are done. A Claude Code session that was already open may not see a freshly created skill, so start a new session to use it.

mkdir -p ~/.claude/skills/explain-diff-html
curl -sL https://gist.githubusercontent.com/geoffreylitt/a29df1b5f9865506e8952488eac3d524/raw/explain-diff-html.md -o ~/.claude/skills/explain-diff-html/SKILL.md

# verify — seeing the name line means it is installed
head -4 ~/.claude/skills/explain-diff-html/SKILL.md

mkdir -p ~/.claude/skills/explain-diff-notion
curl -sL https://gist.githubusercontent.com/geoffreylitt/a29df1b5f9865506e8952488eac3d524/raw/explain-diff-notion.md -o ~/.claude/skills/explain-diff-notion/SKILL.md

Running it: what to say

Once installed there is no command to memorize. Open Claude Code inside your repository and ask in ordinary language: "explain what changed on this branch compared to main." The skill's description matches the situation, so the agent follows that document on its own.

You can point it at three kinds of target: a whole branch against main, a range of commits, or uncommitted changes in the working tree. The skill instructs the agent to explore surrounding code rather than only the diff, and the quality of the background section depends on that.

The output is a single self-contained HTML file. CSS and JavaScript live inside it, so opening it in a browser is enough for the quiz to work. It is one long page with a table of contents rather than a set of tabs, with basic responsive styling so it reads on a phone.

The save location is pinned in the skill: a global place outside the code repository, with a filename that always starts with today's date, for example /tmp/2026-08-01-explanation-isometric-view.html. Two reasons — files sort chronologically, and they never wander into version control.

Opening the result is one command: open on macOS, xdg-open on Linux, start on Windows.

Explain what changed on this branch compared to main

# other ways to scope it
Explain the last 3 commits
Explain my uncommitted changes

# find today's explanation documents
ls -t /tmp/$(date +%F)-explanation-*.html

# open it (macOS)
open /tmp/2026-08-01-explanation-isometric-view.html

Using the quiz as a speed regulator

The five questions at the bottom are the heart of the skill. The instructions are specific: medium difficulty, no gotchas, but hard enough that you must understand the substance of the change to answer. They are multiple choice, and picking an answer shows you immediately whether you were right, with an explanation.

Why a quiz? Litt cites Andy Matuschak's "Books don't work" — the claim that it is remarkably hard to notice, on your own, that you finished reading something without understanding it. Matuschak and Michael Nielsen responded by embedding spaced-repetition quizzes inside an essay, producing writing you cannot get through without retaining it.

The same device, moved to code review. Litt's personal rule is one sentence: if he cannot pass the quiz, he does not send the agent's code to his team for review. It sounds silly and it catches him often. The origin was a PR he believed he had read, until a teammate asked the most basic question and he had no answer.

He calls it a speed regulator. Every AI tool pushes in the direction of going faster. Raise the speed of correctness without raising the speed of understanding and cognitive debt accumulates at exactly that gap. The quiz forces the two speeds back together.

If you bring this to a team, keep it as a personal rule. You cannot gate CI on whether a human passed a quiz. Start instead with "attach the explanation document to the review request" — building the document tends to pull the quiz along with it.

How the Notion version differs

explain-diff-notion.md produces a Notion page instead of a file. The structure — background, intuition, code, quiz — is identical; only the output differs.

The difference is collaboration. A file lives on your machine; a Notion page is something a team looks at together. Comments attach to paragraphs, so the explanation itself becomes the place where discussion happens — a teammate can object to the agent's plan right on the line in question. Litt works at Notion, but the point of this variant is building understanding at team scale rather than individually.

One prerequisite: Notion MCP must be connected. MCP is the standard way to let an agent talk directly to an external service; with the Notion connector in place, the agent creates the page and returns its URL. Without it, this skill cannot produce anything.

The quiz is expressed differently too. The HTML version judges clicks with JavaScript; Notion has no such interaction, so the skill uses toggle blocks. You expand options one at a time and each reveals why it is right or wrong. The answer stays hidden until you commit, which is the part that matters.

In the live demo the Notion page even contained an interactive simulation — drag coordinates around and feel what the change did. Litt attaches a warning: interactivity easily becomes a crutch, and easily becomes slop. Build it only where a static picture genuinely cannot do the job.

Adapting it, and the two other techniques

The skill file is ordinary markdown, so edit it. Four places are worth touching. First, the section list — add whatever your team always asks about, such as rollback plans or performance impact. Second, the number and difficulty of quiz questions. Third, the save path and filename convention, if you want these accumulating in a shared folder. Fourth, the voice: the original asks for the clarity of Martin Kleppmann, and you can name a document your team admires instead.

Some parts are better left alone. The original forbids ASCII diagrams and insists on HTML ones, and it requires code blocks to use pre tags — or, if you style your own div, to set white-space to pre-wrap and check every block before saving. That is a failure mode that shows up in practice, so keep the guardrail.

The same talk offers two more techniques. One is microworlds: having the agent build software that exists only to help you understand and is never shipped. Litt built a debugger that scrubs through the internal execution of a Prolog interpreter he wrote, and when migrating his personal website to another framework, he had the agent build a small game where he clicked through the port step by step. A script would produce the same result, but none of the feel.

The other is shared spaces: humans and agents talking in the same thread, discussions living as comments on documents, coding agents brought inside the team's document space. The problem it addresses is that when everyone talks to their own agent one on one, the team's understanding fragments.

The three techniques share one move. They do not stop at having agents write code; they have agents write the tools that make code understandable. Code got cheap, so disposable tools for understanding got cheap too. Which means the capability can be spent on understanding more, not less — that is the talk's conclusion.