Claude Code Plugins

Community-maintained marketplace

Feedback

pr-review

@shanemcd/pr-review-skill
0
0

Review GitHub pull requests

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name pr-review
description Review GitHub pull requests

PR Review Skill

This skill helps you conduct comprehensive reviews of GitHub pull requests.

Supporting files:

  • scripts/summarize-pr.py - Comprehensive PR summary script (uses GraphQL)
  • scripts/prepare-worktree.py - Create git worktree for PR review

Important: All scripts use uv for automatic dependency management. Run them directly (e.g., scripts/summarize-pr.py). If uv is not available, fall back to python scripts/summarize-pr.py but you'll need to install dependencies manually.

When to Use This Skill

Use this skill when the user asks you to review a GitHub pull request. The user will typically provide a PR URL or PR number.

How to Review a PR

Step 1: Generate PR Summary

Start by generating a comprehensive summary of the PR. This gives you the complete picture before diving deep:

scripts/summarize-pr.py <OWNER> <REPO> <PR_NUMBER>

This script provides:

  • PR metadata (title, author, status, branch, stats)
  • Description
  • Files changed with additions/deletions
  • Discussion & Reviews - Chronological timeline of all comments and reviews
  • Unresolved Review Comments - Code review threads that need addressing (with diff context)

Read and analyze this output carefully:

  • What problem is being solved?
  • What's the current discussion context?
  • What unresolved issues already exist?
  • Who has reviewed and what are their concerns?

IMPORTANT: The unresolved comments are known blockers. Don't duplicate these in your review - focus on finding NEW issues.

Step 2: Prepare Git Worktree and Review Notes

Create a clean worktree for reviewing the PR and initialize review tracking:

WORKTREE_PATH=$(scripts/prepare-worktree.py <repository_directory> <PR_NUMBER>)
cd "$WORKTREE_PATH"

What this does:

  • Creates a new worktree in <repository>/git-worktrees/<branch-name>
  • Creates a review notes directory in <repository>/review-notes/<branch-name>
  • Generates a README.md template in the review notes directory for tracking progress
  • Fetches and checks out the PR branch in the worktree
  • If the worktree already exists, checks for uncommitted changes before recreating
  • Returns the path to the worktree directory

Benefits:

  • Main repository stays on its current branch
  • Can review multiple PRs simultaneously in different worktrees
  • Clean separation between review work and regular development
  • Review notes are organized per-PR with a structured template
  • Progress tracking with checkboxes for each review step

Use the review notes file:

  • Open <repository>/review-notes/<branch-name>/README.md
  • Fill in notes as you progress through each step
  • Check off tasks as you complete them
  • Document unresolved comments and new issues found
  • Write your final recommendation

Step 3: Gather Context

This is the critical step that goes beyond mechanical checking. Based on the PR type and files changed, use the Task tool with subagent_type=Explore to gather additional context:

For code PRs:

  • Related files: Files that import/use the changed code (to understand integration)
  • Test files: Are there tests? Do they cover the changes?
  • Documentation: README, API docs, comments - are they updated?
  • Configuration: Are there deployment/config implications?
  • Recent related PRs: Is this part of a larger effort?

For design/documentation PRs (SDPs, RFCs, etc.):

  • Related design docs: Other SDPs or architectural decisions
  • Architecture principles: Does this align with standards?
  • Existing implementations: What code might be affected?
  • Previous discussions: GitHub issues, meeting notes, etc.

How to gather context:

  • Use gh pr view to see linked issues
  • Use Task tool with subagent_type=Explore to search for:
    • Related files (imports, callers, tests)
    • Architectural standards or guidelines
    • Existing similar implementations
    • Documentation that needs updating
  • Read the files you discover to understand integration points

Example context gathering:

# Use the Task tool with subagent_type=Explore to find:
# - "Find all files that import X module"
# - "Find test files related to Y feature"
# - "Find architecture docs about Z pattern"

Step 4: Analyze the PR

