Explain Diff (HTML)

AI is helping us write code faster than ever.

That's great, but there's also a side effect: we're generating more code, reviewing bigger changes, and sometimes understanding less of what actually happened.

You open a PR and suddenly there are hundreds, maybe thousands, of changed lines across a bunch of files.

Git shows you the diff file by file.

controller.ts

service.ts

utils.ts

tests...

But that's usually not how the change actually works.

So where do you start?

Which file matters first? What calls what? Why was the change needed? How does the data move through the system?

And that's where PR reviews can start becoming difficult.

For me, PRs have always been one of the best ways to learn a codebase. You look at someone else's changes, follow the flow, understand why they made certain decisions, and slowly build a better mental model of the system.

As AI generates more of the implementation and PRs keep getting larger, I didn't want to lose that learning opportunity.

That's where explain-diff-html came from.

Instead of explaining a change in the order Git happens to show the files, it tries to follow the logical flow of the code.

So instead of:

file A → file B → file C

it might explain it as:

request → handler → service → transformation → result

It looks at the diff, the surrounding code, callers, related definitions, commits, and documentation, then turns all of that into a walkthrough that tries to answer a simple question:

"If I actually want to understand this PR, where should I start and how does everything connect?"

And it's not limited to PRs.

Hand it a bug investigation or an RCA alongside the diff, and it connects the reported failure to the fix.

Where it helps, below, covers that and the other uses.

The goal isn't just to tell you what changed.

The goal is to help make PR reviews, debugging, and code investigation a learning opportunity again.

The main use is reading a pull request before you review it. Three others come up often.

Onboarding. Point it at the old merged pull request that introduced something foundational rather than at documentation written a year ago. A new hire gets a walkthrough built from the code as it actually is.

Large or machine-written changes. Git orders a diff by path, so a change spanning controllers, services, and models arrives in an order nobody wrote it in. The page orders it by the path a request takes. That matters most on pull requests an agent produced, where the volume outruns what a reviewer can hold at once.

Bug fixes and post-mortems. Hand the skill your incident report or investigation notes alongside the diff. The page connects the reported failure to the fix, so the reader sees where the bug lived and why the patch closes it.

gh must be authenticated, not only installed. Check with gh auth status.

Node is a build-time validator only. Nobody needs Node to open a finished page, because the reader's browser loads Mermaid from the CDN.

The skill's commands are POSIX shell, so it runs on Linux and macOS directly, and on Windows through WSL or Git Bash. Windows PowerShell and cmd.exe are not supported: they have no command -v, no $(...) substitution, and none of mktemp, sed, or openssl. The generated page itself is plain HTML and opens in any browser on any platform.

SKILL.md drives the agent through eight steps. In outline:

1. Resolve the target and the filename key, detecting the repository's default branch rather than assuming main.
2. Gather context: the code around the diff, the pull request body, the commit messages, and any design records the repository keeps.
3. Draft the four sections, walking the code in flow order.
4. Build the diagrams, from three families of plain HTML and CSS, plus Mermaid for state, entity-relationship, and sequence.
5. Write the quiz to the question shapes that test transfer rather than recall.
6. Hand the prose to a fresh reader for an editing pass, because an author misses their own tells.
7. Run the self-check, including re-reading every cited file:line at the target ref.
8. Write the file.

Steps 4 to 7 keep a short summary in SKILL.md and send the agent to a file in references/ for the detail: diagrams.md, quiz-design.md, writing-quality.md, and validation.md. The commands step 7 runs are in scripts/validate-output.sh.

Step 7 carries two checks that exist because of past failures. It confirms every code block is HTML-escaped, because a single raw < in a pasted diff line opens an element HTML never closes, which swallows the rest of the document and breaks every anchor below it. It also re-reads each cited line at the target ref, because a stale ref produces line numbers that look right and point at nothing.

Everything visual lives in skills/explain-diff-html/html-template.html, which the skill fills in rather than rebuilding per run:

• Colors are CSS custom properties at the top, in a light set and a dark set. Change the two blocks to match your own palette.
• The three hand-built diagram families are plain markup: a simplified UI mockup, a data-flow diagram with example payloads on the arrows, and a node tree for recursive structures.
• The Mermaid loader pins an exact version and checks it with a Subresource Integrity hash. To change versions, edit the @x.y.z in the src and recompute the hash. references/diagrams.md carries the command. A stale hash makes the browser block the script, and the diagrams then fail silently.
• The output directory and the filename pattern are in SKILL.md, under the output contract.
• Every page ends with a credit line: "Generated with explain-diff-html", linked to this repository. Delete the <footer class="colophon"> element to remove it. The .colophon rules style nothing else, so delete those too.