prp-review

name	prp-review
description	Comprehensive multi-pass PR code review covering quality, security, dependencies, docs, tests, error handling, types, performance, accessibility, and simplification. Posts findings to GitHub.
metadata	{"short-description":"Review pull request"}

Agent Mode Detection

If your input context contains [WORKSPACE CONTEXT] (injected by a multi-agents framework), you are running as a sub-agent. Apply these optimizations:

• Skip Phase 1 context extraction if a pr-context-*.md file path is provided in the context files — use it directly (the upstream commit_pr agent already gathered this).
• Skip CLAUDE.md reading — already loaded by parent session.
• Skip PR metadata fetch if PR number and diff are available in context files.
• Skip Validation Phase if context file already contains validation results (from /prp-implement or /prp-ralph).

All review passes (code, security, deps, docs, tests, etc.) run unchanged — these are where quality comes from.

---

PRP Review — Comprehensive Multi-Pass PR Code Review

Input

PR number and optional aspects: $ARGUMENTS

Format: <pr-number> [aspects: comments|tests|errors|types|code|security|deps|docs|perf|a11y|simplify|all] [--since-last-review] [--metrics]

Mission

Perform a comprehensive multi-pass code review. Each pass focuses on a specific quality dimension. Report only high-confidence issues (80%+ certain).

---

Phase 0: Context Detection (Token Optimization)

Before gathering PR information, check if context was pre-generated by /prp-implement or /prp-ralph:

If --context <path> argument provided: Validate the path is under .prp-output/ and does not contain .. segments. Reject absolute paths. Then verify the ## PR Diff section in the file contains actual content (not empty). If empty, WARN and fall through to Phase 1. Otherwise use the context file directly.

If no --context argument, auto-detect:

BRANCH=$(git branch --show-current)
CONTEXT_FILE=".prp-output/reviews/pr-context-${BRANCH}.md"
test -f "$CONTEXT_FILE" && echo "FOUND" || echo "NOT_FOUND"

Result	Action
FOUND	Read the context file. Use file list, implementation summary, and validation status from it. Skip Phase 1 context extraction. If --since-last-review flag present, still proceed through Phase 0.5. Display: "Token optimization: Using pre-generated context from pr-context-{BRANCH}.md — skipping context extraction."
NOT_FOUND	Proceed to Phase 0.5 (if --since-last-review) then Phase 1 to extract context.

When context file is found, extract from it:

• Files Changed — use directly instead of gh pr diff --name-only
• Implementation Summary — provide as background for each pass
• Validation Status — skip re-running validation if results are present
• Review Focus Areas — prioritize these during review passes

---

Phase 0.5: Incremental Review Detection

Only when --since-last-review flag is provided. Skip this phase otherwise.

Detect Previous Review

First, resolve the PR number if not already known (from $ARGUMENTS or gh pr view --json number -q '.number').

# Find previous review artifact for this PR (NUMBER must be resolved first)
REVIEW_FILE=$(ls -t .prp-output/reviews/pr-${NUMBER}-review-codex.md 2>/dev/null | head -1)

Result	Action
Review file found	Extract timestamp from file (look for reviewed: in frontmatter or file modification time)
No review file	WARN: "No previous review found for PR #{NUMBER}. Running full review instead." Proceed to Phase 1.

Get Changed Files Since Last Review

# Get files changed since last review timestamp
# Note: --since uses commit date. If commits were rebased, results may be incomplete.
# In that case, fall back to full review.
git log --since="{TIMESTAMP}" --name-only --pretty=format:"" | sort -u

Result	Action
No changes since timestamp	"No new changes since last review at {TIMESTAMP}. Nothing to re-review." EXIT.
Changes found	Display: "Incremental review: {N} files changed since {TIMESTAMP}"

Incremental Context

When in incremental mode:

1. Create context with ONLY changed files' diff: git diff {BASE}...HEAD -- {changed-files}
2. Include unchanged files that import/use changed code (for cross-file context)
3. Load previous review findings for merge later

Finding Merge (After Review Passes Complete)

After incremental review completes, merge with previous review:

1. Resolved: Previous issues where file:line region no longer matches in current diff — mark as "Resolved"
2. Remaining: Previous issues still present in current code — keep
3. New: Issues from current review not in previous — add as "New"

Display delta summary:

Incremental Review Delta:
- New issues: {N}
- Resolved: {M}
- Remaining from previous: {K}

