--- 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 ...HEAD` * If no changes found: Exit with message "No changes detected between current branch and " * 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/` 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 ` - **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 ` - **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_.md` - Fetch PR details: `gh pr view --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__.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/.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_link: author: branch: <- ticket: (if there is any, otherwise "N/A") files_changed: (+ -) ## PR Description ## Summary [Rest of the review content: Critical Issues, Important Issues, Suggestions, etc.] ``` **Document structure for local reviews:** ```markdown review_type: Local Pre-Review branch: <- author: date: files_changed: (+ -) ticket: (if detectable, otherwise "N/A") ## Changes Summary ## 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_.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