Agent Skill: Prepare PR Review

SKILL.md

name	description	argument-hint	user-invocable
prepare-review	Break up branch changes into smaller, logically-grouped commits for easier code review	base-branch	true

Prepare Review

Break up the changes on the current branch into smaller, logically-grouped commits for easier code review.

Arguments

• $ARGUMENTS - The base branch/commit to compare against (defaults to main)

Workflow

Phase 1: Analysis (Plan Mode)

Enter plan mode and analyze the changes:

1. Determine base reference:

   • If $ARGUMENTS provided, use it as base
   • Otherwise default to main (or master if main doesn't exist)
   • Store the current HEAD SHA for later verification

2. Get diff info:

   • git diff <base>...HEAD --stat - files changed
   • git log <base>..HEAD --oneline - existing commits (if any)
   • git diff <base>...HEAD - full diff

3. Analyze the changes to identify logical groupings based on:

   • Functional cohesion: Related functionality together
   • Refactoring vs features: Separate refactoring from new features
   • Tests: Keep with code they test, or separate if the test changes are large
   • Infrastructure: Config, dependencies, build changes in own commits
   • Error handling: Often can be its own commit

4. Write a plan proposing N commits (where N is appropriate - could be 2-10+):

   • Each commit needs: title, files/hunks, bullet points of changes
   • Order commits so each one compiles/works independently if possible

5. Exit plan mode and wait for user approval

Phase 2: Execution (After Approval)

Once approved, execute the restructuring:

1. Setup:

   # Save current state
   ORIGINAL_HEAD=$(git rev-parse HEAD)
   CURRENT_BRANCH=$(git branch --show-current)
   
   # Create new branch and reset to base
   git checkout -b ${CURRENT_BRANCH}-review
   git reset --soft <base>
   git restore --staged .

2. For each commit in the plan:

   • Stage files with git add <file> for whole files
   • Use git add -p <file> with stdin for partial staging (hunks)
   • Run project formatter if detected (cargo fmt, prettier, black, etc.)
   • Create commit with descriptive message and Co-Authored-By trailer

3. Verification:

   • git diff $ORIGINAL_HEAD should show no differences (trees match)
   • Run <formatter> --check if applicable
   • Show git log --oneline <base>..HEAD of new commits

Grouping Heuristics

Good commit boundaries:

• Import/dependency changes
• Type/interface definitions
• Implementation of a single function/method
• Test additions for specific functionality
• Documentation updates
• Renaming/refactoring (no behavior change)
• Bug fixes (separate from features)

Avoid:

• Mixing unrelated changes
• Splitting a single logical change across commits
• Commits that don't compile/pass tests independently

Example Usage

# Compare against main (default)
/prepare-review

# Compare against specific branch
/prepare-review origin/develop

# Compare against specific commit
/prepare-review abc123

Example Output

For a branch with 15 changed files (auth + logging changes) vs main:

Proposed Commits:

1. Add logging infrastructure (3 files)
2. Refactor auth types (2 files)
3. Implement OAuth flow (5 files)
4. Add auth middleware (3 files)
5. Add auth tests (2 files)