PR Review
Diff-based code review across five dimensions. Reads the changed files, selects
applicable review methodologies, and produces an aggregated report with severity-ranked
findings.
Native alternative: Claude Code's /ultrareview runs a lightweight native bug-focused review (three free per month on Pro/Max plans at Opus 4.7's launch). Use this skill for five-dimension severity-ranked analysis (code quality + tests + error handling + types + comments) with file:line references; use /ultrareview for a quick bug-hunting pass on a diff.
Reference Files
| File |
Contents |
Load When |
references/code-review.md |
Guideline compliance, bug detection, confidence scoring |
Always |
references/test-analysis.md |
Behavioral test coverage, criticality rating |
Test files changed |
references/error-handling.md |
Silent failure patterns, catch block analysis |
Error handling changed |
references/type-design.md |
Invariant analysis, 4-dimension rating rubric |
Type definitions added/modified |
references/comment-quality.md |
Comment accuracy, long-term value, rot detection |
Comments/docstrings added |
Workflow
Phase 1: Scope
- 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
- List all changed files with
git diff --name-only
- Read the project's CLAUDE.md (if present) for project-specific rules
Phase 2: Route
Classify changed files and select applicable dimensions:
| Condition |
Dimension |
Reference to Load |
| Always |
Code review |
references/code-review.md |
Files matching *test*, *spec*, *_test.*, test_* |
Test analysis |
references/test-analysis.md |
| Files containing try/catch, except, .catch, Result, error callbacks |
Error handling |
references/error-handling.md |
| Files containing class, interface, type, struct, enum, dataclass definitions |
Type design |
references/type-design.md |
| Files with new/modified docstrings, JSDoc, or block comments |
Comment quality |
references/comment-quality.md |
Load only the reference files that apply. Skip dimensions with no matching files.
Phase 3: Review
Review the changed behavior and affected contracts using the applicable methodologies:
- Code review — report demonstrated bugs and explicit rule violations at confidence >= 80.
- Test analysis — identify plausible consumer-visible regressions that required behavior does not cover.
- Error handling — trace failures and their caller-visible consequences.
- Type design — assess current invariants and actual consumers; speculative extensibility is not a defect.
- Comment quality — report misleading contracts that affect correct use; ordinary polish is optional.
Read enough surrounding implementation and call sites to prove each scenario. Review changed source rather than generated copies. On fixes, review the changed code and affected interactions; repeat a broader review only when a changed contract or base invalidates the earlier assessment.
Phase 4: Aggregate
Merge all findings into a single report, deduplicated and severity-ranked.
Deduplication rules:
- 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)
Severity is impact, not confidence or a design score.
| Severity |
Evidence and consequence |
| Critical |
Demonstrated severe security, data-loss, availability or equivalent consumer risk; blocks merge. |
| Important |
Concrete regression, broken contract, required behavior gap or evidenced maintainability defect; blocks until resolved or an authorized decision addresses it. |
| Suggestion |
Optional polish or future capability; non-blocking and omitted unless useful or requested. |
Use confidence to filter uncertain claims, not to promote a certain nit into a Critical finding. Respect repository-specific severity labels and provider-required review policy.
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.
## Recommended Action
1. Resolve demonstrated blocking issues, batching fixes by bug class.
2. Re-review changed code and affected interactions only.
3. Leave optional suggestions non-blocking; do not expand the PR to obtain reviewer silence.
4. After three unsuccessful fix/re-review rounds, report the recurring findings for an owner decision. The cap never authorizes merging known defects.
If no issues are found at any severity level, confirm the code meets standards with
a brief summary of what was reviewed and which dimensions were applied.
Aspect Selection
Users can request specific dimensions instead of running all:
| User Says |
Dimensions Applied |
| "review my PR" / "check my changes" |
All applicable (default) |
| "review the code" / "check code quality" |
Code review only |
| "check the tests" / "is test coverage good" |
Test analysis only |
| "check error handling" / "find silent failures" |
Error handling only |
| "review the types" / "check type design" |
Type design only |
| "check the comments" / "review documentation" |
Comment quality only |
When a specific aspect is requested, load only that reference file and skip routing.
Error Handling
| Problem |
Resolution |
| No git diff available |
Ask user to specify files or scope |
| CLAUDE.md not found |
Review against general best practices; note the absence |
| No test files in diff |
Skip test analysis dimension; note in output |
| Diff is empty |
Report "no changes to review" and stop |
| Diff exceeds context limits |
Focus on files the user is most likely to care about; summarize skipped files |
Calibration Rules
- 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.
- File:line references are mandatory. Every finding must include a specific location.
Vague findings ("consider improving error handling") are not actionable.
- Project rules override general rules. If CLAUDE.md says "use arrow functions",
do not flag arrow functions even if conventional style prefers
function declarations.
- Deduplication is mandatory. If two dimensions flag the same issue, merge them.
Never report the same problem twice.
- Progress over perfection. Approve when required behavior and code health meet the repository standard; no finding quota and no mandatory polish. A clean review is a valid result.
- 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.
Rationalizations
| Rationalization |
Reality |
| "Tests pass, so the code is fine" |
Tests are necessary but insufficient — they miss architecture, security, readability, and maintainability concerns |
| "It's a small diff, no real review needed" |
Small changes cause most production incidents; a 3-line auth bypass is worse than a 300-line refactor |
| "We'll clean it up later" |
Fix demonstrated current defects now; defer optional capability and polish without weakening current correctness |
| "The author is senior, I trust them" |
Seniority doesn't prevent mistakes; fresh eyes catch what familiarity blinds |
| "I already reviewed similar code recently" |
Each diff has unique context — assumptions from past reviews cause missed issues |
| "This is just a refactor, nothing can break" |
Refactors change behavior in subtle ways — verify with tests and trace call sites |
Red Flags
- Approving without reading the changed behavior and enough surrounding context to verify affected contracts
- No file:line references in findings — vague feedback is not actionable
- Skipping a review dimension because "it looks fine"
- Reporting only style issues while ignoring logic, security, or architecture
- Reviewing generated code (migrations, protobuf stubs) with the same rigor as hand-written code
- Merging findings from different dimensions without deduplication
Verification
1---2name: pr-review3description: 'Diff-based PR review across code quality, test coverage, silent failures, type design, and comment quality with severity-ranked findings. Triggers on: "review my PR", "review this code", "check my changes", "audit this PR", "code review". NOT for pre-landing gate, use pre-landing-review.'4metadata:5 source: https://skillmd.com/skills/mathews-tom/pr-review6 version: 1.2.07 category: review8 tags: [code-review, pull-request, quality, diff-analysis]9 difficulty: intermediate10 phase: review11---1213# PR Review1415Diff-based code review across five dimensions. Reads the changed files, selects16applicable review methodologies, and produces an aggregated report with severity-ranked17findings.1819> **Native alternative:** Claude Code's `/ultrareview` runs a lightweight native bug-focused review (three free per month on Pro/Max plans at Opus 4.7's launch). Use this skill for five-dimension severity-ranked analysis (code quality + tests + error handling + types + comments) with file:line references; use `/ultrareview` for a quick bug-hunting pass on a diff.2021## Reference Files2223| File | Contents | Load When |24| ------------------------------- | ------------------------------------------------------- | ------------------------------- |25| `references/code-review.md` | Guideline compliance, bug detection, confidence scoring | Always |26| `references/test-analysis.md` | Behavioral test coverage, criticality rating | Test files changed |27| `references/error-handling.md` | Silent failure patterns, catch block analysis | Error handling changed |28| `references/type-design.md` | Invariant analysis, 4-dimension rating rubric | Type definitions added/modified |29| `references/comment-quality.md` | Comment accuracy, long-term value, rot detection | Comments/docstrings added |3031---3233## Workflow3435### Phase 1: Scope36371. Determine the review target:38 - Default: `git diff` (unstaged changes)39 - If user specifies a PR: `git diff main...HEAD` or `gh pr diff <number>`40 - If user specifies files: review those files directly412. List all changed files with `git diff --name-only`423. Read the project's CLAUDE.md (if present) for project-specific rules4344### Phase 2: Route4546Classify changed files and select applicable dimensions:4748| Condition | Dimension | Reference to Load |49| ---------------------------------------------------------------------------- | --------------- | ------------------------------- |50| Always | Code review | `references/code-review.md` |51| Files matching `*test*`, `*spec*`, `*_test.*`, `test_*` | Test analysis | `references/test-analysis.md` |52| Files containing try/catch, except, .catch, Result, error callbacks | Error handling | `references/error-handling.md` |53| Files containing class, interface, type, struct, enum, dataclass definitions | Type design | `references/type-design.md` |54| Files with new/modified docstrings, JSDoc, or block comments | Comment quality | `references/comment-quality.md` |5556Load only the reference files that apply. Skip dimensions with no matching files.5758### Phase 3: Review5960Review the changed behavior and affected contracts using the applicable methodologies:61621. **Code review** — report demonstrated bugs and explicit rule violations at confidence >= 80.632. **Test analysis** — identify plausible consumer-visible regressions that required behavior does not cover.643. **Error handling** — trace failures and their caller-visible consequences.654. **Type design** — assess current invariants and actual consumers; speculative extensibility is not a defect.665. **Comment quality** — report misleading contracts that affect correct use; ordinary polish is optional.6768Read enough surrounding implementation and call sites to prove each scenario. Review changed source rather than generated copies. On fixes, review the changed code and affected interactions; repeat a broader review only when a changed contract or base invalidates the earlier assessment.6970### Phase 4: Aggregate7172Merge all findings into a single report, deduplicated and severity-ranked.7374**Deduplication rules:**7576- If two dimensions flag the same file:line, keep the higher-severity finding77- If code-review and error-handling both flag an empty catch block, merge into one78 finding with the error-handling severity (it's the specialist)7980**Severity is impact, not confidence or a design score.**8182| Severity | Evidence and consequence |83| --- | --- |84| Critical | Demonstrated severe security, data-loss, availability or equivalent consumer risk; blocks merge. |85| Important | Concrete regression, broken contract, required behavior gap or evidenced maintainability defect; blocks until resolved or an authorized decision addresses it. |86| Suggestion | Optional polish or future capability; non-blocking and omitted unless useful or requested. |8788Use confidence to filter uncertain claims, not to promote a certain nit into a Critical finding. Respect repository-specific severity labels and provider-required review policy.8990---9192## Output Format9394```text95# PR Review Summary9697**Scope:** [X files changed, Y dimensions applied]98**Dimensions:** [list of active dimensions]99100## Critical Issues (must fix before merge)101- **[dimension]** `file:line` — Description. Fix suggestion.102103## Important Issues (should fix)104- **[dimension]** `file:line` — Description. Fix suggestion.105106## Suggestions (consider)107- **[dimension]** `file:line` — Description.108109## Recommended Action1101. Resolve demonstrated blocking issues, batching fixes by bug class.1112. Re-review changed code and affected interactions only.1123. Leave optional suggestions non-blocking; do not expand the PR to obtain reviewer silence.1134. After three unsuccessful fix/re-review rounds, report the recurring findings for an owner decision. The cap never authorizes merging known defects.114```115116If no issues are found at any severity level, confirm the code meets standards with117a brief summary of what was reviewed and which dimensions were applied.118119---120121## Aspect Selection122123Users can request specific dimensions instead of running all:124125| User Says | Dimensions Applied |126| ----------------------------------------------- | ------------------------ |127| "review my PR" / "check my changes" | All applicable (default) |128| "review the code" / "check code quality" | Code review only |129| "check the tests" / "is test coverage good" | Test analysis only |130| "check error handling" / "find silent failures" | Error handling only |131| "review the types" / "check type design" | Type design only |132| "check the comments" / "review documentation" | Comment quality only |133134When a specific aspect is requested, load only that reference file and skip routing.135136---137138## Error Handling139140| Problem | Resolution |141| --------------------------- | ----------------------------------------------------------------------------- |142| No git diff available | Ask user to specify files or scope |143| CLAUDE.md not found | Review against general best practices; note the absence |144| No test files in diff | Skip test analysis dimension; note in output |145| Diff is empty | Report "no changes to review" and stop |146| Diff exceeds context limits | Focus on files the user is most likely to care about; summarize skipped files |147148---149150## Calibration Rules1511521. **Precision over recall.** A false positive erodes trust in the review. Only report153 issues at >= 80 confidence (code review) or >= 5 criticality (tests). Silence is154 better than noise.1552. **File:line references are mandatory.** Every finding must include a specific location.156 Vague findings ("consider improving error handling") are not actionable.1573. **Project rules override general rules.** If CLAUDE.md says "use arrow functions",158 do not flag arrow functions even if conventional style prefers `function` declarations.1594. **Deduplication is mandatory.** If two dimensions flag the same issue, merge them.160 Never report the same problem twice.1615. **Progress over perfection.** Approve when required behavior and code health meet the repository standard; no finding quota and no mandatory polish. A clean review is a valid result.1626. **Code-refiner handles simplification.** This skill reviews and reports. It does not163 refactor or simplify — that's the `code-refiner` skill's job. Keep the roles separate.164165## Rationalizations166167| Rationalization | Reality |168|---|---|169| "Tests pass, so the code is fine" | Tests are necessary but insufficient — they miss architecture, security, readability, and maintainability concerns |170| "It's a small diff, no real review needed" | Small changes cause most production incidents; a 3-line auth bypass is worse than a 300-line refactor |171| "We'll clean it up later" | Fix demonstrated current defects now; defer optional capability and polish without weakening current correctness |172| "The author is senior, I trust them" | Seniority doesn't prevent mistakes; fresh eyes catch what familiarity blinds |173| "I already reviewed similar code recently" | Each diff has unique context — assumptions from past reviews cause missed issues |174| "This is just a refactor, nothing can break" | Refactors change behavior in subtle ways — verify with tests and trace call sites |175176## Red Flags177178- Approving without reading the changed behavior and enough surrounding context to verify affected contracts179- No file:line references in findings — vague feedback is not actionable180- Skipping a review dimension because "it looks fine"181- Reporting only style issues while ignoring logic, security, or architecture182- Reviewing generated code (migrations, protobuf stubs) with the same rigor as hand-written code183- Merging findings from different dimensions without deduplication184185## Verification186187- [ ] Changed behavior and affected contracts reviewed with sufficient surrounding context188- [ ] Applicable dimensions covered; irrelevant dimensions omitted189- [ ] Every finding includes file:line, concrete scenario, consequence and bug class190- [ ] Severity reflects impact, not confidence, a score or a target finding count191- [ ] Blocking and non-blocking feedback distinguished; provider-required reviews preserved192- [ ] Re-review is scoped to changed code and affected interactions; recurring failures stop after three rounds