CHECKPOINT: Incremental mode active. Reviewing {N} changed files only.

---

Phase 1: Context Extraction

Skip if Phase 0 found existing context.

1.1 Identify the PR

• If PR number provided: gh pr view <number>
• If no number: gh pr view (current branch's PR)
• If gh pr view fails (no PR for this branch): STOP — "No open PR found for branch {BRANCH}. Create a PR first with gh pr create, or pass a PR number explicitly."
• Get PR branch name and changed files

1.2 Check PR State

State	Action
MERGED	STOP: "PR already merged. Nothing to review."
CLOSED	WARN: "PR is closed. Review anyway? (historical analysis)"
DRAFT	NOTE: "Draft PR — focusing on direction, not polish"
OPEN	PROCEED with review

• Never push to main without explicit user approval

1.3 Gather Context

Extract all context in ONE pass:

# PR metadata
gh pr view {NUMBER} --json number,title,body,author,headRefName,baseRefName,state,additions,deletions,changedFiles

# Structural diff (compact overview — use prp-diff if available)
if [ -x .prp/scripts/prp-diff.sh ]; then
  .prp/scripts/prp-diff.sh {NUMBER}
fi

# Full PR diff
gh pr diff {NUMBER}

# Changed files list
gh pr diff {NUMBER} --name-only

Also read:

• CLAUDE.md — project rules and conventions
• Implementation report (if exists): ls -t .prp-output/reports/*-report*.md 2>/dev/null | head -1
• Related plan (if referenced in implementation report)

1.4 Create Context File

mkdir -p .prp-output/reviews

Context File Path: .prp-output/reviews/pr-context-{BRANCH}.md

---
pr: {NUMBER}
branch: "{BRANCH}"
extracted: {ISO_TIMESTAMP}
files_changed: {N}
---

# PR Review Context: #{NUMBER} — {TITLE}

## PR Metadata
- **Author**: {author}
- **Branch**: {head} → {base}
- **State**: {state}
- **Size**: +{additions}/-{deletions} across {changedFiles} files

## Project Guidelines (from CLAUDE.md)
{relevant sections from CLAUDE.md}

## Changed Files
{list from gh pr diff --name-only}

## PR Diff
{full diff output}

## Implementation Context
{implementation report summary, if found — otherwise "No implementation report found"}

1.5 Classify Files

Categorize each changed file: production, test, config, types, docs.

All review passes read from this shared context file.

After writing the context file, verify it was created:

test -f "$CONTEXT_FILE" || echo "FATAL: Could not create context file at $CONTEXT_FILE"

If the file was not created, STOP — do not proceed with review passes without a context file.

CHECKPOINT: Context file created and verified. All passes will read from this file.

---

Phase 1.5: Large PR Detection

Check PR size after context extraction.

Size Check

Calculate total changes from PR metadata: additions + deletions.

Size	Action
≤500 lines	Proceed normally — standard review
501-1000 lines	Large PR strategy — phased review by risk tier
>1000 lines	Large PR strategy + recommend splitting

File Risk Categorization

When large PR detected, categorize each changed file:

Tier	Category	Examples	Review Depth
Tier 1 (Critical)	Security, auth, payment, encryption, permissions	auth/, middleware/, crypto, *.key	Full depth — all applicable passes
Tier 2 (Business Logic)	API endpoints, services, business rules, data processing	services/, controllers/, api/, routes/	Full depth — all applicable passes
Tier 3 (Support)	Utils, helpers, shared components, configuration	utils/, helpers/, components/shared/, config/	Core passes only (code, security)
Tier 4 (Low Risk)	Tests, documentation, config files, generated code	test/, docs/, *.config.*, *.generated.*	Core passes only (code)

Phased Review Strategy

Phase A: Review Tier 1-2 files (critical + business logic)
├── All applicable passes run
├── Full depth analysis
└── Priority findings reported first

Phase B: Review Tier 3-4 files (support + low risk)
├── Core passes only
├── Quick scan for obvious issues
└── Lower priority findings

Coverage Map

Include in review summary:

### File Coverage Map
| File | Tier | Passes Run |
|------|------|------------|
| `src/auth/login.ts` | 1 (Critical) | code, security, deps, perf |
| `src/api/users.ts` | 2 (Business) | code, security, deps, tests |
| `src/utils/format.ts` | 3 (Support) | code, security |
| `tests/auth.test.ts` | 4 (Low Risk) | code |

Split Recommendation

If PR >1000 lines, display:

Large PR detected ({N} lines). Consider splitting into smaller PRs for better review quality.
Suggested splits based on file categories:
- PR 1: {Tier 1-2 files} ({N} lines)
- PR 2: {Tier 3-4 files} ({M} lines)

CHECKPOINT: Large PR strategy applied. Files categorized by risk tier.

---

Aspect Selection Logic

Aspect	Focus Area	When to Run
code	General quality and guidelines	Always — core quality check
security	OWASP Top 10, vulnerabilities	Always — security review
deps	CVEs, outdated packages, licenses	Always — dependency health
docs	Updates stale documentation	Almost always — skip for typo/test/config-only
tests	Test coverage and quality	When test files or tested code changed
comments	Comment accuracy and value	When comments/docstrings added
errors	Silent failures, error handling	When error handling changed
types	Type design quality	When types added/modified
perf	Performance bottlenecks	When performance-sensitive patterns detected or explicitly requested
a11y	Accessibility compliance	When UI/frontend files changed or explicitly requested
simplify	Code simplification	Last — after other passes
all	All applicable aspects	Default if no aspects specified

Skip docs only when: typo-only fixes, test-only changes, documentation-only changes, config tweaks.

Conditional Pass Dispatch

Auto-detect file types from PR diff and dispatch specialist passes automatically.

File-Type → Pass Mapping

File Pattern	Pass	Trigger
.tsx, .jsx, .vue, .svelte, .css, .scss, .html	a11y (Accessibility)	UI/frontend files changed
.sql, imports from prisma, drizzle, knex, sequelize, typeorm	perf (Performance)	Database patterns detected
router, endpoint, controller, handler, api/ path	perf (Performance)	API endpoint patterns detected
for.*await, Promise.all, .map(, setInterval, setTimeout	perf (Performance)	Async/loop patterns detected

Detection Logic

Scan changed files from PR diff:

If UI files detected (.tsx/.jsx/.vue/.svelte/.css/.scss/.html):
└── Auto-add: accessibility pass

If performance-sensitive patterns detected:
├── DB imports (prisma, drizzle, knex, sequelize, typeorm, .sql files)
├── API patterns (router, endpoint, controller, handler, api/ path)
└── Async/loop patterns (for.*await, Promise.all, .map(, setInterval)
└── Auto-add: performance pass

Auto-dispatch Display

When passes are auto-dispatched, display to user:

Auto-dispatching: accessibility pass (3 .tsx files detected)
Auto-dispatching: performance pass (DB query patterns in 2 files)

Note: Conditional dispatch adds to existing passes — it does NOT replace the always-run passes (code, security, deps).

---

Per-File Review Checklist

For EVERY changed file, check against these 7 categories:

• Correctness: Logic errors, edge cases, error handling
• Type Safety: No implicit any, return types declared, type guards
• Pattern Compliance: Codebase patterns, naming conventions, imports
• Security: Input validation, secrets exposure, injection vulnerabilities
• Performance: N+1 queries, unnecessary async, memory leaks
• Completeness: Tests for new code, docs updated, TODOs addressed
• Maintainability: Readability, over/under-engineering, magic numbers

Issue Severity Levels

Level	Icon	Criteria	Examples
Critical	RED	Blocking — must fix	Security vulnerabilities, data loss, crashes
High	ORANGE	Should fix before merge	Type safety violations, logic errors
Medium	YELLOW	Should consider	Pattern inconsistencies, missing edge cases
Low	BLUE	Suggestions	Style preferences, minor optimizations

Implementation report check: Documented deviations are intentional — only flag undocumented deviations.

---

Review Passes

Pass 1: Code Quality & Guidelines (Always)

Focus: Project guideline compliance, bugs, and quality issues.

• Read conventions from CLAUDE.md / project config
• Focus on the diff — don't review unchanged code
• Bug detection: logic errors, off-by-one, null handling, race conditions
• Naming conventions, import organization, dead code
• Confidence threshold: 80%+ — report only high-confidence issues
• Check implementation report for documented deviations (don't flag intentional choices)

Do NOT report: Style preferences already handled by linter, theoretical issues without clear impact.

Pass 2: Documentation Impact (Almost Always)

Focus: Update documentation affected by code changes.

• Check for stale docs in CLAUDE.md, README.md, and docs/ directory
• New features must be documented, API changes reflected
• Missing references, broken links, outdated examples
• Auto-action: If doc updates needed, make the changes, commit and push to PR branch
• Display what was updated: "Updated: CLAUDE.md (new command reference), README.md (config section)"

Skip only when: typo-only fixes, test-only changes, documentation-only changes, config tweaks.

Pass 3: Security Review (Always)

Focus: OWASP Top 10 vulnerabilities with clear attack vectors.

• Injection: SQL, NoSQL, OS command, LDAP injection
• Broken Auth: Weak session management, credential exposure
• Data Exposure: Sensitive data in logs, responses, or error messages
• SSRF: Server-side request forgery via user-controlled URLs
• Input validation gaps, secrets in code, unsafe deserialization
• Report only vulnerabilities with clear attack vectors — not theoretical issues
• Include severity (Critical/High/Medium/Low) and specific remediation for each finding

Do NOT report: Theoretical vulnerabilities without exploitable path, issues in test code.

Pass 4: Dependency Analysis (Always)

Focus: Dependency security and health.

• Known CVEs in direct and transitive dependencies
• Outdated packages with available security patches
• Abandoned or deprecated dependencies (no updates >2 years)
• License compliance issues (copyleft in proprietary projects)
• Include exact remediation commands: npm audit fix, specific version bumps, alternative packages
• Check package.json/lock file consistency

Do NOT report: Minor version bumps without security implications, devDependency version lag.

Pass 5: Test Coverage (When Tests Changed)

Focus: Behavioral test coverage and quality.

• Behavioral coverage — not just line metrics
• Identify untested critical paths and edge cases
• Test quality: meaningful assertions, not just snapshot tests
• Rate each recommendation by criticality (1-10): 10 = must-have, 1 = nice-to-have
• Check for flaky test patterns (timing dependencies, shared state)

Do NOT report: Missing tests for trivial getters/setters, low-criticality edge cases.

Pass 6: Comment Analysis (When Comments Added)

Focus: Comment accuracy and long-term value.

• Verify comments match actual code behavior — stale comments are worse than no comments
• Completeness for complex algorithms or business logic
• Comment rot risk: will this comment become stale when code changes?
• JSDoc/TSDoc parameter accuracy

Do NOT report: Missing comments on self-explanatory code, style preferences for comment format.

Pass 7: Error Handling (When Error Handling Changed)

Focus: Silent failure detection — zero tolerance for swallowed errors.

• Empty catch blocks, catch blocks without logging or re-throw
• Proper user-facing error messages (not raw stack traces)
• Specific catch blocks (not blanket catch(e) for all errors)
• Error propagation correctness — does the error reach the right handler?
• Async error handling: unhandled promise rejections, missing .catch()

Do NOT report: Intentionally empty catches with explanatory comments, test error handling.

Pass 8: Type Design (When Types Changed)

Focus: Type design quality for new or modified types.

• Encapsulation (1-10): Are internals properly hidden?
• Invariant Expression (1-10): Do types enforce business rules?
• Usefulness (1-10): Do types help consumers avoid mistakes?
• Enforcement (1-10): Are types strict enough to catch errors at compile time?
• Check for any escape hatches, overly broad union types, missing discriminants

Do NOT report: Types in test files, generated type files, third-party type augmentations.

Pass 9: Performance (Conditional — When Patterns Detected)

Only run when: auto-dispatched (performance-sensitive patterns detected) OR explicitly requested via perf aspect.

Focus: Performance issues with measurable impact.

• N+1 queries: DB calls inside loops, missing batch/join
• Sequential awaits: await in loops that could be Promise.all
• Memory leaks: Event listeners not cleaned up, growing caches, closures holding references
• Unbounded operations: Missing pagination, unlimited array operations on large datasets
• Unnecessary re-renders: Missing memoization, inline object creation in render
• Confidence threshold: 80%+ — report only issues with measurable impact
• Include quantified impact estimate and fix for each finding

Do NOT report: Micro-optimizations, premature optimization suggestions, theoretical scaling concerns without evidence.

Pass 10: Accessibility (Conditional — When UI Files Changed)

Only run when: auto-dispatched (UI/frontend files detected) OR explicitly requested via a11y aspect.

Focus: WCAG 2.1 compliance for changed UI code.

• Keyboard navigation: All interactive elements focusable and operable
• Screen reader support: Proper semantic HTML, meaningful alt text
• Color contrast: 4.5:1 for normal text, 3:1 for large text
• ARIA usage: Correct roles, states, and properties
• Form labels: All inputs have associated labels
• Focus management: Proper focus order, visible focus indicators
• Report issues with affected user groups (e.g., "keyboard-only users cannot activate this button")

Do NOT report: Accessibility issues in unchanged code, issues in admin-only screens (lower priority).

Pass 11: Simplification (After Other Passes)

Focus: Code clarity while preserving functionality.

• Nested ternaries → if/else
• Clever code → explicit, readable code
• Unnecessary abstractions → direct implementation
• Redundant type assertions, unnecessary type casting
• Auto-action: If improvements made, commit and push to PR branch
• Run last: Only after other passes confirm no critical issues

Do NOT report: Style preferences handled by formatter/linter, changes that would alter behavior.

---

Validation Phase (Run After Review Passes)

Run automated checks to catch issues that code review alone may miss.

Skip if context file contains concrete validation results (actual PASS/FAIL with counts — not template placeholders like ✅ without details). If the Validation Status table has real results (e.g., "✅ PASS | 42 passed" or "❌ FAIL | 3 errors"), trust those results and skip re-running. If results look like unfilled templates, run validation.

Run Validation Suite

# Type checking (adapt to project)
npm run type-check || bun run type-check || npx tsc --noEmit

# Linting
npm run lint || bun run lint

# Tests
npm test || bun test

# Build
npm run build || bun run build

Capture for each: pass/fail status, error count, warning count, specific failures.

Specific Validation

Change Type	Additional Validation
New API endpoint	Test with curl/httpie
Database changes	Check migration exists
Config changes	Verify .env.example updated
New dependencies	Check package.json/lock file

Regression Check

# Full test suite
npm test || bun test

# Specific tests for changed functionality
npm test -- {relevant-test-pattern}

Include validation results in the output report's Validation Results table.

---

Result Deduplication

Before categorizing, deduplicate findings across passes.

Dedup Rules

Two findings are considered duplicates when BOTH conditions are met:

1. Same file region: Same file AND within ±5 lines of each other
2. Same category: Both about the same concern (e.g., both about error handling, both about security)

NOT duplicates (do not merge):

• Different files, even if description is similar
• Same file region but different categories (e.g., security issue + code quality issue at same line)

Merge Strategy

When duplicates found:

• Keep the most detailed description (longest/most specific)
• Use the highest severity from any contributing pass
• List all contributing passes in the "Pass" column: e.g., code, errors
• Combine remediation suggestions if they differ

Example

BEFORE dedup:

Pass	Issue	Location
code	Empty catch block swallows error	api.ts:45
errors	Catch block has no logging or re-throw	api.ts:47

AFTER dedup:

Pass	Issue	Location
code, errors	Empty catch block swallows error — no logging or re-throw	api.ts:45-47

---

Result Aggregation

Category	Description	Action
Critical	Must fix before merge	Block merge
Important	Should fix	Address before merge
Suggestions	Nice to have	Consider
Strengths	What's good	Acknowledge

Verdict Decision Logic

Condition	Verdict
No critical/important issues AND all validation passes	READY TO MERGE
Important issues OR validation warnings (fixable)	NEEDS FIXES
Critical issues OR validation failures	CRITICAL ISSUES

Note: If validation fails, verdict is at least NEEDS FIXES regardless of pass findings.

Summary Format

## PR Review Summary

### Critical Issues (X found)
| Pass | Issue | Location |
|------|-------|----------|
| code | Description | `file.ts:line` |

### Important Issues (X found)
| Pass | Issue | Location |
|------|-------|----------|
| security | Description | `file.ts:line` |

### Suggestions (X found)
| Pass | Suggestion | Location |
|------|------------|----------|
| types | Description | `file.ts:line` |

### Strengths
- Well-structured error handling
- Good test coverage for critical paths

### Validation Results
| Check | Status | Details |
|-------|--------|---------|
| Type Check | {PASS/FAIL} | {notes} |
| Lint | {PASS/WARN} | {count} warnings |
| Tests | {PASS/FAIL} | {count} passed |
| Build | {PASS/FAIL} | {notes} |

### Documentation Updates
- `CLAUDE.md` - Added new command reference
- `README.md` - Updated configuration section

### Verdict
[READY TO MERGE / NEEDS FIXES / CRITICAL ISSUES]

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

Note: Pass column may list multiple passes for deduplicated findings (e.g., code, errors).

---

Output

Report Frontmatter

Include this frontmatter at the top of the review file:

---
pr: {NUMBER}
title: "{TITLE}"
author: "{AUTHOR}"
reviewed: {ISO_TIMESTAMP}
verdict: {READY TO MERGE / NEEDS FIXES / CRITICAL ISSUES}
---

Save Local Review

Save aggregated review to .prp-output/reviews/pr-{NUMBER}-review-codex.md before posting to GitHub.

Note: Uses -codex suffix to identify which tool produced the review and prevent overwriting reviews from other tools (each tool uses its own suffix for parallel review capability).

Post to GitHub

Condition	Action
READY TO MERGE	gh pr review {NUMBER} --approve --body-file .prp-output/reviews/pr-{NUMBER}-review-codex.md
NEEDS FIXES or CRITICAL ISSUES	gh pr review {NUMBER} --request-changes --body-file .prp-output/reviews/pr-{NUMBER}-review-codex.md
Draft PR	gh pr comment {NUMBER} --body-file .prp-output/reviews/pr-{NUMBER}-review-codex.md (comment only — no formal review on drafts)

If gh pr review fails (e.g., permission denied, fork PR restrictions):

1. Log the actual error message from gh
2. Display: "WARNING: Could not post formal review (error: {message}). Falling back to PR comment — formal approve/request-changes not applied."
3. Fall back to: gh pr comment {NUMBER} --body-file .prp-output/reviews/pr-{NUMBER}-review-codex.md

---

Review Metrics Collection

Append Metrics After Every Review

After publishing to GitHub, append one JSONL line to .prp-output/reviews/review-metrics.jsonl:

{"timestamp":"2026-03-14T10:30:00Z","pr_number":163,"branch":"feature/auth","review_type":"single","verdict":"NEEDS_FIXES","total_issues":5,"critical":1,"important":2,"suggestions":2,"passes_run":["code","security","deps","docs","tests","errors","types"],"conditional_passes":["a11y"],"incremental":false,"large_pr":false,"lines_changed":342,"files_changed":8}

Fields:

• timestamp — ISO 8601 review completion time
• pr_number — PR number reviewed
• branch — Branch name
• review_type — Always "single" for this command (distinguishes from multi-agent "agents" reviews)
• verdict — READY_TO_MERGE / NEEDS_FIXES / CRITICAL_ISSUES
• total_issues — Total findings count
• critical, important, suggestions — Counts by severity
• passes_run — List of all passes that ran
• conditional_passes — List of passes added by conditional dispatch
• incremental — Whether --since-last-review was used
• large_pr — Whether large PR strategy was applied
• lines_changed, files_changed — PR size metrics

# Append (creates file if not exists)
mkdir -p .prp-output/reviews
echo '{...}' >> .prp-output/reviews/review-metrics.jsonl || echo "WARNING: Failed to append review metrics. Review results are saved, but metrics tracking is incomplete."

--metrics Flag: Aggregate Summary

When --metrics flag provided (without PR number), display aggregate summary and EXIT:

# Read metrics
cat .prp-output/reviews/review-metrics.jsonl

Display:

## Review Metrics Summary

**Total Reviews**: {N}
**Period**: {earliest timestamp} — {latest timestamp}

### Verdicts
| Verdict | Count | % |
|---------|-------|---|
| READY TO MERGE | {N} | {%} |
| NEEDS FIXES | {N} | {%} |
| CRITICAL ISSUES | {N} | {%} |

### Issues by Severity
| Severity | Total | Avg per Review |
|----------|-------|---------------|
| Critical | {N} | {avg} |
| Important | {N} | {avg} |
| Suggestions | {N} | {avg} |

### Pass Contribution
| Pass | Times Run | Issues Found |
|------|-----------|-------------|
| code | {N} | {total} |
| security | {N} | {total} |
| deps | {N} | {total} |
| ... | ... | ... |

### Review Efficiency
- Incremental reviews: {N} ({%} of total)
- Large PR reviews: {N}
- Conditional dispatches: {N} (a11y: {N}, perf: {N})

If no metrics file exists: "No review metrics found. Metrics will be collected after your first review."

---

Update Implementation Report

After posting to GitHub, update the implementation report to close the feedback loop.

Find Implementation Report

# Find report matching the PR branch
BRANCH=$(gh pr view <PR_NUMBER> --json headRefName -q '.headRefName')
ls -t .prp-output/reports/*-report*.md 2>/dev/null | head -1

Append Review Outcome

If implementation report exists, append the following section to the end of the report:

---

## Review Outcome

**Reviewed**: {ISO_TIMESTAMP}
**PR**: #{NUMBER}
**Verdict**: {READY TO MERGE / NEEDS FIXES / CRITICAL ISSUES}
**Review File**: `.prp-output/reviews/pr-{NUMBER}-review-codex.md`

| Category | Count |
|----------|-------|
| Critical | {N} |
| Important | {N} |
| Suggestions | {N} |

{If NEEDS FIXES or CRITICAL ISSUES: list top issues to address}

If no implementation report found: Skip this step silently (PR may not have been created via PRP workflow).

---

Update PRD (if applicable)

If implementation report references a Source PRD:

Verdict	PRD Update
READY TO MERGE	Change phase status from complete to reviewed
NEEDS FIXES	Add note: "Review: {N} issues to address"
CRITICAL ISSUES	Add note: "Blocked: {brief reason}"

---

Workflow Integration

Before creating PR:

1. Run $prp-review on current branch
2. Fix critical and important issues
3. Re-run to verify
4. Create PR

During PR review:

1. Run $prp-review <pr-number>
2. Review posts summary to GitHub with formal approve/request-changes
3. Address feedback
4. Re-run targeted aspects

After making changes:

1. Run specific aspects: $prp-review <pr-number> tests code
2. Verify issues resolved
3. Push updates

---

Usage Examples

$prp-review 163                        # Full review
$prp-review 163 tests errors           # Specific aspects
$prp-review 163 security deps          # Security + dependency only
$prp-review                            # Current branch's PR
$prp-review 42 code docs              # Only code and docs
$prp-review 42 simplify               # Just simplify
$prp-review 42 perf a11y              # Performance + accessibility focus
$prp-review 163 --since-last-review   # Incremental re-review
$prp-review --metrics                  # View review metrics

---

Edge Cases

Situation	Action
PR has 500+ changed files	Apply Large PR Strategy (Phase 1.5) — tier-based review
gh pr diff returns empty	STOP — "No changes to review. Verify the branch is pushed and the correct base branch is set. Run gh pr diff {NUMBER} manually to diagnose."
No PR found for current branch	STOP — "No open PR found for branch. Create a PR first with gh pr create, or pass a PR number explicitly."
--context path with empty diff	WARN and fall through to Phase 1 for fresh context extraction
No CLAUDE.md or conventions file	Proceed — rely on codebase patterns from diff
PR is a revert commit	Focus on: was the revert correct? Any side effects?
PR modifies only generated files	Skip most passes, note "generated code" in review
Review artifact already exists	Overwrite with new review (timestamp in frontmatter tracks versions)
--metrics with no metrics file	Display "No review metrics found" and EXIT
--metrics with PR number	Display metrics first, then proceed with review

---

Critical Reminders

1. Understand before judging. Read full context, not just the diff.
2. Be specific. Include file:line references and concrete fix suggestions.
3. Prioritize. Use severity levels honestly — not everything is critical.
4. Be constructive. Offer solutions, not just problems.
5. Acknowledge good work. If something is done well, say so.
6. Run validation. Don't skip automated checks.
7. Check patterns. Read existing similar code to understand expectations.
8. Think about edge cases. What happens with null, empty, very large, concurrent?
9. Check implementation report. Documented deviations are intentional, not issues.

---

Success Criteria

• CONTEXT_GATHERED: PR metadata, diff, artifacts reviewed
• CODE_REVIEWED: All changed files analyzed with per-file checklist
• SECURITY_REVIEWED: OWASP Top 10 checked
• DEPS_ANALYZED: CVEs, outdated packages, licenses checked
• VALIDATION_RUN: Type check, lint, tests, build executed
• ISSUES_DEDUPLICATED: Duplicate findings merged across passes
• CONDITIONAL_DISPATCHED: Specialist passes triggered by file types (accessibility, performance)
• ISSUES_CATEGORIZED: Findings organized by severity
• PR_UPDATED: Formal review posted to GitHub (approve/request-changes)
• METRICS_COLLECTED: Review metrics appended to JSONL
• RECOMMENDATION_CLEAR: Verdict with rationale
• CHECKLIST_APPLIED: Per-file review checklist used for every changed file
• PRD_UPDATED: If PRD exists, phase status updated based on verdict