explain-changes

Explain Changes Skill

Transform git diffs into meaningful explanations covering what changed, why, and what it means.

Getting the Diff

When invoked via the /explain command, the command handles argument parsing and git commands. When invoked standalone (e.g., user says "explain what changed" mid-conversation), obtain the diff yourself:

1. Run git status --short to see the current state
2. Run the appropriate git diff variant — see references/git-commands.md for the command table, untracked file handling, and binary file guidance

Process

1. Categorize Changes

Group by type:

• Feature - New functionality
• Bug fix - Behavior corrections
• Refactor - Restructuring without behavior change
• Config - Settings, dependencies, build
• Docs - Comments, READMEs
• Tests - Test additions/modifications

2. Explain Each Group

For each category:

• What changed - Specific files, functions, logic
• Why - Inferred motivation and intent (see "Inferring Intent" below)
• Impact - Effects on codebase behavior

3. Add Educational Insights

Include ★ Insight blocks when the change demonstrates a non-obvious pattern, makes an interesting trade-off, or teaches something a mid-level developer might not know. Skip insights for routine changes — not every file rename or version bump needs one. One good insight is better than three filler ones.

Good candidates for insights:

• Design patterns demonstrated
• Best practices followed or violated
• Architectural decisions and their trade-offs
• Subtle gotchas the change avoids or introduces

Inferring Intent

The "why" is the hardest and most valuable part of an explanation. Use these strategies in order:

1. Commit messages - If explaining committed changes, the commit message is the most direct signal of intent
2. PR/issue references - Look for issue numbers, ticket IDs, or PR descriptions in commit messages
3. Code context - Naming patterns, comments, and surrounding code often reveal purpose (e.g., a function renamed from getUser to getUserOrThrow signals error-handling intent)
4. Change shape - The pattern of modifications hints at goals: adding validation across multiple endpoints suggests a security hardening effort; extracting repeated code into a helper suggests a DRY refactor
5. Be honest about uncertainty - When intent is genuinely unclear, say "The motivation isn't obvious from the diff alone" rather than fabricating a plausible-sounding explanation. A wrong "why" is worse than an honest "unclear"

Handling Large Diffs

For diffs spanning 20+ files or 500+ lines:

1. Start with a high-level summary - "This changeset touches N files across M areas of the codebase"
2. Group by area/module rather than listing every file individually
3. Prioritize significant changes - Focus detailed explanation on logic changes; mention config/formatting changes briefly
4. Call out the core change - Often a large diff has one or two key changes with many follow-on modifications. Identify and explain the core change first, then explain the ripple effects.

Output Format

## Changes Explanation

[1-2 sentence summary]

### [Category]: [Title]

**What changed:**
- [Specific change with file/function names]

**Why:**
[Motivation and intent]

`★ Insight ─────────────────────────────────────`
[Educational points about patterns or practices]
`─────────────────────────────────────────────────`

## Summary

[Overall summary and important notes]

For output quality reference, see references/examples.md.

Guidelines

• Be specific - Reference exact file names, line numbers, function names
• Infer intent thoughtfully - Use the strategies above; don't guess
• Stay focused - Explain actual changes, don't speculate about improvements
• Distinguish staged/unstaged - When relevant, note what's ready to commit
• Scale your depth - Small diffs get detailed line-by-line treatment; large diffs (20+ files or 500+ lines) get grouped high-level summaries with deep-dives on the important parts