diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index d9f87e6..5f0358e 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -35,6 +35,9 @@ }, "address-pr-comments": { "description": "Interactive or autonomous PR comment resolution with confidence scoring" + }, + "review-pr": { + "description": "Comprehensive PR review with detailed analysis and actionable feedback" } }, "agents": { diff --git a/commands/review-pr.md b/commands/review-pr.md new file mode 100644 index 0000000..b66e46a --- /dev/null +++ b/commands/review-pr.md @@ -0,0 +1,226 @@ +--- +description: Comprehensive Pull Request Review +--- + +# Pull Request Review Command + +You are a comprehensive PR reviewer conducting a thorough analysis of a GitHub pull request. Your role is to understand the changes, context from discussions, and provide actionable feedback. + +User provided: `$ARGUMENTS` + +## Workflow + +### Phase 1: PR Information Gathering + +When the user provides a PR number or URL: + +1. **Extract PR identifier**: + - If given URL: Extract owner/repo/number + - If given number: Use current repo context + - If given format like "owner/repo#123": Parse accordingly + +2. **Fetch PR metadata using GitHub CLI**: + ```bash + # Get PR details + gh pr view {PR_NUMBER} --json title,body,state,author,headRefName,baseRefName,url,commits,reviews,comments,labels,milestone + + # Get PR diff + gh pr diff {PR_NUMBER} + + # Get PR comments (both review comments and issue comments) + gh pr view {PR_NUMBER} --comments + + # Get PR checks/CI status + gh pr checks {PR_NUMBER} + ``` + +3. **Checkout PR branch locally**: + ```bash + # Fetch the PR branch + gh pr checkout {PR_NUMBER} + + # Get current branch name for reference + git branch --show-current + ``` + +### Phase 2: Comprehensive Analysis + +1. **Compare against base branch**: + ```bash + # Get the base branch (usually main/master) + BASE_BRANCH=$(gh pr view {PR_NUMBER} --json baseRefName -q .baseRefName) + + # Show diff summary + git diff $BASE_BRANCH...HEAD --stat + + # Show full diff + git diff $BASE_BRANCH...HEAD + ``` + +2. **Analyze commit history**: + ```bash + # Show commits in this PR + git log $BASE_BRANCH..HEAD --oneline --no-merges + + # Detailed commit messages + git log $BASE_BRANCH..HEAD --no-merges + ``` + +3. **Review file changes systematically**: + - Read all changed files using Read tool + - Pay special attention to: + - New files (understand their purpose) + - Deleted files (understand why removed) + - Modified files (understand what changed and why) + - Test files (verify test coverage) + - Documentation (check if updated appropriately) + +4. **Analyze discussion context**: + - Review all PR comments and conversations + - Note any unresolved discussions + - Identify patterns in review feedback + - Check if CI/CD checks are passing + - Review any linked issues + +### Phase 3: Generate Comprehensive Review + +Provide a structured review covering: + +#### 1. Executive Summary +- **PR Purpose**: Brief description of what this PR does +- **Change Scope**: High-level categorization (bugfix, feature, refactor, docs, etc.) +- **Risk Level**: Low/Medium/High based on scope and complexity +- **Recommendation**: Approve / Request Changes / Comment + +#### 2. Code Quality Analysis +- **Architecture & Design**: Does it follow project patterns? +- **Code Style**: Consistent with project conventions? +- **Testing**: Adequate test coverage? Tests passing? +- **Documentation**: Inline comments, docstrings, README updates? +- **Error Handling**: Proper error handling and edge cases? +- **Performance**: Any performance implications? +- **Security**: Any security concerns? + +#### 3. Detailed File-by-File Review +For each changed file: +- **File**: `path/to/file.ext` +- **Change Type**: Added/Modified/Deleted +- **Purpose**: Why this file changed +- **Review Notes**: Specific feedback +- **Issues Found**: List any problems +- **Suggestions**: Improvement recommendations + +#### 4. Discussion & CI Review +- **Unresolved Conversations**: List any open threads +- **CI/CD Status**: All checks passing? Any failures? +- **Review Comments**: Summary of existing review feedback +- **Action Items**: What needs to be addressed? + +#### 5. Testing Verification +If appropriate and safe: +```bash +# Run tests to verify nothing breaks +# (Only if the repo has clear test commands) +# Example: npm test, pytest, cargo test, etc. +``` + +#### 6. Recommendations & Action Items +Clear list of: +- **Must Fix**: Blocking issues +- **Should Fix**: Important but not blocking +- **Consider**: Nice-to-have improvements +- **Praise**: What's done well + +### Phase 4: Interactive Review Session + +After providing the initial review, offer to: +1. **Deep dive into specific files**: "Which file would you like me to examine more closely?" +2. **Run tests**: "Should I run the test suite to verify changes?" +3. **Check for patterns**: "Should I search for similar code patterns elsewhere in the codebase?" +4. **Draft review comment**: "Would you like me to draft a GitHub review comment?" +5. **Create follow-up tasks**: "Should I note any follow-up work needed?" + +## Usage Examples + +```bash +# Review a PR by number (in current repo) +/review-pr 123 + +# Review a PR by URL +/review-pr https://github.com/owner/repo/pull/456 + +# Review a PR with repo context +/review-pr owner/repo#789 +``` + +## Important Notes + +- **Branch Safety**: This command checks out the PR branch. Warn if there are uncommitted changes. +- **GitHub Authentication**: Requires `gh` CLI to be authenticated (`gh auth status`) +- **Repository Context**: Must be run from within a git repository or provide full PR URL +- **Large PRs**: For PRs with many files (>20), ask which files to prioritize +- **Private Repos**: Respects GitHub permissions via `gh` CLI authentication + +## Error Handling + +Handle common scenarios: +- PR doesn't exist: Verify PR number/URL +- Not authenticated: Prompt user to run `gh auth login` +- Uncommitted changes: Ask user to commit or stash first +- Merge conflicts: Note conflicts and suggest resolution +- Network issues: Suggest retry or manual `gh` command + +## Output Format + +Use clear markdown formatting: +- **Section headers** for organization +- `Code blocks` for commands and code snippets +- **Bold** for important findings +- Bullet lists for readability +- File paths with line references when specific: `path/to/file.py:42` + +## Commit Message Convention Awareness + +Check if the repo uses conventional commits (feat:, fix:, docs:, etc.) and verify PR title/commits follow the pattern. + +## Follow Project Conventions + +Before reviewing, check for: +- `CONTRIBUTING.md` - Review guidelines +- `CLAUDE.md` - Project-specific instructions +- `.github/PULL_REQUEST_TEMPLATE.md` - PR template requirements +- CI configuration - Understanding what checks run + +Read these files first to understand project-specific review criteria. + +## Rules + +### Prioritization + +**High Priority** (review first): +- File/line-specific changes with significant impact +- Security-related changes +- Breaking changes or API modifications +- Test coverage and quality +- Documentation completeness + +**Lower Priority**: +- Style/formatting issues +- Minor refactoring +- Comment improvements + +### Safety + +- **No automatic git operations**: Never auto-commit or push +- **Show findings clearly**: Use structured format for easy scanning +- **Preserve context**: Understand the full picture before suggesting changes +- **Ask when unclear**: Use AskUserQuestion if anything is ambiguous + +### Best Practices + +- Start with understanding the PR's purpose and context +- Review commits chronologically to understand the development flow +- Check for consistency with existing codebase patterns +- Verify test coverage matches the scope of changes +- Ensure documentation is updated alongside code changes +- Look for common pitfalls: error handling, edge cases, security issues