PR Reviewer Skill

Conduct comprehensive, professional code reviews for GitHub Pull Requests using industry-standard criteria and automated tooling.

Table of Contents

• •Purpose
• •When to Use
• •Review Process Workflow
• •Reference Documentation
• •Scripts Reference
• •Best Practices
• •Quick Reference Commands
• •Tips for Effective Reviews
• •Resources

Purpose

This skill performs code reviews by:

1. •Automating data collection - Fetching all PR-related information (metadata, diff, comments, commits, issues)
2. •Organizing review workspace - Creating structured directory with all artifacts
3. •Applying systematic criteria - Reviewing against comprehensive quality checklist
4. •Facilitating inline feedback - Optionally adding comments directly to PR code
5. •Ensuring completeness - Checking functionality, security, testing, maintainability

When to Use

Activate this skill when:

• •A GitHub PR URL is provided with a review request
• •Receiving "review this PR" or "code review" requests
• •Checking PR quality before merging
• •Providing systematic feedback on proposed changes
• •GitHub PR review is mentioned in any context

Review Process Workflow

IMPORTANT: This skill uses a two-stage approval process. Nothing is posted to GitHub until explicit approval with /send or /send-decline.

Overview

1. •Fetch PR data - Collect all information
2. •Generate review files - Create detailed, human, and inline comment files
3. •Review and edit - Examine files, make changes as needed (use /show)
4. •Approve and post - Use /send (approve) or /send-decline (request changes)

Step 1: Fetch PR Data

Use fetch_pr_data.py to automatically collect all PR information:

python scripts/fetch_pr_data.py <pr_url> [--output-dir <dir>] [--no-clone]

Actions performed:

• •Parse PR URL to extract owner, repo, and PR number
• •Create directory structure: <output-dir>/PRs/<repo-name>/<PR-NUMBER>/
• •Fetch PR metadata (title, author, state, branches, labels)
• •Download PR diff and commit history
• •Retrieve all PR comments and reviews
• •Extract ticket references (JIRA, GitHub issues)
• •Optionally clone source branch and generate git diff

Example:

python scripts/fetch_pr_data.py https://github.com/facebook/react/pull/28476

# Custom output directory
python scripts/fetch_pr_data.py https://github.com/owner/repo/pull/123 --output-dir /tmp/reviews

# Skip cloning (faster, no git diff)
python scripts/fetch_pr_data.py https://github.com/owner/repo/pull/123 --no-clone

Output structure:

/tmp/PRs/<repo-name>/<PR-NUMBER>/
├── metadata.json           # PR metadata (title, author, branches)
├── diff.patch             # PR diff from gh CLI
├── git_diff.patch         # Git diff (if cloned)
├── comments.json          # Review comments on code
├── commits.json           # Commit history
├── related_issues.json    # Linked GitHub issues
├── ticket_numbers.json    # Extracted ticket references
├── SUMMARY.txt            # Human-readable summary
└── source/                # Cloned repository (if not --no-clone)

Step 2: Analyze PR Data

After fetching, analyze collected data against review criteria:

1. •Read SUMMARY.txt - High-level overview
2. •Review metadata.json - PR context, labels, assignees
3. •Examine diff.patch - Code changes
4. •Check comments.json - Existing feedback
5. •Review commits.json - Commit quality and messages
6. •Check related_issues.json - Linked tickets/issues
7. •Apply review criteria - Evaluate against comprehensive checklist

Use the Read tool to examine files:

Read /tmp/PRs/<repo-name>/<PR-NUMBER>/SUMMARY.txt
Read /tmp/PRs/<repo-name>/<PR-NUMBER>/metadata.json
Read /tmp/PRs/<repo-name>/<PR-NUMBER>/diff.patch

Step 3: Generate Review Files

CRITICAL: After analysis, use generate_review_files.py to create structured review documents:

python scripts/generate_review_files.py <pr_review_dir> --findings <findings_json> [--metadata <metadata_json>]

Creates three files in pr_review_dir/pr/:

1. •pr/review.md - Detailed internal review with emojis and line numbers
2. •pr/human.md - Clean review for posting (no emojis, em-dashes, line numbers)
3. •pr/inline.md - Proposed inline comments with code snippets

Also creates slash commands in .claude/commands/:

• •/send - Post human.md and approve PR
• •/send-decline - Post human.md and request changes
• •/show - Open review directory in VS Code

Findings JSON structure:

{
  "summary": "Overall assessment of the PR...",
  "metadata": {
    "repository": "owner/repo",
    "number": 123,
    "title": "PR title",
    "author": "username",
    "head_branch": "feature",
    "base_branch": "main"
  },
  "blockers": [
    {
      "category": "Security",
      "issue": "SQL injection vulnerability",
      "file": "src/db/queries.py",
      "line": 45,
      "details": "Using string concatenation for SQL query",
      "fix": "Use parameterized queries",
      "code_snippet": "result = db.execute('SELECT * FROM users WHERE id = ' + user_id)"
    }
  ],
  "important": [...],
  "nits": [...],
  "suggestions": ["Consider adding...", "Future enhancement..."],
  "questions": ["Is this intended to...", "Should we..."],
  "praise": ["Excellent test coverage", "Clear documentation"],
  "inline_comments": [
    {
      "file": "src/app.py",
      "line": 42,
      "comment": "Consider edge case handling for empty input",
      "code_snippet": "def process(data):\n    return data.strip()",
      "start_line": 41,
      "end_line": 43,
      "owner": "owner",
      "repo": "repo",
      "pr_number": 123
    }
  ]
}

