Review protocol

Purpose: Defines the automated code review process powered by the Claude Code GitHub Action. Every PR is reviewed against project standards and outputs structured JSON findings with formal approve/request_changes decisions.

Quick reference:

• Automated — GitHub Action on every PR with formal approve/request_changes
• Critical — any types, console.log, auth bypass, SQL injection, missing RLS, CLAUDE.md violations
• Warning — Perf issues, missing tests, over-engineering
• Self-fix loop — Max 3 rounds, then flag for manual review
• Pre-PR — Run pnpm type-check && pnpm lint && pnpm test:run && pnpm build locally first

---

Input

You receive:

1. Diff — the full git diff of the PR
2. PR metadata — title, body, author
3. CLAUDE.md — project-specific rules (if present in the repo)

---

Rules by file type

TypeScript (*.ts)

• No any types — Critical severity
• No console.log — Use Axiom/Sentry logging
• No native Date — Use Luxon (DateTime, Duration, Interval)
• Zod validation — Required at system boundaries (API routes, form submissions, external data)
• TODO references — Every TODO must reference a Linear issue (// TODO [RAJ-XXX]: description)

React components (*.tsx)

• All TypeScript rules above, plus:
• Naming conventions — PascalCase components, camelCase hooks (with use prefix), kebab-case files
• Layout mounting — Layout components (headers, sidebars, nav) must be mounted in a parent layout
  • Unmounted components are dead code
• Accessibility (WCAG AA) — Color contrast ≥ 4.5:1, all interactive elements keyboard-navigable, ARIA labels on non-text controls
  • See standards/reference/accessibility.md for full requirements

API routes (app/api/**)

• Auth checks — Required (Clerk middleware or explicit auth() call)
• RLS policies — Required for Supabase queries
• Zod validation — Required on all request bodies
• Activity logging — Required for user-facing actions

Database (prisma/**)

• Reversible migrations — Preferred over destructive changes
• RLS policies — Required for multi-tenant tables
• Indexes — Required on frequently queried columns

Shared utilities (lib/**)

• No any types
• Parameterized queries — No string interpolation in SQL
• No N+1 patterns — Prefer batch fetches

Markdown / standards (standards/**, CLAUDE.md)

• Internal references — Must resolve (no broken links)
• Counts in CLAUDE.md — Must match actual files

GitHub Actions (*.yml in .github/workflows/)

• GITHUB_TOKEN events — Don't trigger other workflows; verify event chains will actually fire
• Permissions — Must be minimal (principle of least privilege)
• No secret exposure — Never echo $SECRET in logs
• Concurrency groups — Verify they use correct event payload fields
• Self-triggering workflows — Check for infinite loop potential

Prompt construction (any code that builds LLM prompts)

• Content separation — User-controlled content must be separated from system instructions
• Permission flags — Never use --dangerously-skip-permissions when only output is needed (no file access)
• Untrusted content — Validate and sanitize untrusted content boundaries

Shell scripts / CI steps

• Unquoted variables — Check for word splitting issues
• Error handling — Verify set -e and || fallbacks
• Git staging — Prefer git add -u or explicit files over git add -A

---

Severity levels

• Critical — Security vulnerabilities, data loss, auth bypass, any type, CLAUDE.md violations, missing RLS policies
• Warning — Performance issues, missing tests, over-engineering, unnecessary complexity
• Info — Style, naming, minor improvements

---

What NOT to flag

• Test files — Unless security-relevant
• Lock files — pnpm-lock.yaml, package-lock.json
• Auto-generated files
• Formatting-only changes
• .claude/ directory — Agent config, settings
• Build artifacts — Files in node_modules/, dist/, .next/

---

Output format

Respond with ONLY this JSON. No markdown fences, no explanation, no preamble.

{ "findings": [ { "file": "path/to/file.ts", "line": 42, "severity": "critical|warning|info", "rule": "short rule name", "message": "What's wrong and how to fix it" } ], "summary": "One-paragraph summary of the review", "approved": true }

Set approved: false if there are any Critical or Warning findings. Set approved: true only when there are zero Critical/Warning findings (Info-only is acceptable).

---

Review principles

1. Be direct — flag the issue, suggest the fix, move on
2. Flag over-engineering — unnecessary abstractions, premature generalization, feature flags for one-off changes
3. CLAUDE.md is law — any violation of project-specific CLAUDE.md rules is Critical
4. Security first — auth, injection, XSS, and OWASP top 10 are always Critical
5. Don't nitpick — if the code works, is readable, and follows the rules, approve it

---

How it works

This protocol powers automated PR review via a GitHub Action (.github/workflows/claude-review.yml):

1. Push a PR — The Action runs automatically on PR creation and updates
2. Claude reviews — Reads the diff + this protocol, outputs findings as JSON
3. Formal review posted — Findings become inline PR comments with approve/request_changes
4. Self-fix loop — If changes are requested, Claude auto-fixes and pushes (max 3 rounds)
5. Standards reflection — After a clean review, Claude analyzes patterns across recent PRs and suggests protocol updates

Addressing findings

• Agree — Fix the issue, push. The Action re-reviews automatically.
• Disagree — Reply to the inline comment with rationale. Admin can dismiss the review.
• Won't fix — Reply explaining why. The review can be dismissed by an admin.

Escalation

If findings can't be resolved after 3 auto-fix rounds:

1. Post comment — The Action flags manual review needed
2. Tag @Ameet — On the PR if a human decision is required
3. Add awaiting-input label — To the Linear issue if blocked

---

Pre-PR verification

Before pushing a PR, always run local verification:

pnpm type-check && pnpm lint && pnpm test:run && pnpm build

Don't rely on the reviewer to catch type errors or lint failures — those should be clean before the PR is created.

---

Rules

1. All PRs get reviewed — The GitHub Action reviews every PR automatically
2. Pre-PR verification required — Run type-check, lint, test, build before pushing
3. Address all findings — Don't merge with unresolved Critical/Warning findings unless an admin dismisses the review
4. No silent bypasses — If you dismiss a finding, explain why in the PR comment
5. Formal review blocks merge — The Action posts a formal GitHub review that serves as a required status check

---

Related standards

• standards/core/sdlc.md — Development lifecycle
• standards/core/linear-lifecycle.md — Linear statuses, labels, and comment protocol
• .github/workflows/claude-review.yml — GitHub Action that runs this protocol

---

Review Protocol v4.0 (Claude Code) — March 2026