analyze-changes

Analyze Changes

Perform an interactive, chunk-by-chunk review of changes in a PR or branch. Explain what each logical change does, then critique for potential issues.

When to Use

• Reviewing a PR before merge
• Understanding what changed on a feature branch
• Self-review before pushing
• Onboarding to someone else's changes

Process

1. Detect Context

Determine the diff source:

If on a PR branch or user mentions PR:

gh pr view --json number,title,body,baseRefName 2>/dev/null
gh pr diff

If on a feature branch (no PR):

# Detect main branch
git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
# Or default to main/master

git diff main...HEAD
# or
git diff master...HEAD

If user specifies:

• Follow their instruction (specific commits, files, etc.)

2. Identify Logical Chunks

Analyze the diff and group changes into logical chunks. A chunk is:

• A coherent unit of change (single purpose)
• May span multiple files
• Should be reviewable independently

Good chunking:

• "Add user validation middleware"
• "Refactor database connection pooling"
• "Update API response format"
• "Add tests for auth flow"

Bad chunking:

• By file (misses logical grouping)
• Too granular (every function)
• Too broad ("all the changes")

3. Present Overview

## Change Overview

**Context**: {PR #N: title | Branch: name vs main}

**Overall Goal**: {1-2 sentences: what does this PR/branch aim to achieve}

## Logical Chunks

1. **{Chunk 1 theme}**: {one-line description}
2. **{Chunk 2 theme}**: {one-line description}
3. **{Chunk 3 theme}**: {one-line description}

---

Ready to review Chunk 1: "{theme}"? (y/skip/all)

4. Review Each Chunk

Wait for user confirmation before each chunk.

User responses:

• y / yes / continue / proceed → Review this chunk
• skip → Skip to next chunk
• all → Review all remaining chunks without pausing

For each chunk, follow CHUNK-REVIEW-GUIDE.md:

### Chunk {N}: {Theme}

**Files touched**:
- `{path/to/file1}` — {brief: added/modified/deleted, what}
- `{path/to/file2}` — {brief}

**What this changes**:
{Explanation of what the code does now, how it differs from before}

**Why** (if discernible):
{Rationale for the change — from PR description, commit messages, or code context}

**Concerns**:
{Any issues, risks, or suggestions — or "None identified" if solid}

---

Ready for Chunk {N+1}: "{theme}"? (y/skip/all)

5. Final Summary

After all chunks reviewed:

## Review Summary

**Chunks reviewed**: {N} of {total}

**Cross-cutting concerns**:
{Issues that span multiple chunks or affect the PR as a whole}

**Overall assessment**:
{Brief: is this PR ready? What needs attention?}

Guidelines

• Explain before critiquing: User should understand the change before hearing concerns
• Be specific in concerns: "This might break X because Y" not "This seems risky"
• Acknowledge good work: If a chunk is well-done, say so briefly
• Don't invent issues: If code is solid, "None identified" is fine
• Respect user's time: Keep explanations concise, expand if asked