gh-martingonzalez-claude-plugins-plugins-pr-review/commands/pr-review.md

---
description: "Comprehensive PR review using specialized agents"
argument-hint: "[review-aspects]"
allowed-tools: ["Bash", "Glob", "Grep", "Read", "Task"]
---

# Comprehensive PR Review

Run a comprehensive pull request review using multiple specialized agents, each focusing on a different aspect of code quality.

**Review Aspects (optional):** "$ARGUMENTS"

## Review Workflow:

1. **Determine Review Scope**
   - Check if argument contains the keyword `local`
   - If `local` argument detected:
     * **Pre-review mode** - Review local changes before creating/updating PR
     * Verify current directory is a git repository: `git rev-parse --is-inside-work-tree`
     * If not a git repo: Exit with error message
     * Get current branch: `git branch --show-current`
     * Get default branch: `git remote show origin | grep 'HEAD branch'` or assume `main`/`master`
     * Check for uncommitted changes: `git status --porcelain`
     * If uncommitted changes exist: Ask user "You have uncommitted changes. Review staged changes only, or commit all changes first? (staged/commit/cancel)"
     * Generate diff against default branch: `git diff <default-branch>...HEAD`
     * If no changes found: Exit with message "No changes detected between current branch and <default-branch>"
     * Continue with review using the local diff
     * Skip PR metadata extraction (no PR exists yet)
     * Use branch name and local changes for context
   - Check if argument is a PR URL (matches pattern: `https://github.com/*/pull/*`)
   - If PR URL detected:
     * Use `gh pr view $URL --json headRefName,headRepository,headRepositoryOwner` to extract metadata
     * Extract repo name and branch from JSON response
     * **Check for existing repository:**
       - If current directory is NOT a git repo: Check if any child folder matches repo name and contains `.git`
       - If matching child folder found: Use that instead of cloning
       - If no matching folder exists: Clone via `git clone git@github.com:owner/repo.git`
     * **Navigate to repository directory**
     * **Branch state management:**
       1. Check current branch: `git branch --show-current`
       2. Check if on HEAD of PR branch: `git fetch origin && git rev-parse HEAD` vs `git rev-parse origin/<pr-branch>`
       3. Check for uncommitted changes: `git status --porcelain`
       4. Apply appropriate action:
          - **On PR branch, at HEAD, no changes:** Continue with review
          - **On PR branch, behind HEAD, no changes:** Pull latest: `git pull origin <pr-branch>`
          - **On PR branch, behind HEAD, with changes:** Ask user: "Branch has uncommitted changes. Reset hard and pull HEAD? (y/n)"
          - **On different branch, no changes:** Switch to PR branch: `git checkout <pr-branch>`
          - **On different branch, with changes:** Ask user: "You are on branch X with uncommitted changes. Reset and switch to PR branch? (y/n)"
     * Continue with review in this context
   - If no URL provided:
     * Run `git rev-parse --is-inside-work-tree` to check if current directory is a git project
     * If NOT a git project: **Exit early** with message: "Not in a git repository and no PR URL provided. Please either navigate to a git project or provide a PR URL."
     * If git project exists: proceed with current repository
   - Check git status to identify changed files
   - If no specific review aspects provided in arguments: **Ask user interactively** which aspects to review
   - Present numbered list of available aspects and wait for user selection

2. **Interactive Review Aspect Selection (if not provided in arguments)**

   Present this numbered menu to user:
   ```
   Select review aspects (comma-separated numbers, or 0 for all):

   0. All applicable reviews (comprehensive)
   1. Comments - Analyze code comment accuracy and maintainability
   2. Tests - Review test coverage quality and completeness
   3. Errors - Check error handling for silent failures
   4. Types - Analyze type design and invariants
   5. Code - General code review for project guidelines
   6. Simplify - Simplify code for clarity and maintainability

   Example: "1,2,3" or "0" or "2"
   ```

   - Wait for user input
   - Parse their selection (e.g., "1,3,5" → comments, errors, code)
   - If user enters "0" or "all": run all applicable reviews
   - Proceed to next step with selected aspects

