jawhnycooke Comprehensive PR Review Workflow
Run multi-agent pull request reviews where each specialized agent focuses on a different aspect of code quality, then aggregate results into an actionable summary.
Review Aspects
Six specialized review agents are available:
| Agent | Focus | When Applicable |
|---|---|---|
| code-reviewer | CLAUDE.md compliance, bugs, general quality | Always |
| pr-test-analyzer | Test coverage quality, critical gaps | Test files changed |
| silent-failure-hunter | Silent failures, catch blocks, error logging | Error handling changed |
| type-design-analyzer | Type encapsulation, invariant expression | New types added/modified |
| comment-analyzer | Comment accuracy, documentation completeness | Comments/docs added |
| code-simplifier | Code clarity, readability, project standards | After passing review |
Review Workflow
Step 1: Determine Review Scope
- Check git status to identify changed files:
git diff --name-only - Check if a PR already exists:
gh pr view - Parse any user-specified review aspects
- Default: run all applicable reviews
Step 2: Identify Applicable Reviews
Based on the 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)
Step 3: Launch Review Agents
Sequential approach (default):
- One agent at a time for easier understanding and action
- Each report is complete before the next
- Good for interactive review
Parallel approach (on user request):
- Launch all agents simultaneously
- Faster for comprehensive review
- Results come back together
Step 4: Aggregate Results
After agents complete, organize findings:
# 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
Agent Details
code-reviewer
Reviews code against project guidelines in CLAUDE.md with confidence-based filtering (only reports issues with confidence >= 80). Checks for CLAUDE.md compliance, bug detection, and code quality. Groups issues by severity (Critical: 90-100, Important: 80-89).
pr-test-analyzer
Focuses on behavioral coverage rather than line coverage. Identifies critical code paths, edge cases, and error conditions that must be tested. Rates criticality from 1-10 and maps to severity (9-10: CRITICAL, 7-8: HIGH, 5-6: MEDIUM, 1-4: LOW).
silent-failure-hunter
Analyzes for silent failures, empty catch blocks, broad exception catching, inadequate error messages, and unjustified fallback behavior. Checks logging quality, user feedback, catch block specificity, and error propagation.
type-design-analyzer
Evaluates new types on four dimensions (each rated 1-10): encapsulation, invariant expression, invariant usefulness, and invariant enforcement. Flags anti-patterns like anemic domain models, exposed mutable internals, and missing construction validation.
comment-analyzer
Verifies comment factual accuracy against code, assesses completeness, evaluates long-term value, and identifies misleading elements. Categorizes findings as critical issues, improvement opportunities, and recommended removals.
code-simplifier
Simplifies code for clarity and maintainability while preserving all functionality. Applies project standards, reduces unnecessary complexity, eliminates redundant code, and improves naming. Avoids nested ternaries and over-compact solutions.
Usage Patterns
Full review (default): Run all applicable review agents based on changed files.
Targeted review:
Specify aspects to focus on: tests, errors, comments, types, code, simplify.
Parallel review: Request all agents run simultaneously for faster results.
Workflow Integration
Before committing:
- Write code
- Run code and error reviews
- Fix critical issues
- Commit
Before creating PR:
- Stage all changes
- Run all reviews
- Address critical and important issues
- Re-run specific reviews to verify
- Create PR
After PR feedback:
- Make requested changes
- Run targeted reviews based on feedback
- Verify issues are resolved
- Push updates
Tips
- Run reviews early, before creating the PR
- Agents analyze git diff by default
- Address critical issues before lower priority ones
- Re-run reviews after fixes to verify resolution
- Use targeted reviews when the concern area is known
- All agents return actionable results with specific file:line references