# Diff Visual > Catch up on a git change before you review it — background on the system it lands in, the idea behind it, a literate diff of the real extracted code, and a five-question quiz. Use whenever the user wants to understand, explain, walk through, or get up to speed on a diff, branch, commit, or PR — including agent-written code they didn't write themselves, or a teammate's PR they're about to review. Also use for "visualize this diff" and "what changed here". Accepts branch names, commit hashes, HEAD, PR numbers, or commit ranges. - Skill: `leejuoh/diff-visual` (Agent Skill) - Install (CLI): `npx skillmds@latest add leejuoh/diff-visual` - Raw SKILL.md: https://api.skillmd.com/api/skills/leejuoh/diff-visual/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: LeeJuOh (https://skillmd.com/u/leejuoh) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/leejuoh/diff-visual --- # Diff Visual Catch a reader up on a change **before** they review it. Most code now arrives written by an agent, which means the reader has no system already in their head — so the report answers, in order: what was here before (**Background**), what the idea is (**Intuition**), how the code realises it (**Code**), and whether the reader actually got it (**Quiz**). **When to run** - Your agent finished a task and you're about to push — read it, pass the quiz, then send. - A teammate's PR is waiting — read it before you form an opinion. The quiz is a speed regulator, not a gate. Nothing blocks a push (ADR 0003); "don't send it until you can pass" is a rule the reader keeps, not one the tool enforces. And nothing in the report says whether the change is *good* — that judgement is `/code-review`'s and the reader's. **Voice**: write like Martin Kleppmann — clear, flowing, each section handing off to the next. Follow every abstract sentence with something concrete. Output is a self-contained interactive HTML page (default) or an inline markdown report. You write it directly — no templates, no intermediate JSON, no agent chains. ## Instructions ### Format Detection Parse `--format` first: | Flag | Values | Default | Meaning | |------|--------|---------|---------| | `--format` | `html` \| `md` | `html` | `html` → full interactive page at `${CLAUDE_PLUGIN_DATA}/reports/`. `md` → inline markdown report, delivered in the response | | `--local` | switch | off | Force the local design-system file — capable HTML **publishes to an Artifact by default** | | `--artifact` | switch | retained no-op alias | Already the default on capable HTML — kept so muscle memory / natural-language triggers don't break | **Channel is decided by the shared contract**, not re-derived here — read `${CLAUDE_PLUGIN_ROOT}/references/design-system/channel-decision.md` (SSOT, restates ADR 0009) for the `(Format × capable) → channel` table, flag semantics, and the optimistic-try-then-regenerate rule. The short version: **capable HTML publishes to a claude.ai Artifact by default**; `--local` forces the local page; `md` and non-capable sessions stay local. `--local` forces local (Mermaid diagrams, zoom/pan) and triggers on natural-language equivalents — "keep it local", "don't publish", "just the local file" — in whatever language the user writes. `--artifact` is the retained alias for the now-default behavior and still triggers on "as an artifact", "publish as a link", "share as a URL"; if both are signalled, `--local` wins. Both apply to `--format html` only. If `--artifact` is combined with `--format md`, ignore it and use the normal markdown response path below — publishing a diff-visual md report as-is is out of scope for this slice (doc-visual's simpler single-file input validated that combination first; diff-visual's diff scope makes it a separate follow-up). **Config precedence.** Explicit this-turn signal > config > default. Before falling back to the default, check stored preferences once: `node ${CLAUDE_PLUGIN_ROOT}/scripts/config.js get` (prints the config as JSON, or `{}`). A `default_format` value replaces the `html` default. For the channel: an **absent `artifact` key means artifact-first** (the default), `artifact: false` is a **persistent force-local** (the config twin of `--local`), and `artifact: true` is explicit artifact-first. Anything the user actually says this turn — a literal flag or a natural-language equivalent — always overrides config; config only fills in when the request is silent on format/channel. ### Scope Detection Parse the user's argument to determine the diff scope: | Input | Interpretation | Git command | |-------|---------------|-------------| | `HEAD` or nothing | Uncommitted changes | `git diff HEAD` | | `branch-name` | Branch vs main/master | `git diff main...branch-name` | | `#123` or PR URL | Pull request diff | `gh pr diff 123` | | `abc1234` | Single commit | `git show abc1234` | | `abc..def` | Commit range | `git diff abc..def` | | `abc...def` | Three-dot range | `git diff abc...def` | **Default base**: If the scope implies comparison against a base branch, detect the default branch: ``` git rev-parse --verify main 2>/dev/null || git rev-parse --verify master ``` **Scope validation**: Verify the ref/range exists before proceeding. If invalid, inform the user and stop. ### Language Detection Determine the output language: 1. **Explicit argument**: `--lang ` (e.g., `--lang ko`, `--lang fr`, `--lang zh`) → use that language. Any language code is valid 2. **User message text**: Detect the language of the message (excluding ref/path) and match it - Examples: Korean text → Korean, Japanese text → Japanese, "en español" → Spanish, "auf Deutsch" → German 3. **Ref-only with no other text**: Default to English ### Intent Check *Why: how much of this subsystem the reader already knows is the one thing that changes the shape of the report — it decides whether the deep Background layer opens or stays folded. And a reader who names what they're unsure about gets Intuition and Code aimed there.* If the user's message already conveys this (says what they know, or names what they're after), skip this step and proceed with defaults. If the request is bare — a branch name and nothing else — use AskUserQuestion for up to 2 questions: 1. **Familiarity**: How well do you know this part of the codebase? (new to it / worked in it before / I wrote most of it) 2. **Focus**: Anything specific you want to understand about this change? How the answers land: *new to it* → deep Background written and left **open**; *worked in it* or *I wrote it* → deep Background still written but **collapsed**, and kept short. A named focus pulls weight into that part of Intuition and Code. Defaults (when not specified): treat the reader as new to the subsystem, deep Background collapsed, attention spread evenly across the change. ### Data Gathering *Why: the diff tells you what moved. It never tells you what the thing was — and "what the thing was" is the whole first half of a catch-up. Half of this step reads the change; the other half reads the world the change lands in.* Run git commands in parallel where possible. **Step 1 — Stats and metadata** (parallel): ``` git diff {scope} --stat git diff {scope} --name-status git log {scope-log-range} --oneline --format="%h %s" git log {scope-log-range} -- CHANGELOG.md (CHANGELOG update check) ``` Where `{scope-log-range}` is: - For branch: `main..branch-name` - For range: `abc..def` - For single commit: `-1 abc1234` - For HEAD: `-1 HEAD` (or recent commits if uncommitted) **Step 2 — Change shape**: - Files changed, new files, deleted files (from `--name-status`); lines +/− from `--numstat` - These numbers ground your prose; they are no longer a section of their own **Step 3 — Content analysis**: Read the full diff **and the changed files in full** — a hunk without its file is missing the context that makes it mean anything. Establish: - What the change does, and which functions/types/endpoints it touches - Which imports and call sites appear or disappear — this alone decides whether the dependency picture in Code exists at all (D5: no change, no picture) **Step 4 — Surrounding-code exploration** (Background's raw material): Read *outward* from the changed files until you could describe this subsystem to someone who has never opened it. Use Glob + Grep: - Callers and callees of every changed function (grep the symbol repo-wide) - The module the changed files live in — its entry point, its core data structures, its README - Tests exercising the changed behaviour — they state the old contract in executable form - Existing similar code, so the idea can be framed as "like X, but …" Note each finding as `file:line`. Background prose needs sources exactly as much as numbers do. ### Verification Checkpoint *Why: Background and Intuition are **authored**, not lifted — that is a real step beyond re-structuring, and the fact sheet is what keeps it honest.* Before generating the report, **produce a structured fact sheet** listing every claim you will present: 1. **Quantitative check**: Lines +/−, file counts, module counts — all must match git output exactly 2. **Name check**: Every function name, type name, file path you mention must exist **either in the diff or in a source file you actually read** during Step 4 — cite it as `file:line`. (Background describes code the diff never touches; that prose is grounded by the read, not by the diff.) Diagrams are prose too: **node labels and edge endpoints come only from this verified set of names** — never invent a box or an arrow for something you haven't confirmed at a `file:line`. A made-up arrow teaches a relationship the system doesn't have, which is the same failure as a retyped snippet that drifted. This is a writing discipline you keep, not something a gate can check for you (ADR 0011) — the fact sheet is the only place it gets enforced. 3. **Behavior check**: Every behavioral description must be traceable to specific code 4. **Source citation**: For each claim, name the source (commit hash, `file:line`, diff hunk) 5. **Verdict check**: No claim asserts quality. If a sentence contains *should*, *bad*, *better*, *recommended* (or their equivalent in the output language), rewrite it as a fact or drop it If a claim can't be sourced, remove it or mark it uncertain. ### Report Generation Use extended thinking for the analysis above. The depth of analysis directly determines report quality. **HTML channel routing (default = Artifact).** For `--format html` the channel is decided by `${CLAUDE_PLUGIN_ROOT}/references/design-system/channel-decision.md`: on a capable account the default is the **Artifact channel** — go to "HTML mode — Artifact channel" below. Write the **local design-system + Mermaid** page only when `--local` is in play, or as the **non-capable regenerate fallback** after a publish attempt fails (see "Publish"). `md` is unaffected — it stays local either way. #### The four sections (all formats, all channels) Fixed order, no tabs, one page, table of contents at the top. Every format below renders *these* sections; only the rendering technique changes. | # | Section | What it holds | |---|---|---| | 1 | **Background** | The world before the change. Two layers: deep (the subsystem, collapsed by default) then narrow (the specific code the change touches, always open) | | 2 | **Intuition** | The idea in one paragraph + a toy-data example + before/after flow diagrams carrying that example data | | 3 | **Code** | The literate diff — the change walked in understanding order, snippets lifted by extraction. Dependency before/after picture first *if* dependencies changed. Full diff as a collapsed appendix at the bottom | | 4 | **Quiz** | Five medium multiple-choice questions with click-through feedback | **1 — Background.** Written from Step 4's exploration, not from the diff. - *Deep layer*: the subsystem this change lands in — what it is for, how a request moves through it, which data structures matter. Enough that someone who has never opened this repo can follow what comes next. Collapsed by default (the second PR in the same repo shouldn't re-scroll it); open when Intent Check said "new to it". - *Narrow layer*: the specific functions, files, and data the change touches — as they were **before**. Always open. This is the sentence the reader will hold in their head while reading Code. - Both layers describe existing code, so every name traces to a `file:line` you read. **2 — Intuition.** The reader should finish this section able to state the change in their own words. - *The idea*, one paragraph: what this change is trying to accomplish. Not how — that's Code. - *A toy-data example*: one small concrete input and what happens to it, as a short table or list. Small enough to trace by hand. Abstract descriptions slide off; a single traced example sticks. - *Two flow diagrams*, before and after: the path the request/data takes. **They must carry the toy example's actual data as labels** — a picture of unlabelled boxes leaves the reader exactly where they started. Keep to one diagram family and reuse it across the report. - *Phantom notation for what's gone*: anything the change removed or relocated stays on the "after" side as a **dotted** node or edge rather than silently vanishing — half of what a before/after pair is for is showing the reader what disappeared, and a box that is simply absent reads as an oversight. Mermaid (`--local` and md): dotted edge `-.->` plus the `phantom` classDef from `mermaid-patterns.md` — plain dotted already means optional/async there, so the faded class is what separates "gone" from "sometimes taken". Inline SVG (Artifact channel): `stroke-dasharray="4 3"` at reduced opacity. Label it with the fact alone — `removed`, `moved to session.ts` — never why it went (no verdicts). - No implementation detail here. If you're naming a function signature, you're in Code's territory. **3 — Code — the literate diff.** Prose that walks the change in **understanding order**, with extracted snippets embedded where they're being discussed. Not file-by-file: group the hunks that belong to one idea even when they live in different files, and lead with whichever one the rest depends on. - *Extraction law (ADR 0005)*: every code block is `extract-hunks.js` output pasted verbatim. You write the prose around it and never a line inside it. A reader who doesn't know the code cannot notice when a retyped snippet has drifted — a wrong snippet teaches a wrong system. ```bash node ${CLAUDE_PLUGIN_ROOT}/scripts/extract-hunks.js [line-range] # PR with no local refs: gh pr diff | node ${CLAUDE_PLUGIN_ROOT}/scripts/extract-hunks.js --stdin [line-range] ``` - *Budget*: 3–8 snippets, ≤150 lines each (`structured-blocks.md`). These are the pieces the reader must see, not every touched file. Read `structured-blocks.md` before writing the section — layout, highlighting, and degrade rules live there. - *before/after vs after-only*: show both sides only where "what became what" is the point. Everywhere else, the after side alone reads faster. - *Dependency picture* — the section's **first** block, and only when imports or call sites actually changed: two box-and-arrow pictures, before and after, distinguishing new arrows, removed arrows, and cycles by colour or style — removed arrows and dropped modules take the same phantom (dotted) notation as Intuition, so "gone" looks the same everywhere in the report. Caption states facts only ("`auth.ts` now calls `session.ts`"; a cycle gets a ⚠️ marker and nothing more). No verdict sentence. If dependencies didn't change, the block doesn't exist — don't render an empty one. - *Appendix*: the complete diff, once, in a collapsed block at the very bottom. The report must not grow to the length of the diff. **4 — Quiz.** Five multiple-choice questions, medium difficulty. - Answerable only by someone who understood the change — not by re-reading a line number, not by general knowledge. No gotchas, no trick wording. - **Options length-matched**: word counts within ±1 across the options of a question, and don't write the correct answer more fully than the others. Form must leak nothing, or the reader passes by shape instead of understanding. - Clicking an option reveals right/wrong **plus one sentence per option** saying why it is or isn't the case — the moment right after a wrong guess is when the explanation lands. - HTML (both channels): inline `