3. **Available Review Aspects Reference:**

   - **comments** - Analyze code comment accuracy and maintainability
   - **tests** - Review test coverage quality and completeness
   - **errors** - Check error handling for silent failures
   - **types** - Analyze type design and invariants (if new types added)
   - **code** - General code review for project guidelines
   - **simplify** - Simplify code for clarity and maintainability
   - **all** - Run all applicable reviews (default)

4. **Identify Changed Files**
   - Run `git diff --name-only` to see modified files
   - Check if PR already exists: `gh pr view`
   - Identify file types and what reviews apply

5. **Determine Applicable Reviews**

   Based on changes:
   - **Always applicable**: code-reviewer (general quality)
   - **If test files changed**: pr-test-analyzer
   - **If comments/docs added**: comment-analyzer
   - **If error handling changed**: silent-failure-hunter
   - **If types added/modified**: type-design-analyzer
   - **After passing review**: code-simplifier (polish and refine)

6. **Launch Review Agents**

   **Sequential approach** (one at a time):
   - Easier to understand and act on
   - Each report is complete before next
   - Good for interactive review

   **Parallel approach** (user can request):
   - Launch all agents simultaneously
   - Faster for comprehensive review
   - Results come back together

7. **Aggregate Results**

   After agents complete, summarize:
   - **Critical Issues** (must fix before merge)
   - **Important Issues** (should fix)
   - **Suggestions** (nice to have)
   - **Positive Observations** (what's good)

8. **Provide Action Plan**

   Organize findings:
   ```markdown
   # PR Review Summary

   ## Critical Issues (X found)
   - [agent-name]: Issue description [file:line]

   ## Important Issues (X found)
   - [agent-name]: Issue description [file:line]

   ## Suggestions (X found)
   - [agent-name]: Suggestion [file:line]

   ## Strengths
   - What's well-done in this PR

   ## Recommended Action
   1. Fix critical issues first
   2. Address important issues
   3. Consider suggestions
   4. Re-run review after fixes
   ```

9. **Generate Review Document**

   After completing the review, write a markdown file with appropriate naming convention.

   **For PR URL reviews:**
   - Filename: `pr_<PR_NUMBER>.md`
   - Fetch PR details: `gh pr view <PR_URL> --json number,title,author,headRefName,baseRefName,body,additions,deletions,changedFiles`
   - Extract ticket URL from PR body (look for patterns like Jira, GitHub issues, etc.)

   **For local reviews:**
   - Filename: `pr_local_<BRANCH_NAME>_<TIMESTAMP>.md` (e.g., `pr_local_feature-auth_20251010-143022.md`)
   - Use timestamp format: `YYYYMMDD-HHMMSS`
   - Generate metadata from git: author (git config user.name), branch names, file statistics

   **File location:**
   - Create `.pr-reviews/` directory in repository root if it doesn't exist
   - Save review file as `.pr-reviews/<FILENAME>.md`
   - Ensure `.pr-reviews/` is added to `.gitignore` so reviews are not committed

   **Gitignore management:**
   - Check if `.gitignore` exists in repository root
   - If exists: Check if `.pr-reviews/` is already ignored
   - If not ignored: Append `.pr-reviews/` to `.gitignore`
   - If `.gitignore` doesn't exist: Create it with `.pr-reviews/` entry

   **Document structure for PR reviews:**
   ```markdown
   pr_title: <PR_TITLE>
   pr_link: <PR_URL>
   author: <PR_AUTHOR_NAME>
   branch: <TARGET_BRANCH> <- <SOURCE_BRANCH_NAME>
   ticket: <TICKET_URL> (if there is any, otherwise "N/A")
   files_changed: <NUMBER_OF_FILES_CHANGED> (+<ADDITIONS> -<DELETIONS>)

   ## PR Description
   <PR_EXACT_DESCRIPTION>

   ## Summary
   <EXECUTIVE_SUMMARY>

   [Rest of the review content: Critical Issues, Important Issues, Suggestions, etc.]
   ```

   **Document structure for local reviews:**
   ```markdown
   review_type: Local Pre-Review
   branch: <DEFAULT_BRANCH> <- <CURRENT_BRANCH_NAME>
   author: <GIT_USER_NAME>
   date: <REVIEW_DATE_TIME>
   files_changed: <NUMBER_OF_FILES_CHANGED> (+<ADDITIONS> -<DELETIONS>)
   ticket: <EXTRACTED_FROM_BRANCH_NAME_OR_COMMITS> (if detectable, otherwise "N/A")

   ## Changes Summary
   <SUMMARY_OF_LOCAL_CHANGES>

   ## Summary
   <EXECUTIVE_SUMMARY>

   [Rest of the review content: Critical Issues, Important Issues, Suggestions, etc.]
   ```

   **Notes:**
   - Use underscores for spaces in filename (e.g., `pr_123.md`)
   - Preserve exact PR description formatting
   - Executive summary should be 2-3 sentences highlighting key findings and risk level
   - Reviews are kept local and not tracked in git

10. **Provide Review File Location**

   After successfully writing the review document:
   - Display the absolute path to the review file
   - Format: "Review saved to: `/absolute/path/to/repo/.pr-reviews/pr_<NUMBER>.md`"
   - This allows users to easily locate and open the review file

## Usage Examples:

**Local pre-review (before creating PR):**
```
/github-toolkit:pr-review local
# Reviews local changes against default branch (comprehensive)

/github-toolkit:pr-review local tests errors
# Reviews only test coverage and error handling of local changes

/github-toolkit:pr-review local code
# Quick code quality check before committing
```

**Review PR from URL:**
```
/github-toolkit:pr-review https://github.com/owner/repo/pull/123
# Clones repo (if needed), checks out PR branch, runs full review

/github-toolkit:pr-review https://github.com/owner/repo/pull/123 tests errors
# Reviews specific aspects of external PR
```

**Full review (current repo with existing PR):**
```
/github-toolkit:pr-review
```

**Specific aspects:**
```
/github-toolkit:pr-review tests errors
# Reviews only test coverage and error handling

/github-toolkit:pr-review comments
# Reviews only code comments

/github-toolkit:pr-review simplify
# Simplifies code after passing review
```

**Parallel review:**
```
/github-toolkit:pr-review all parallel
# Launches all agents in parallel

/github-toolkit:pr-review local all parallel
# Fast pre-review of local changes
```

## Agent Descriptions:

**comment-analyzer**:
- Verifies comment accuracy vs code
- Identifies comment rot
- Checks documentation completeness

**pr-test-analyzer**:
- Reviews behavioral test coverage
- Identifies critical gaps
- Evaluates test quality

**silent-failure-hunter**:
- Finds silent failures
- Reviews catch blocks
- Checks error logging

**type-design-analyzer**:
- Analyzes type encapsulation
- Reviews invariant expression
- Rates type design quality

**code-reviewer**:
- Checks CLAUDE.md compliance
- Detects bugs and issues
- Reviews general code quality

**code-simplifier**:
- Simplifies complex code
- Improves clarity and readability
- Applies project standards
- Preserves functionality

## Tips:

- **Run early**: Before creating PR, not after
- **Focus on changes**: Agents analyze git diff by default
- **Address critical first**: Fix high-priority issues before lower priority
- **Re-run after fixes**: Verify issues are resolved
- **Use specific reviews**: Target specific aspects when you know the concern

## Workflow Integration:

**Before committing:**
```
1. Write code
2. Run: /github-toolkit:pr-review code errors
3. Fix any critical issues
4. Commit
```

**Before creating PR:**
```
1. Stage all changes
2. Run: /github-toolkit:pr-review all
3. Address all critical and important issues
4. Run specific reviews again to verify
5. Create PR
```

**After PR feedback:**
```
1. Make requested changes
2. Run targeted reviews based on feedback
3. Verify issues are resolved
4. Push updates
```

## Notes:

- Agents run autonomously and return detailed reports
- Each agent focuses on its specialty for deep analysis
- Results are actionable with specific file:line references
- Agents use appropriate models for their complexity
- All agents available in `/agents` list