Now review the PR comprehensively:

  1. Does it solve the stated problem?

    • Compare the changes to the PR description
    • Check if the solution is complete

  2. Are unresolved comments blocking?

    • Review the unresolved threads from Step 1's summary
    • Determine severity and impact

  3. What NEW issues exist?

    • Things not already flagged in unresolved threads (from Step 1)
    • Consider: correctness, design, testing, documentation, edge cases

  4. Context and design concerns

    • Does it fit the broader architecture?
    • Are there cross-cutting concerns (security, performance, etc.)?
    • Is the approach consistent with similar code?

Review criteria by PR type:

For code PRs:

  • Correctness and logic
  • Test coverage
  • Error handling
  • Performance implications
  • Security concerns
  • Documentation completeness
  • Code style and conventions

For design/documentation PRs:

  • Completeness of requirements
  • Clarity of problem statement
  • Well-defined use cases
  • Consistency in terminology
  • Alignment with architecture principles
  • Missing sections or incomplete information
  • Feasibility of implementation

Step 5: Complete Review Notes and Provide Recommendation

As you work through the review, systematically fill in the review notes at <repository>/review-notes/<branch-name>/README.md:

  1. Step 1 - PR Summary Analysis

    • Check off each task as you review the summary output
    • Document key observations in the Notes section
    • List unresolved comments under "Unresolved Comments (from PR)"

  2. Step 3 - Context Gathering

    • Note what related files/tests/docs you examined
    • Document architectural concerns or patterns found
    • Check off tasks as you complete them

  3. Step 4 - Code Review

    • Work through the changed files systematically
    • Check off review tasks as you complete them
    • Document new issues found under "New Issues Found" with file:line references

  4. Step 5 - Final Recommendation

    • Select the appropriate status (Approve/Request Changes/Comment)
    • Write a clear summary of your findings
    • List specific, actionable items for the author
    • Focus on NEW issues, not duplicating unresolved comments

Review notes structure:

  • Unresolved Comments: Issues already flagged in the PR discussion
  • New Issues Found: Problems you discovered during review
  • Final Recommendation: Your verdict and next steps
  • Use file:line references for all code-specific feedback

Output Format

Your review output should be written in the review notes file at <repository>/review-notes/<branch-name>/README.md.

The template provides sections for:

  • PR Summary Analysis with checkboxes
  • Context Gathering notes
  • Code Review progress tracking
  • Unresolved Comments (from existing PR discussion)
  • New Issues Found (your discoveries)
  • Final Recommendation with status and action items

Use code references in the format file_path:line_number when pointing to specific locations.

Important Notes

  • Always start with summarize-pr.py - This gives you the complete PR context upfront
  • Always use prepare-worktree.py - Never checkout PRs in the main repository
  • Always use the review notes file - Document your progress systematically in review-notes/<branch-name>/README.md
  • Always use the gh CLI tool via Bash, never try to construct GitHub URLs manually
  • Prefer running scripts with uv - The scripts have uv-style dependency declarations and will auto-install dependencies. Fall back to python only if uv is unavailable.
  • Don't duplicate unresolved threads - They're already documented, focus on NEW issues
  • Use Task tool with subagent_type=Explore for context gathering - this is where you add value
  • Be thorough but constructive - provide specific, actionable feedback
  • Prioritize findings by severity and impact
  • Check off tasks in the review notes as you complete each step

Example Workflow

# Step 1: Generate comprehensive PR summary
scripts/summarize-pr.py <OWNER> <REPO> <PR_NUMBER>

# Read and analyze the output:
# - What's the PR about?
# - What's the discussion history?
# - What unresolved issues exist?

# Step 2: Prepare git worktree
WORKTREE_PATH=$(scripts/prepare-worktree.py /path/to/repo <PR_NUMBER>)
cd "$WORKTREE_PATH"

# Step 3: Gather context using Task tool
# Use Task tool with subagent_type=Explore to find:
# - Related architecture docs
# - Similar implementations
# - Test coverage
# - Integration points

# Step 4: Analyze the PR
# - Read changed files
# - Check for issues not in unresolved threads
# - Verify alignment with context found

# Step 5: Provide structured review
# Follow the 5-section format above