Step 4: Review and Edit Files

Use /show to open the review directory in VS Code.

Actions available:

• •Read pr/review.md - Detailed analysis
• •Edit pr/human.md - Modify before posting
• •Review pr/inline.md - Check proposed comments
• •Adjust any content as needed

NOTHING is posted until explicit approval in Step 5.

Step 5: Approve and Post

Post the review when ready:

Option A: Approve the PR

/send

• •Posts pr/human.md as comment
• •Approves the PR
• •Confirms action

Option B: Request Changes

/send-decline

• •Posts pr/human.md as comment
• •Requests changes on the PR
• •Confirms action

Posting inline comments (optional, after /send or /send-decline): Review pr/inline.md and run the provided commands for specific code comments.

Step 6: Apply Review Criteria

Reference references/review_criteria.md for comprehensive checklist. Review against these categories:

Priority markers for findings:

• •Blocker: Must be fixed before merge
• •Important: Should be addressed
• •Nit: Nice to have, optional
• •Suggestion: Consider for future
• •Question: Clarification needed
• •Praise: Good work

For detailed criteria: Read references/review_criteria.md

Reference Documentation

This skill includes comprehensive reference guides:

Scripts Reference

scripts/fetch_pr_data.py

Automated PR data fetching and organization.

python scripts/fetch_pr_data.py <pr_url> [options]

Options:
  --output-dir DIR    Base output directory (default: /tmp)
  --no-clone         Skip cloning repository

scripts/generate_review_files.py

Generate structured review files from analysis findings.

python scripts/generate_review_files.py <pr_review_dir> --findings <findings_json> [--metadata <metadata_json>]

Creates:

• •pr/review.md - Detailed internal review
• •pr/human.md - Clean review for posting
• •pr/inline.md - Proposed inline comments with commands
• •.claude/commands/send.md - Slash command to approve and post
• •.claude/commands/send-decline.md - Slash command to request changes
• •.claude/commands/show.md - Slash command to open in VS Code
• •REVIEW_READY.txt - Summary of next steps

scripts/add_inline_comment.py

Add inline code review comments to specific lines in PR.

python scripts/add_inline_comment.py <owner> <repo> <pr_number> <commit_id> <file_path> <line> "<comment>" [options]

Options:
  --side RIGHT|LEFT       Side of diff (default: RIGHT)
  --start-line N         Starting line for multi-line comment
  --start-side RIGHT|LEFT Starting side for multi-line comment

Best Practices

Communication

• •Frame feedback as suggestions, not criticism
• •Explain why an issue matters, not just what is wrong
• •Acknowledge excellent practices
• •Prioritize blockers first, style issues last

Review Efficiency

• •Use scripts to automate data fetching and comment posting
• •Reference review_criteria.md as checklist
• •Focus: Critical issues > Important > Nice-to-have
• •Review promptly (within 24 hours if possible)

Inline Comments

• •Reference exact lines and files
• •Provide better alternatives
• •Test inline comments on test PRs first
• •Use sparingly to avoid overwhelming

PR Size Handling

• •Large PRs (>400 lines): Suggest splitting
• •Review in logical chunks
• •Focus on architecture for large changes

For detailed scenarios: Read references/scenarios.md

Quick Reference Commands

# Fetch PR data
python scripts/fetch_pr_data.py https://github.com/owner/repo/pull/123

# Add inline comment
python scripts/add_inline_comment.py owner repo 123 latest "src/app.py" 42 "Comment"

# View PR in browser
gh pr view 123 --repo owner/repo --web

# Check PR status
gh pr checks 123 --repo owner/repo

# View existing comments
gh api /repos/owner/repo/pulls/123/comments --jq '.[] | {path, line, body}'

Tips for Effective Reviews

1. •Start with context: Read PR description, linked issues, commit messages
2. •Understand intent: Identify the problem being solved
3. •Check tests first: Verify tests demonstrate the fix/feature
4. •Look for patterns: Repeated issues suggest architecture problems
5. •Consider alternatives: Evaluate simpler approaches
6. •Think about maintenance: Assess future modification ease
7. •Remember humans: Maintain kindness, respect, and constructive tone

For troubleshooting: Read references/troubleshooting.md

Resources

• •Review Criteria: references/review_criteria.md
• •gh CLI Guide: references/gh_cli_guide.md
• •Scenarios: references/scenarios.md
• •Troubleshooting: references/troubleshooting.md
• •GitHub PR Review Docs: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests
• •Google Engineering Practices: https://google.github.io/eng-practices/review/
• •OWASP Top 10: https://owasp.org/www-project-top-ten/