zhongwei/gh-martingonzalez-claude-plugins-plugins-pr-review
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1977fd02cfe13d45725faa11b9b2314a10a923fd
gh-martingonzalez-claude-pl…/commands/pr-review.md
Zhongwei Li 1977fd02cf Initial commit
2025-11-30 08:39:22 +08:00

347 lines
12 KiB
Markdown
Raw Blame History

---
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
Reference in New Issue View Git Blame Copy Permalink