explain-diff

/explain-diff

What it does

Reads a git diff and produces a tight English narration of what changed, why a reviewer should care, and where the risk concentrates. Lives next to the vanilla commit workflow (mechanical Conventional Commits message) and /security-review (structured security audit) — covers the "narrative" niche neither does.

Three audience modes:

• --for pr (default) — output is a PR-description-shaped block: ## Summary, ## Why, ## How to verify. Copy-pasteable into the PR body.
• --for review — emphasizes what's load-bearing and what's mechanical; flags non-obvious decisions that the reviewer might miss without the author's voice ("the new IF EXISTS clause on line 47 is load-bearing — without it the migration is non-idempotent").
• --for self — terse 3–5 bullet self-narration; useful before switching context or coming back to a branch later.

Workflow

1. Resolve diff range.

   • Default: git diff HEAD (working tree + staged vs last commit).
   • If $ARGUMENTS starts with ^ or contains .. or ..., treat as a ref range and use git diff <range>.
   • If --for pr and the current branch has commits beyond main, use git diff main...HEAD instead (covers the whole branch).

2. Get supporting context (parallel-OK):

   • git status --short for file-state breakdown.
   • git log --oneline -10 for repo style of commit messages.
   • git rev-parse --abbrev-ref HEAD for branch name.

3. Read the diff in full. If the diff is enormous (>50k tokens estimated), STOP and report: "diff is too large — narrow with --paths <pattern> or <file>...". Don't try to chunk and summarize partial diffs; the result would be incoherent.

4. Walk the diff and identify:

   • Files added vs modified vs deleted.
   • Hunks that look mechanical (renames, type-only changes, formatting).
   • Hunks that look load-bearing (new branches, new functions, condition changes, new dependencies).
   • Test changes (file paths matching *_test.*, *.test.*, tests/, etc.).
   • Doc / config-only changes.
   • Anything that touches a sensitive path (auth*, crypto*, *.env*, routes/, etc.) — surface as a "consider /security-review" reminder, not a substitute for it.

5. Emit narration in the requested shape.

--for pr output template

## Summary

- <one sentence per key change, ordered by importance>

## Why

<one paragraph: the motivation. If the diff doesn't make the motivation
obvious, say so explicitly — "motivation not inferable from the diff;
add to PR body".>

## How to verify

- [ ] <reviewer step 1>
- [ ] <reviewer step 2>
- <commands to run if applicable>

--for review output template

## What changed (load-bearing)

- `file:line` — <description of load-bearing change>
- ...

## What changed (mechanical, low-risk)

- <bulk list, less detail>

## What to look at first

<top 1–2 things the reviewer should NOT skip>

## What's untested

- <files modified without corresponding test changes, IF the language
  conventionally tests, IF the file is non-trivial>

--for self output template

- <bullet 1, ≤80 chars>
- <bullet 2>
- <bullet 3>
[max 5]

Hard rules

• Read-only. No Edit/Write in the tool list. If the user asks "while you're at it, fix X" — STOP and surface that as a separate request.
• Never invent intent. If the diff doesn't make motivation obvious, explicitly say "motivation not inferable from diff" rather than guess.
• Never expand scope to security audit. If sensitive paths show up, ONE LINE: "diff touches routes/auth/... — consider /security-review". Don't try to be that skill.
• Always cite file:line for load-bearing claims.
• Skip noise. Don't list every renamed file individually if there are 30 of them; aggregate ("renamed 30 files from services/old/* to services/new/*").

When to run

• Before opening a PR — paste the --for pr output into the PR body.
• After receiving a code review request from a teammate, run --for review to make sure the diff is honestly readable.
• Coming back to a branch after a few days — --for self to re-orient.

What this skill does NOT do

• Generate the commit message. That's the vanilla commit workflow. They're different shapes: a commit message is per-commit; a PR description is per-branch. Don't conflate.
• Audit for security/correctness. Cite when sensitive paths appear; let /security-review do the actual audit.
• Run tests or verify claims. "How to verify" is suggestions for the reviewer; this skill doesn't execute anything.
• Compare against main automatically in --for self / --for review modes. Default is HEAD (working tree vs last commit). User picks the range explicitly when they want branch-wide.