/code-review

description: Code review — local uncommitted changes or GitHub PR (pass PR number/URL for PR mode)
argument-hint: [pr-number | pr-url | blank for local review]

Code Review

> PR review mode adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.

**Input**: $ARGUMENTS

---

Mode Selection

If `$ARGUMENTS` contains a PR number, PR URL, or `--pr`: → Jump to **PR Review Mode** below.

Otherwise: → Use **Local Review Mode**.

---

Local Review Mode

Comprehensive security and quality review of uncommitted changes.

Phase 1 — GATHER

git diff --name-only HEAD

If no changed files, stop: "Nothing to review."

Phase 2 — REVIEW

Read each changed file in full. Check for:

**Security Issues (CRITICAL):**

• Hardcoded credentials, API keys, tokens
• SQL injection vulnerabilities
• XSS vulnerabilities
• Missing input validation
• Insecure dependencies
• Path traversal risks

**Code Quality (HIGH):**

• Functions > 50 lines
• Files > 800 lines
• Nesting depth > 4 levels
• Missing error handling
• console.log statements
• TODO/FIXME comments
• Missing JSDoc for public APIs

**Best Practices (MEDIUM):**

• Mutation patterns (use immutable instead)
• Emoji usage in code/comments
• Missing tests for new code
• Accessibility issues (a11y)

Phase 3 — REPORT

Generate report with:

• Severity: CRITICAL, HIGH, MEDIUM, LOW
• File location and line numbers
• Issue description
• Suggested fix

Block commit if CRITICAL or HIGH issues found. Never approve code with security vulnerabilities.

---

PR Review Mode

Comprehensive GitHub PR review — fetches diff, reads full files, runs validation, posts review.

Phase 1 — FETCH

Parse input to determine PR:

| Input | Action | |---|---| | Number (e.g. `42`) | Use as PR number | | URL (`github.com/.../pull/42`) | Extract PR number | | Branch name | Find PR via `gh pr list --head <branch>` |

gh pr view <NUMBER> --json number,title,body,author,baseRefName,headRefName,changedFiles,additions,deletions
gh pr diff <NUMBER>

If PR not found, stop with error. Store PR metadata for later phases.

Phase 2 — CONTEXT

Build review context:

1. **Project rules** — Read `CLAUDE.md`, `.claude/docs/`, and any contributing guidelines 2. **Planning artifacts** — Check `.claude/prds/`, `.claude/plans/`, `.claude/reviews/`, and legacy `.claude/PRPs/{prds,plans,reports,reviews}/` for context related to this PR 3. **PR intent** — Parse PR description for goals, linked issues, test plans 4. **Changed files** — List all modified files and categorize by type (source, test, config, docs)

Phase 3 — REVIEW

Read each changed file **in full** (not just the diff hunks — you need surrounding context).

For PR reviews, fetch the full file contents at the PR head revision:

gh pr diff <NUMBER> --name-only | while IFS= read -r file; do
  gh api "repos/{owner}/{repo}/contents/$file?ref=<head-branch>" --jq '.content' | base64 -d
done

Apply the review checklist across 7 categories:

| Category | What to Check | |---|---| | **Correctness** | Logic errors, off-by-ones, null handling, edge cases, race conditions | | **Type Safety** | Type mismatches, unsafe casts, `any` usage, missing generics | | **Pattern Compliance** | Matches project conventions (naming, file structure, error handling, imports) | | **Security** | Injection, auth gaps, secret exposure, SSRF, path traversal, XSS | | **Performance** | N+1 queries, missing indexes, unbounded loops, memory leaks, large payloads | | **Completeness** | Missing tests, missing error handling, incomplete migrations, missing docs | | **Maintainability** | Dead code, magic numbers, deep nesting, unclear naming, missing types |

Assign severity to each finding:

| Severity | Meaning | Action | |---|---|---| | **CRITICAL** | Security vulnerability or data loss risk | Must fix before merge | | **HIGH** | Bug or logic error likely to cause issues | Should fix before merge | | **MEDIUM** | Code quality issue or missing best practice | Fix recommended | | **LOW** | Style nit or minor suggestion | Optional |

Phase 4 — VALIDATE

Run available validation commands:

Detect the project type from config files (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.), then run the appropriate commands:

**Node.js / TypeScript** (has `package.json`):

npm run typecheck 2>/dev/null || npx tsc --noEmit 2>/dev/null  # Type check
npm run lint                                                    # Lint
npm test                                                        # Tests
npm run build                                                   # Build

**Rust** (has `Cargo.toml`):

cargo clippy -- -D warnings  # Lint
cargo test                   # Tests
cargo build                  # Build

**Go** (has `go.mod`):

go vet ./...    # Lint
go test ./...   # Tests
go build ./...  # Build

**Python** (has `pyproject.toml` / `setup.py`):

pytest  # Tests

Run only the commands that apply to the detected project type. Record pass/fail for each.

Phase 5 — DECIDE

Form recommendation based on findings:

| Condition | Decision | |---|---| | Zero CRITICAL/HIGH issues, validation passes | **APPROVE** | | Only MEDIUM/LOW issues, validation passes | **APPROVE** with comments | | Any HIGH issues or validation failures | **REQUEST CHANGES** | | Any CRITICAL issues | **BLOCK** — must fix before merge |

Special cases:

• Draft PR → Always use **COMMENT** (not approve/block)
• Only docs/config changes → Lighter review, focus on correctness
• Explicit `--approve` or `--request-changes` flag → Override decision (but still report all findings)

Phase 6 — REPORT

Create review artifact at `.claude/reviews/pr-<NUMBER>-review.md` unless the repo already uses legacy `.claude/PRPs/reviews/` for this workstream:

# PR Review: #<NUMBER> — <TITLE>

**Reviewed**: <date>
**Author**: <author>
**Branch**: <head> → <base>
**Decision**: APPROVE | REQUEST CHAN