pr-reviewer-3a

PR Reviewer (Unified)

Review pull requests using multiple review methodologies. Includes automatic focus analysis to reduce cognitive load and four review modes to match different PR characteristics.

When to Use

• Before submitting PRs for team review (self-review)
• Reviewing teammates' PRs
• Validating implementation completeness
• Large or complex PRs requiring structured review

Input Types

• PR number (e.g., #234)
• Branch name
• Git diff
• Optional: --mode [standard|mob|deep|multi] (default: standard)

---

Step 0a: Load Review Profile (optional)

Run before Focus Analysis if .claude/review-profile.yaml exists.

Check for a project-specific review profile:

ls .claude/review-profile.yaml 2>/dev/null

If found, load and apply it:

• Override default high_risk_paths / medium_risk_paths / skip_paths with profile values
• Prepend patterns (naming / architecture / testing rules) to the review checklist
• Add watch_for items as explicit check points during review
• Append extra_checklist items to the final checklist output

If not found, skip silently and proceed with defaults.

---

Step 0b: Focus Analysis

Always run this before any review mode.

Reduce cognitive load by identifying WHERE to focus attention before diving into details.

Risk Classification

Risk	Path Pattern	Examples
High	domain/, usecase/, *security*, *auth*	Business logic, security
Medium	infrastructure/, *router*, *handler*	API, navigation
Low	test/, *.md, UI-only components	Tests, docs

Analysis Process

git diff main --stat
git diff main --name-status

Mode Auto-Selection Hint

After focus analysis, suggest a mode based on PR characteristics:

• Small PR, single feature -> standard
• Large PR, many files across layers -> mob
• Complex logic changes, few files -> deep
• Cross-cutting concerns, multiple domains -> multi

---

Review Mode Selection

Mode	Best For	Approach
standard	Typical PRs, single-feature changes	Three Amigos (Business + Dev + Testing)
mob	Large PRs, many files	Broad parallel scan, then deep-dive on hotspots
deep	Complex logic, subtle bugs	3-round progressive review with increasing depth
multi	Cross-cutting PRs, architectural changes	Parallel review from multiple specialist personas

---

Mode: standard (Three Amigos)

The default review mode. Examines the PR from three perspectives: Business, Development, and Testing.

1. Gather PR Context

gh pr view [number]
gh pr diff [number]

# Or for branch
git diff main...[branch]
git log main...[branch] --oneline

2. Business Review

• Does it fulfill requirements?
• Is user value delivered?
• Are acceptance criteria met?
• Any scope creep?

3. Development Review

• Clean Architecture compliance
• Code quality and maintainability
• Error handling
• Security considerations
• Conventional Commits format

4. Testing Review

• Test coverage adequate?
• Detroit School approach (Fakes over Mocks)?
• Edge cases covered?

---

Mode: mob (Broad Scan + Deep-Dive)

Best for large PRs with many files. Scans broadly first, then deep-dives into hotspots.

Phase 1: Broad Parallel Scan

Review ALL changed files quickly in parallel. For each file, produce a one-line assessment:

| File | Risk | Signal | Note |
|------|------|--------|------|
| `domain/foo` | H | logic-change | New validation rule |
| `presentation/bar` | L | ui-only | Padding tweak |

Signals: logic-change, new-dep, error-handling, security, state-mgmt, ui-only, config, test-gap

Phase 2: Hotspot Identification

Identify the top 3-5 hotspots (files/areas with highest risk or most signals).

Phase 3: Deep-Dive Review

For each hotspot, perform a full Three Amigos review. Non-hotspot files get "scan-passed" status.

---

Mode: deep (3-Round Progressive Review)

Best for complex logic changes where subtle bugs may hide.

Round 1: Surface Review (Correctness)

• Syntax errors, obvious logic bugs, missing null checks, broken control flow

Round 2: Structural Review (Design)

• Architecture layer violations, dependency direction, Single Responsibility violations, code duplication

Round 3: Semantic Review (Intent)

• Does implementation match PR description?
• Subtle race conditions or edge cases?
• Implicit assumptions that may break?
• Orphaned code paths?

---

Mode: multi (Multi-Persona Parallel Review)

Best for cross-cutting PRs or architectural changes.

Personas

Persona	Focus	Looks For
Architect	System design, layer boundaries	Layer violations, coupling, scalability
Security Engineer	Auth, input validation, data exposure	Injection, auth bypass, data leaks
Performance Engineer	Efficiency, resource usage	N+1 queries, memory leaks
UX Advocate	User impact, error messages	Bad error UX, missing loading states
Test Strategist	Test quality, coverage gaps	Missing edge cases, mock overuse

Process

1. Select Personas: Based on focus analysis, pick 3-4 relevant personas (always include Architect).
2. Parallel Review: Each persona reviews the diff independently.
3. Validation Pass: For each finding, verify it was introduced by this PR's diff. Discard pre-existing issues.
4. Synthesis: Merge validated findings, de-duplicate, prioritize.

Confidence Scoring

Score	Meaning	Action
≥ 80	Real issue, significant	Include in output
50–79	Possible issue, minor	Include as "Note" only
< 50	Likely false positive	Discard silently

Auto-discard: Issues pre-existing before this PR, violations suppressed in CLAUDE.md, items a senior engineer would not raise.

---

Review Checklist (All Modes)

Business

• Requirements fulfilled
• Acceptance criteria met
• No unintended scope creep

Development

• Architecture layer compliance
• Error handling complete
• No security issues
• No dead code

Testing

• Adequate test coverage
• Fakes preferred over mocks
• Edge cases covered

Guidelines

• Be constructive in feedback
• Provide specific file:line references
• Suggest concrete fixes
• Prioritize issues by severity
• Acknowledge good practices
• Always run Step 0a then Step 0b first

Related Skills

• implementation-sequencer — sequencing before building
• detroit-school-lint — test quality issues
• pr-comment-handler — addressing review comments received
• quality-gate — pre-PR self-check

Gotchas

See gotchas.md in this directory for known pitfalls and recurring mistakes when using this skill.