| name | summary |
| description | Summarize the most recent commit or pending changes — what they do, how they fit into the existing code, and a diagram if the change is structural. |
Change Summary
Core Rule
EXPLAIN WHAT THE CHANGE SHIPS AND HOW IT FITS — NOT WHAT FILES MOVED OR WHAT LINES CHANGED.
The output should let someone who hasn't touched the code in a week immediately understand what the change is, why it matters, and how it connects to the existing system. Keep it short enough to read in under 30 seconds.
Phase 1: Determine scope
Run these in order and use whichever produces output first:
git diff HEAD — unstaged working tree changesgit diff --cached — staged-only changesgit show HEAD — most recent commit
If none of these produce output (brand-new repo with no commits), say so and stop.
Phase 2: Gather context
- Get the file-level summary:
git diff --stat HEAD (or git show --stat HEAD if falling back to the commit)
- Read the full diff — every line of it
- For each file that changed substantially, read the surrounding code in that file: the functions, classes, or modules adjacent to the changed lines. Don't read only the diff lines — understand what the changed code lives inside and connects to.
- If there's a
README.md, CLAUDE.md, or ROADMAP.md at the project root and the change seems architectural, skim it for context on the project's structure and intent.
Goal: understand not just what changed but what role those changes play in the larger codebase.
Phase 3: Produce the summary
Write the output directly — no preamble, no sign-off, no "Here is your summary:".
Format
**[One-line title — the change in plain English]**
[2–3 sentences: what it does and why. Lead with the behavior or capability, not the mechanism.]
[1–2 sentences: how it connects to the existing code — what it replaces, extends, calls into, or is called by.]
[Diagram OR key details — see below]
Diagram vs. prose
Use a Mermaid diagram when the change involves any of:
- Data or control flow between components
- A new call chain or middleware layer
- New wiring between modules (a new service, handler, hook, or event listener)
- Relationships between the new code and multiple existing parts of the system
Use bullet points for contained changes:
- Bug fixes
- Config or constant updates
- Single-function additions with no architectural implications
- Copy or text changes
Diagram rules:
- Mermaid only — no ASCII art
- 4–8 nodes maximum
- Label every edge to show what flows or what triggers what
- Show only what the change introduces or touches — not the whole system
- Use
graph LR for flows, sequenceDiagram for call sequences
Bullet rules:
- 3–6 bullets maximum
- Each bullet is a behavior or consequence, not a file name or line number
Hard Rules
- Target 10–20 lines of output. Never exceed 30.
- No file names, line numbers, or "this was modified in X" narration.
- No padding. Short changes get short summaries.
- If the diff doesn't make the intent obvious, describe what it does — don't invent a "why."
- No questions. No asking for clarification. Run the commands, read the code, write the summary.
