Review

PR Review Agent

Review a pull request for correctness, architecture, conventions, and frontend best practices.

Step 1: Gather Context

Read the PR

1. Fetch PR metadata: gh pr view $ARGUMENTS --json number,title,body,headRefName,baseRefName,files,url
2. Fetch the full diff: gh pr diff $ARGUMENTS
3. List changed files: gh pr view $ARGUMENTS --json files --jq '.files[].path'

Read the linked issue

1. Extract issue references from the PR body (look for Closes #N, Fixes #N, Resolves #N, or #N references)
2. For each linked issue, read the full issue and comments:

   gh issue view <number> --json title,body,comments
   

3. Look for:
   • Investigation reports (between <!-- BUG-INVESTIGATION --> markers) — understand the root cause
   • Implementation plans (between <!-- IMPLEMENTATION-PLAN --> markers) — understand the intended approach
   • Team feedback in comments — requirements, constraints, or scope changes
4. If no issue is linked, note this in the review as an informational comment

Understand the intent

Before reviewing any code, write down (internally):

• What problem does this PR solve? (from the issue)
• What approach was planned? (from the plan, if any)
• What constraints or conventions apply? (from CLAUDE.md)

Step 2: Run Quality Gates

Run these checks and record results:

npm run typecheck

npm run lint

If either fails, include the specific errors in the review as must-fix items.

Step 3: Review the Diff

Read the shared review criteria at .claude/skills/review/CRITERIA.md. This is the single source of truth for what to check.

For each changed file, evaluate against all 7 sections of the criteria. Organize findings by severity:

• Sections 1-2 (Must-Fix): Bugs, correctness, security. The PR should not merge without addressing these.
• Sections 3-5 (Should-Fix): Architecture, React patterns, TypeScript. Strong recommendation to fix.
• Sections 6-7 (Suggestion): Tailwind/shadcn, conventions. Nice-to-have, not blocking.

Step 4: Check Completeness Against Issue

If an implementation plan exists in the issue:

• Verify every task in the plan has corresponding code changes
• Flag any planned work that appears missing or partially implemented
• Note any scope additions not in the original plan

Step 5: Post the Review

Post findings as a GitHub PR review using gh api, not as an issue comment.

Severity levels

• Must-Fix — Bugs, security issues, type/lint failures. The PR should not merge without addressing these.
• Should-Fix — Architecture violations, missing patterns, significant code quality issues. Strong recommendation to fix.
• Suggestion — Style, naming, minor improvements. Nice-to-have, not blocking.

Review format

Post inline comments on specific lines where possible using the PR review API. Then post a summary review.

# Submit review with inline comments
gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
  --method POST \
  -f body="$(cat <<'EOF'
## PR Review

**Issue context:** #[issue number] — [one-line summary of what this PR should accomplish]

### Quality Gates
- Typecheck: PASS/FAIL
- Lint: PASS/FAIL

### Must-Fix ([count])
[Numbered list of blocking issues with file:line references]

### Should-Fix ([count])
[Numbered list of recommended fixes with file:line references]

### Suggestions ([count])
[Numbered list of non-blocking improvements]

### Completeness
[If linked to an issue with a plan: status of each planned task]
[If no plan: general assessment of whether the PR fully addresses the issue]

### Summary
[1-3 sentences: overall assessment and whether this is ready to merge after fixes]
EOF
)" \
  -f event="COMMENT" \
  --json url

Use event: "REQUEST_CHANGES" if there are must-fix items, "APPROVE" if clean, "COMMENT" otherwise.

Inline comment format

For each specific issue, post an inline comment on the relevant line:

gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
  --method POST \
  -f event="COMMENT" \
  -f body="Summary" \
  --jq '.id'

Then add comments to the review using the review comments API. Group related comments into a single review submission.

Rules

• Read the issue first. Never review code without understanding the intent.
• Be specific. Every finding must include a file path, line number, and concrete suggestion.
• Prioritize correctly. A real bug matters more than a style nit. Don't bury important findings in noise.
• Don't nitpick what lint catches. If ESLint or TypeScript will catch it, don't duplicate the feedback — just report the gate failure.
• Acknowledge good work. If the PR is well-structured or handles edge cases well, say so briefly.
• Stay in scope. Review the diff, not the entire codebase. Don't suggest refactoring unrelated code.
• Follow ALL conventions in CLAUDE.md