---
name: explain-diff-html
description: Rich HTML explanation of a code change, diff, branch, or PR, with diagrams and a quiz.
disable-model-invocation: true
metadata:
  version: "0.2.0"
---

# Explain Diff

Build a rich, interactive explanation of the specified code change as a single self-contained HTML file, written with the clarity and flow of Martin Kleppmann: classic style, engaging, smooth transitions between sections.

## Sections

- **Background**: the existing system relevant to this change. Explore the surrounding code broadly for this. The reader's prior knowledge is unknown, so open with a deep background for beginners, marked as skippable, then a narrower background directly relevant to the change.
- **Intuition**: the essence of the change, not the full details, with concrete toy-data examples and diagrams used liberally.
- **Code**: a high-level walkthrough of the changes, grouped and ordered so they are understandable.
- **Quiz**: five interactive multiple-choice questions so the reader can confirm they actually understood. Medium difficulty: answerable only by someone who understood the substance of the PR, with no gotchas. On click, tell the reader whether they were correct and give feedback.

## Format

- One long page with section headers and a table of contents; inline CSS and JavaScript; responsive so it reads on a phone.
- Save outside the repo at `/tmp/YYYY-MM-DD-explanation-<slug>.html`, today's date first so the files sort by time and stay out of version control.
- Diagrams are built from HTML elements. Pick a small number of diagram families and reuse them across cases: a simplified version of the UI the user sees, to explain UI changes; a system diagram of data flow or communication between components, carrying example data.
- Lists are HTML lists; callouts mark key concepts, definitions, and important edge cases.
- Code blocks are `<pre>` tags, or a styled div whose CSS includes `white-space: pre-wrap`; otherwise the browser collapses the newlines. Done when every code block in the saved source has `white-space: pre` or `pre-wrap`.