Review Changes

Review changed code with explicit severity and confidence.

Process

Follow this sequence to produce a thorough, efficient review:

Understand intent. Read the PR description, commit messages, and any linked issues. Know what the change is trying to do before judging how well it does it.
Scan for scope. Skim the full diff to understand what areas it touches — files, modules, layers. This determines which lenses to load.
Select lenses. Use the table below to pick the relevant reviewer lenses. Load only what applies; skip the rest.
Review each file. Walk the diff file by file. Pull in adjacent unchanged code only when it is necessary to explain impact or verify whether an issue is real.
Synthesize. After the file-by-file pass, look for groupable root causes. Multiple symptoms in different files may share one underlying problem — present those as a grouped finding instead of separate entries.
Write up findings using the format and presentation rules below.
Produce a verdict in the summary section.

Lens Selection

Use this table to decide which lenses to load based on what the diff touches. Readability is always worth loading as a baseline.

If the diff touches…	Load these lenses
User input, auth, networking, secrets	Security
Public APIs, module boundaries	Architecture
CLI output, error messages, defaults	UX
Hot paths, loops, queries, large data	Performance
New features, bug fixes, branching logic	Tests
Docs, README, docstrings, examples	Documentation
Existing GitHub review comments	GitHub review threads
Anything else	Readability (always on)

Scope

Focus on the changed code and behavior introduced by the diff. Pull in adjacent unchanged code only when it is necessary to explain impact or verify whether an issue is real.

Rating

Rate impact separately from certainty.

Severity	Emoji	Meaning
P1	🔴	Critical: security flaws, data loss, crashes, or release blockers
P2	🟠	Important: broken features, serious regressions, or major correctness gaps
P3	🟡	Should fix: smaller bugs, coverage gaps, or usability problems
P4	⚪	Nice to have: low-impact polish or consistency issues

Report findings with confidence ≥ 80. For findings between 60–79, mention them briefly in a "Lower-confidence observations" section at the end, clearly marked as uncertain. Below 60, drop them entirely.

Finding Format

Each finding must include:

File: location with line numbers
Issue: one-sentence problem statement
Reasoning: why the behavior is wrong or risky
Evidence: concrete code, types, behavior, or reviewer comment
Suggestion: a specific fix or next action

Use this header format:

### 🟠 P2 · 🛡️ SEC-1 · Missing authorization check · 92%

Use these prefixes:

SEC: security
ARC: architecture
TST: tests
UXD: user experience
RDY: readability
DOC: documentation
PRF: performance
GIT: GitHub review feedback

Use these category icons when presenting a review summary:

Prefix	Emoji	Category
`SEC`	🛡️	security
`ARC`	🏗️	architecture
`TST`	🧪	tests
`UXD`	🎨	user experience
`RDY`	👁️	readability
`DOC`	📖	documentation
`PRF`	🚀	performance
`GIT`	💬	GitHub feedback
`GRP`	📦	grouped findings

Review Presentation

When summarizing findings for a human, present them in an emoji-led format:

{severity_emoji} {severity} · {category_emoji} {id} · {title} ({confidence}%) · {file}:{line}

Examples:

🔴 P1 · 🛡️ SEC-1 · SQL injection vulnerability (95%) · src/db.ts:45
🟠 P2 · 🏗️ ARC-1 · Circular dependency (88%) · src/modules/a.ts:12
🟡 P3 · 🧪 TST-2 · Missing edge case test (82%) · tests/api.test.ts:78

For GitHub findings, append the author when available:

🟠 P2 · 💬 GIT-1 · Consider using constants (90%) · src/config.ts:23 (@reviewer)

If multiple findings collapse into one root cause, you may present a grouped summary:

╭──────────────────────────────────────────────────────────────────────────╮
│ 🟠 P2 · 📦 GRP-1 · Inconsistent error handling (3 findings)              │
╰┬─────────────────────────────────────────────────────────────────────────╯
 ├─ 🟠 P2 · 👁️ RDY-1 · Missing error check (85%) · src/api.ts:23
 ├─ 🟡 P3 · 👁️ RDY-2 · Silent failure (82%) · src/api.ts:45
 └─ 🟡 P3 · 👁️ RDY-3 · No error logging (80%) · src/api.ts:67

Sort summaries by severity first, then by confidence. Include a legend when the review is long enough that readers would benefit from one.

Actionability

Prefer findings that are specific, reproducible, and cheap enough to act on in the current change. Cap output at roughly 8 findings for a normal-sized diff — prioritize ruthlessly rather than dumping everything.

Avoid:

Speculative concerns without concrete evidence in the diff.
Style preferences that linters or formatters already enforce.
Suggesting rewrites of working code unless there's a clear maintainability or correctness risk.
Flagging pre-existing TODO/FIXME comments that aren't part of this change.
Issues outside the review scope (e.g., unrelated files, hypothetical future requirements).

Summary

End every review with:

A bordered summary that includes only the severity counts.
A verdict label.
One to three short, action-oriented bullets that explain the TL;DR.

Use this format:

╭───────────────────────────────────────────╮
│ 🔴 P1: 0   🟠 P2: 1   🟡 P3: 2   ⚪ P4: 1 │
╰───────────────────────────────────────────╯
**Needs changes**:
- Fix the inconsistent error handling in `src/api.ts`, `src/jobs.ts`, and `src/worker.ts`.
- Add a retry-path test so this regression does not recur.
- Merge after the P2 issue is resolved.

The verdict label should be one of:

Ship it: no findings, or only P4 nits.
Ship with fixes: P3 or below; nothing blocking.
Needs changes: at least one P2 that should be resolved before merge.
Blocked: at least one P1; do not merge.

Write the bullets as a call to action. Prefer concrete next steps over vague summaries.

Good:

Add the missing authorization check in the admin route.
Update the docs to mention the new default timeout.
Merge after the flaky retry test is fixed.