filip-podstavec/claude-leverage/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).

1. 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.

1. 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.

1. 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.

• Load-bearing decisions shipped without an `AIDEV-` anchor (only in

--for review). A load-bearing hunk that encodes a non-obvious choice — an ordering dependency, a perf carve-out, an idempotency trick, a deliberate rejection of the obvious approach — and carries no AIDEV-NOTE: / AIDEV-TODO: / AIDEV-QUESTION: in the added lines is a memory the next agent won't inherit. This is the review-boundary backstop for the ai-first-nudge hook, which only fires on ≥50-LOC single writes and so misses decisions built up incrementally.

1. 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>
 
## Load-bearing but un-anchored
 
-`file:line` — <the non-obvious decision that has no AIDEV anchor;
  suggest the anchor to add, e.g. "AIDEV-NOTE: retry order matters —
  webhook must land before the DB commit">
-<omit this section entirely if every load-bearing hunk is either
  self-evident or already anchored — don't manufacture findings>

--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.