# Explain Diff

> explain-diff when turning a git diff, branch, or pull request into a self-contained HTML teaching page.

- Skill: `prathamdby/explain-diff` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add prathamdby/explain-diff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prathamdby/explain-diff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: prathamdby (https://skillmd.com/u/prathamdby)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/prathamdby/explain-diff

---


# Explain diff

## Flags

| Flag                | Default                               | Effect                           |
| ------------------- | ------------------------------------- | -------------------------------- |
| `--target <branch>` | `main`                                | Explain `<branch>...HEAD`        |
| `--pr <n\|url>`     | off                                   | Explain one PR diff and metadata |
| `--staged`          | off                                   | Explain the index                |
| `--unstaged`        | off                                   | Explain worktree changes         |
| `--output <path>`   | `/tmp/YYYY-MM-DD-explain-<slug>.html` | Set HTML path                    |

The four source choices are mutually exclusive; conflicting or valueless flags
are `BLOCKED`; bare `--pr` is the only value-less exception and may resolve the
current branch PR. With no source flag, use the equivalent of `--target main`.
Block when PR diff cannot be fetched. Missing optional PR metadata permits a
diff-only page with no motive claims.

## 1. Lock source and output

Capture source identity, head SHA, exact diff, sorted paths, and SHA-256 diff
hash. Empty diff is `NO_CHANGES`. Derive slug from sanitized branch name, PR
number, or `change-<head8>`, capped at 40 characters.

Resolve output to an absolute path outside the repo; an explicit in-repo path is
`BLOCKED`, never relocated. Create a missing parent. Block before overwriting a
user-supplied existing file. A default output may replace only a prior artifact
containing this skill's generator marker.

Record:
`source/hash | theme(name/paths/path-hash/gate) | evidence | output | gate | verification | terminal`.
Gate is `lock`, `research`, `build`, or `verify`. Persist beside the output as
`<output>.ledger` after every gate and completed theme. Resume an active ledger
only when output and source hash match; otherwise `BLOCKED`. Remove on success.

Done when source and safe output are immutable.

## 2. Group and research

Assign every changed path to a functional theme before reading surrounding
code. For more than 50 paths, explain themes through representative hunks and
include every sorted path without truncation. Represent a rename as
`old → new`; list generated or binary paths under those themes and make no
behavioral claim without text hunks. Give path-only inventory rows
`data-hunk="<path>:inventory"`. Use at most 12 themes, three
surrounding files per theme, and 30 surrounding files total. Read direct
definitions, callers, contracts, tests, and config only when a planned claim
needs them.

Done when every path has a theme and each planned claim has a hunk or read-file
pointer.

## 3. Build the teaching page

Load `./REFERENCE.md`. Write one HTML file in this order: Background, Intuition,
Code, Quiz. Include a table of contents, inline CSS and JavaScript, responsive
layout, and only HTML or inline-SVG diagrams. Code sections group by theme,
with the complete inventory for large diffs.

Every factual sentence about the change traces to a hunk. Every system claim
traces to a surrounding file. Remove unsupported intent, motive, or PR claims.

Done when the file exists with all four non-empty sections and five grounded
quiz questions.

## 4. Verify and report

Apply the reference checklist. Verify no external asset URL, all anchors,
generator marker, code whitespace, evidence pointers, and quiz answer feedback.
When a browser tool exists, load the file and test one correct and one incorrect
answer for every question; otherwise parse JavaScript and HTML and disclose
`verification: static-only`. A browser run reports `verification: browser`.
Recompute the live source fingerprint before `SUCCESS`; drift is `BLOCKED` so
the page never mixes snapshots.

After interruption, compare source hash and ledger. Restart changed themes;
otherwise continue at the first incomplete gate.

Report absolute path, source, theme and file counts, quiz count, and verification
level. Do not paste the HTML. Terminal values are `SUCCESS`, `NO_CHANGES`, and
`BLOCKED`. Never commit, push, or mutate a PR.