PR Review

Reference Files

references/code-review.md

references/test-analysis.md

references/error-handling.md

references/type-design.md

references/comment-quality.md

Workflow

Phase 1: Scope

1. Determine the review target:
   • Default:

     git diff

     (unstaged changes)
   • If user specifies a PR:

     git diff main...HEAD

     or

     gh pr diff <number>

   • If user specifies files: review those files directly
2. List all changed files with

   git diff --name-only

3. Read the project's CLAUDE.md (if present) for project-specific rules

Phase 2: Route

references/code-review.md

*test*

*spec*

*_test.*

test_*

references/test-analysis.md

references/error-handling.md

references/type-design.md

references/comment-quality.md

Phase 3: Review

1. Code review — scan every changed file for guideline violations and bugs. Apply confidence scoring (0-100). Only report issues >= 80.
2. Test analysis — map test coverage to changed code paths. Rate gaps 1-10. Only report gaps >= 5.
3. Error handling — examine every error handler in the diff for silent failures. Classify CRITICAL/HIGH/MEDIUM.
4. Type design — evaluate new or modified types on 4 dimensions (encapsulation, invariant expression, usefulness, enforcement). Rate each 1-10.
5. Comment quality — verify accuracy, assess long-term value, flag comment rot.

Phase 4: Aggregate

• If two dimensions flag the same file:line, keep the higher-severity finding
• If code-review and error-handling both flag an empty catch block, merge into one finding with the error-handling severity (it's the specialist)

Output Format

# PR Review Summary

**Scope:** [X files changed, Y dimensions applied]
**Dimensions:** [list of active dimensions]

## Critical Issues (must fix before merge)
- **[dimension]** `file:line` — Description. Fix suggestion.

## Important Issues (should fix)
- **[dimension]** `file:line` — Description. Fix suggestion.

## Suggestions (consider)
- **[dimension]** `file:line` — Description.

## Strengths
- What's well-done in this changeset.

## Recommended Action
1. Fix critical issues
2. Address important issues
3. Consider suggestions
4. Re-run review after fixes

Aspect Selection

Error Handling

Calibration Rules

1. Precision over recall. A false positive erodes trust in the review. Only report issues at >= 80 confidence (code review) or >= 5 criticality (tests). Silence is better than noise.
2. File:line references are mandatory. Every finding must include a specific location. Vague findings ("consider improving error handling") are not actionable.
3. Project rules override general rules. If CLAUDE.md says "use arrow functions", do not flag arrow functions even if conventional style prefers

   function

   declarations.
4. Deduplication is mandatory. If two dimensions flag the same issue, merge them. Never report the same problem twice.
5. Acknowledge strengths. A review that only lists problems is demoralizing. Note what's done well, even briefly.
6. Code-refiner handles simplification. This skill reviews and reports. It does not refactor or simplify — that's the

   code-refiner

   skill's job. Keep the roles separate.