| name | analyze-changes |
| description | Analyze git changes (branch, commit, or current branch) and produce a design-oriented markup document with Mermaid diagrams, query/usage examples, data walkthroughs, PR context, and impact assessment. |
| argument-hint | [branch-name | commit-sha] |
| user-invocable | true |
Analyze the git changes specified by the argument and produce a design-oriented analysis document.
Input
The argument $ARGUMENTS is either:
- Empty / not provided — analyze the current branch compared to
develop
- A commit SHA (short or full) — analyze that single commit
- A branch name — analyze all commits on that branch relative to
develop
Steps
1. Determine the input type and gather changes
If $ARGUMENTS is empty or blank, get the current branch name:
git rev-parse --abbrev-ref HEAD
Then treat it as a branch name (see branch handling below).
Otherwise, run these git commands to figure out what was provided:
git cat-file -t "$ARGUMENTS" 2>/dev/null
git branch --list "$ARGUMENTS"
-
If it resolves to a commit and is not a branch name (git branch --list "$ARGUMENTS" is empty), treat it as a single commit SHA. Gather:
git show --stat <SHA>git diff <SHA>~1..<SHA> (the full diff)git log -1 --format="%H%n%s%n%b" <SHA> (commit message)
-
If it resolves to a branch, gather:
git log --oneline develop..<branch> (all commits on the branch)git diff develop...<branch> (combined diff)git log --format="%H%n%s%n%b%n---" develop..<branch> (all commit messages)
2. Check for an associated Pull Request
Use gh to find a PR associated with the branch or commit:
gh pr list --head "<branch-name>" --json number,title,body,comments,reviews,url --limit 1
gh pr list --search "<SHA>" --state all --json number,title,body,comments,reviews,url --limit 1
If a PR is found:
3. Read all changed files at their final state
For every file that was added or modified in the diff, use the Read tool to read the final version of the file. This gives you the full source to understand the design, not just the diff hunks.
4. Analyze the changes
Study the diff, commit messages, PR description, and PR comments carefully. Identify:
- Purpose: What is the overall goal of these changes?
- Architecture: What are the new algorithms, data structures, and execution flows? How do they connect?
- Concrete usage: What queries, API calls, or scenarios trigger each new code path? What does the old behavior look like vs the new?
- Non-trivial decisions: Why was this approach chosen? What trade-offs were made?
- Trivial parts: Simple renames, formatting, config — note briefly, don't over-analyze.
5. Generate the markup document
Create a file named changes-analysis-<identifier>.md in the project root directory, where <identifier> is the short SHA or branch name (sanitized for filenames — replace / with -).
The document MUST follow this structure:
# Change Analysis: <short description>
**Ref**: `<SHA or branch name>`
**PR**: [#<number> <title>](<url>) *(if PR exists, omit section if no PR)*
**Date**: <commit date(s)>
**Author**: <author(s)>
## Summary
<2-5 sentence high-level summary of what these changes accomplish and why.>
## Design
<Start with the shared concepts that apply across all changes: the overall
algorithm/approach, common data structures, shared invariants, configuration.
Then break into per-feature/per-algorithm subsections.>
### <Shared concept: e.g., overall algorithm, detection pipeline>
Provide a table mapping each feature to its trigger condition, implementation class, data structure, and real-world impact (benchmark numbers if available).
| Feature | Trigger | Implementation | Data Structures | Impact |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |>
: Low / Medium / High
:
:
:
Important Rules
-
Design-first, not file-first. Never organize the document by file, by diff hunk, or by commit. Organize by algorithm/feature. A single feature may span multiple files — the document should explain it as one unit. Each section should be self-contained: a reader should understand one feature without reading the others.
-
Every feature section must have a concrete example with a data walkthrough. Abstract algorithm descriptions are insufficient. Show real values flowing through the system. For database changes, use actual SQL queries (from benchmarks or tests) and walk through with sample data. Show both old behavior and new behavior with cost comparison.
-
Mermaid diagrams are REQUIRED for non-trivial changes. Use:
- Flowchart for decision logic, algorithm flow, execution paths
- Class diagram for new type hierarchies and relationships
- Sequence diagram for multi-component interactions
- State diagram for state machine changes
Place diagrams INSIDE the feature section they belong to, right after the algorithm description and before the example. Do not collect all diagrams in one place.
-
Do NOT include a "Changed Files" table. It duplicates what git diff --stat already shows and adds no design insight. The document is about understanding, not inventory.
-
Do NOT use file:line references. They go stale after any rebase or edit and clutter the text. Refer to classes and methods by name (e.g., "traceBackwardBranch() in MatchExecutionPlanner"). The reader can find them with grep.
-
Shared concepts go at the top of the Design section. If multiple features share a data structure, an invariant (like context isolation), a safety mechanism (like a runtime fallback), or a configuration knob — describe it once before the per-feature sections, not repeated in each.
-
Explain WHY, not just what. Use commit messages and PR description for motivation. When a design choice has trade-offs, state them. When something looks redundant (e.g., a check that always passes with current data), explain when it matters.
-
Be honest about limitations. If a feature is only exercised by synthetic tests and not by any production query, say so. If a pattern never actually filters in symmetric cases, explain what the real win is (cost reduction, not filtering).
-
Use the Agent tool with if you need to understand surrounding code context that isn't in the diff — e.g., to find which real queries trigger a new optimization, or to understand the old behavior being replaced. When the question is reference-accuracy (callers/overrides/usages of a Java symbol, "is this slot consumed anywhere", "which classes implement this interface"), instruct the Explore sub-agent in its prompt to , when the mcp-steroid MCP server is reachable per the SessionStart hook. Sub-agents default to grep otherwise; an unannotated delegation routes through grep and silently misses polymorphic call sites and identifiers in Javadoc/comments. See § MCP Steroid → "Grep vs PSI — when to switch" for the full routing rule.
