| name | diff-explain |
| description | Explain a diff in plain English. Works with staged changes, unstaged changes, commits, branches, or PR numbers. Use when you want to understand what changed and why. Keywords: diff, explain diff, what changed, understand changes, diff summary, review changes, read diff |
Diff Explain
Explain a diff in plain, conversational English. Focus on what changed and why it likely changed, not just listing modified files.
Determine the Diff Source
Parse $ARGUMENTS to determine what diff to explain:
| Argument | Command |
|---|
| (none) | git diff (unstaged changes) |
--staged | git diff --staged |
--unstaged | git diff |
A number (e.g., 123) | gh pr diff 123 |
| A commit hash | git show <hash> |
| A branch name | git diff main...<branch> |
Two refs (e.g., v1.0..v1.1) | git diff <ref1>...<ref2> |
Gather Context
- Get the diff using the appropriate command above
- Get the file list:
git diff --stat (or equivalent for the source)
- If it's a PR, also fetch:
gh pr view <number> --json title,body,labels
Explain the Changes
Structure the explanation as:
Overview
One paragraph: what is this change about at a high level? What problem does it solve or what feature does it add?
Key Changes
For each logically grouped change:
- What: which files changed and what was modified
- Why: infer the motivation from the code context
- How: brief description of the implementation approach
Group related file changes together (e.g., "Updated the User model and its tests" rather than listing each file separately).
Notable Details
Flag anything interesting:
- Breaking changes or API modifications
- New dependencies added
- Configuration changes
- Files deleted or renamed
- Potential risks or things a reviewer should look closely at
Summary Stats
Files changed: N
Insertions: +N
Deletions: -N
Guidelines
- Be conversational, not mechanical. "Added a retry mechanism to the HTTP client" is better than "Modified http_client.ts lines 45-60"
- Infer intent from the code. If a function was renamed from
getData to fetchUserProfile, note that the rename improves clarity, don't just say "renamed function"
- Highlight the important parts. A 500-line diff might have one key architectural decision — find it and lead with it
- Note what's missing if relevant: "This adds the API endpoint but doesn't include tests yet"
- Skip boilerplate: don't explain auto-generated changes, lock file updates, or formatting-only diffs unless they're the entire change
