diff-explainer

Files (6)

• SKILL.md
• diff-explainer.css · assets/
• template-diff-explainer.html · assets/
• sample.md · examples/
• diff-explainer.lua · filters/
• build.sh · scripts/

SKILL.md (first lines)

# Diff Explainer

Generate a single self-contained HTML document that explains a git diff to a human
reviewer. The goal is to minimize reviewer cognitive load in a world where AI
generates far more code than humans can read line-by-line: build understanding in
layers (why → mental model → diagrams → guided code walkthrough → review points)
so the reviewer spends attention only where human judgment is actually needed.

This skill is generation only: diff in, HTML file out, written locally. It **reads**
whatever context explains the change (step 1), but changes nothing outside its own
output — no git branch operations, no publishing, no writing to a PR. Distribution
is out of scope: the deliverable is a file on disk, and how it reaches other people
is the caller's problem, not this skill's.

## Inputs

Resolve each input in this order; ask only if genuinely ambiguous.

| Input | Resolution |
|-------|-----------|
| Diff | Caller/user-specified PR number/URL, range, or pathspec → else staged changes if any → else `<merge-base with default branch>...HEAD` |
| Context material | **Collected in step 1** from the diff's provenance. Free-form text from the caller (purpose statement, design notes) is additional, and takes precedence where the two conflict |
| Output path | Caller-specified → else `.agents/diff-explainer/{yyyy-mm-dd}-{branch-or-range-slug}/index.html` |
| Language | Caller-specified → else the dominant language of the context material → else the conversation language |

## Process

### 1. Collect the diff and its context

Collecting context is a **step, not an option**: "Background & Why" is only as good
as what is gathered here, and *how the diff was specified* determines what is
reachable. Take the diff itself first — `git diff --stat <range>` for the shape and
`git diff <range>` for the content (`gh pr diff <n>` when the input is a PR) — then
gather context by input shape.

**A PR (number or URL)** — the richest case:

- `gh pr view <n> --json title,body,url,baseRefName,headRefName` for the PR itself.
- `git log --format='%h %s%n%b' origin/<base>..<head>` for the commit messages.
- **Every issue/PR the body references** — `#N`, `Fixes …` / `Closes …`, and full
  GitHub URLs: fetch title + body (`gh issue view` / `gh pr view`, adding
  `-R owner/repo` for another repository). A change is often only explicable
  through the issue that motivated it, and a cross-repo reference is usually the
  dependency it is built on.
- Do **not** read the PR's review comments. This skill explains the change; it
  neither relays nor pre-empts other people's review findings.

**A range, branch, or single commit**:

- `git log --format='%h %s%n%b' <range>` — commit messages are context even when
  nothing else exists; include trailers (`Fixes`, `Refs`, `Co-authored-by`).
- Expand issue references found in those messages the same way as above.
- If the branch has an open PR (`gh pr view` succeeds), **escalate to the PR case**
  — a branch name alone still reaches the PR body and everything it links to.

**Always, whatever the input was**:

- **This session.** What the user asked for in this conversation is first-class
  context material, and for uncommitted work it is usually the only material that
  exists. Use it rather than inferring purpose from the diff.
- **Repository-local material for the touched paths** — the module README, the
  `CHANGELOG` `[Unreleased]` entry (the author's own user-facing framing of the
  change; its *absence* is itself a signal in a repository that requires one),
  relevant ADRs and design docs, and the module's `CLAUDE.md` / `AGENTS.md`
  conventions. Conventions matter most: they let `risk=` rest on a stated rule
  ("this module targets Java 8, so an API signature change breaks clients")
  rather than on guesswork.
- Read surrounding source files when the diff alone is not enough to explain a
  chunk correctly (e.g. a modified function whose callers matter).

**Budget.** Follow references **one hop only, never recursively** — a linked
issue's own links are out of scope, or collection never terminates. Skip anything
unreachable in silence (a private cross-repo issue, a dead link). Cap at roughly
five references, preferring the ones the body actually leans on.

**Record what was consulted.** List the sources the explanation was built from, in
the background section or the footer. This serves the same purpose as the
verified/inferred split: the reader sees what the explanation rests on — and what
it never looked at.

**When collection still leaves a gap.** If a chunk stays genuinely ambiguous in a
way that would change the explanation — e.g. you cannot tell whether a change is a
behavior change or a pure refactor, which flips its risk level — **ask the user
rather than guessing, when the session is interactive**. When running headless or
delegated by another skill there is no one to ask: fall back to inferring and
marking it inferred (see Background & Why). Reserve the
question for gaps that affect correctness; route minor uncertainty to the
`.inferred-note` path, not to the user.

### 2. Plan the walkthrough

Partition the entire diff into chunks and order them by **understanding order** —
the order in which a reviewer builds a correct mental model — never by file path
order. Typical narrative: core abstraction/contract change first, then call-site
adaptations, then tests, then mechanical fallout.

Classify every chunk's risk:

- **high** — behavior or contract changes, data migrations, concurrency, error
  handling, security-sensitive paths, non-obvious conditionals. These get full
  prose explanation and an expanded diff.
- **low** — mechanical, repetitive changes where reading one instance proves the
  pattern: renames, import updates, generated files, format churn, boilerplate
  test scaffolding. Group them aggressively (one chunk may cover 30 files),
  show one representative excerpt, and collapse the rest.
- **medium** — everything else.

Risk classification is the core value of the document: it is what tells the
reviewer where NOT to spend attention. State the reason for the level in each
chunk ("mechanical rename, verified identical pattern ×12" / "changes retry
semantics — off-by-one here corrupts the queue").

For each chunk also determine, up front:

- **Test coverage** — does the diff itself add/modify a test that exercises this
  chunk? If yes, name the test file; if no, the chunk is *untested* and that is
  where the reviewer's judgment is most needed. "high risk + untested" is the
  single most important thing to surface.
- **Change pattern** — whether the chunk instantiates a recognizable, nameable

From choplin/explainer-studio, MIT.

More from choplin/explainer-studio