review_changes

Review code changes before staging/committing to understand what was done and why.

WHEN TO CALL: After you (the AI assistant) have made code changes on behalf of the user and BEFORE staging or committing. This lets the user understand what you did at a conceptual level rather than reading raw diffs.

REQUIRED: Before calling this tool, summarize what the user asked you to do. Pass this as the 'goal' parameter. Be specific — "add JWT authentication middleware" is better than "make changes".

HOW TO PRESENT THE RESPONSE — follow this layered approach:

1. NARRATIVE SUMMARY (always show first): Start with a plain-language summary of what changed. Example: "I made 5 changes across 3 files to add JWT authentication." Include the key stats: files added/modified/deleted, lines changed.

2. GOAL ALIGNMENT (group changes by purpose): Look at each changed file and classify it into one of three tiers:

   • KNOWN: Changes that directly relate to the 'goal' you passed. You know these because you made them for the stated purpose.

   • INFERRED: Changes whose context_clues (comments, docstrings) suggest a clear purpose different from the stated goal. These may be from a different AI agent session. Describe the inferred purpose.

   • UNKNOWN: Changes with no clear connection to any goal AND no useful context clues. Flag these — the user should review them.

3. PER-FILE BREAKDOWN: For each goal group, list the files with a short description of what changed. Read the diff to explain HOW the goal was achieved:

   • What functions/classes were added or modified?

   • What's the approach? (e.g., "Added middleware pattern using decorators")

   • Any notable implementation choices?

4. ATTENTION GUIDE: Tell the user what needs their eyes vs what's routine:

   • NEW FILES: "I created auth/middleware.py — worth a quick review"

   • MODIFIED FILES: "Added 3 lines to config.py — routine import addition"

   • UNKNOWN CHANGES: "utils.py was modified but doesn't match the goal — please check"

   • LARGE CHANGES: Any file with 50+ lines added deserves a mention

5. DETAIL ON DEMAND: End with: "Want me to walk through any specific file in detail?"

IMPORTANT: You have the full diff in the response — READ IT to understand the actual code in any programming language. The context_clues are supplementary hints (comments/docstrings) to help you classify changes from other sessions that you didn't make yourself.

Args: goal: What the user asked the AI to do. Summarize from your conversation. Be specific — this is used to classify changes into goal groups. scope: What to analyze: - "working" (default): All unstaged working tree changes (git diff) plus untracked files. Use this before staging. - "staged": Only staged changes (git diff --staged). Use this if the user has already staged specific files. repo_path: Path to git repository (optional, defaults to MCP roots).

Returns: JSON string with: - goal: The stated goal (pass-through for your reference) - summary: File and line count statistics - changes: Per-file stats (path, status, lines_added, lines_removed) - context_clues: Comments and docstrings from added lines (per file) - diff: Raw diff text for you to read and understand the code - untracked_files: List of new files not yet tracked by git (working scope only) - pagination_info: Token counts and chunk info for the diff