spillwavesolutions/agent_rulez/pr-reviewer

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/