# Pr Review

> Review GitHub pull requests

- Skill: `benthomasson/pr-review` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add benthomasson/pr-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/benthomasson/pr-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: benthomasson (https://skillmd.com/u/benthomasson)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/benthomasson/pr-review

---


# 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:

```bash
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:

```bash
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:**
```bash
# 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

```bash
# 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
```