Code Review

Code Review (Adversarial + Receiving)

Reference Files

Read only what's needed:

• references/review-order-and-checkpoints.md — review order, checkpoint discipline; load when starting a review that spans multiple files or needs a checkpointed pass
• references/code-review-heuristics.md — heuristics, pattern recognition, false-positive prevention; load when the diff is non-trivial or before reporting CLEAN (Zero-Finding Halt re-scan)
• references/security-review-checklist.md — security review checklist; load whenever the diff touches auth, input handling, network, secrets, or data access

Run ADVERSARIAL when producing findings on a diff; run RECEIVING when acting on findings someone else produced. The Code Smells catalog, AI-Generated Anti-Patterns, Metric Honesty Rule, and Deferred Findings handling below apply in both modes.

Mode: ADVERSARIAL REVIEW

Only report issues with confidence ≥80 — below that, a finding is more likely noise than signal, and noise burns the fix loop's time and trust. Do not inflate a score to smuggle a hunch through; a genuine security hunch goes to the Summary as an open question (see the Security exception under Confidence Scoring). Every finding states category, impact, and why it matters. Present a recommendation, not a menu. Be opinionated.

Signal quality rule: One finding with file:line evidence and a fix is worth more than ten generic observations. Never report a pattern without showing where it lives.

Two-Stage Review

Stage 1: Spec Compliance — Does the code do what the plan/spec asked? Check: phase exit criteria met, interfaces match plan's Consumes/Produces, no scope drift, no missing scenarios.

Stage 2: Code Quality — Is the code well-built? Check: correctness, performance, security, clarity, test coverage.

One-fact rule: On a consequential change, find the one fact the change is safe because of — a caller invariant, a lifecycle assumption, a data-shape contract at a boundary — and spend the review proving that fact instead of enumerating maybes. The fact is usually one a breakage grep will not surface. If you cannot prove it, the change is unreviewed; the maybes you listed do not change that.

Review Order

Top-down (spec → architecture → module → function → line) for first pass. Bottom-up (line → function → module) for detail pass. See references/review-order-and-checkpoints.md.

Severity Classification

Confidence Scoring

Security exception: a security-category finding below 80 confidence is NOT silently dropped. Surface it as an explicit open question in the review Summary (e.g., "Possible auth bypass at file:line — could not confirm exploit path"), not as a finding. The <80 floor drops everything else.

Parallel Review + Router Merge

When code-reviewer and failure-hunter run in parallel (BUILD workflow):

• code-reviewer (Assessment A): correctness, performance, spec compliance. Forms opinion WITHOUT seeing the hunter's scan.
• failure-hunter (Assessment B): silent failure scan using red-flags table. Does NOT see the reviewer's findings.
• Router-owned merge: after both complete, the router writes a merged findings summary into the workflow artifact before verifier handoff. Where both agree → high confidence. Where the hunter caught what the reviewer missed → keep. Where the hunter finding is a false positive → drop with reason. Contradictory verdicts: stricter verdict wins, logged in status_history.

Zero-Finding Halt

Zero findings on a non-trivial change → insufficient depth, not perfect code. Re-scan against heuristics and security checklist before reporting CLEAN.

Code Smells (Fowler Catalog)

Scan for these 16 named smells during review. Each is actionable — not a style preference. "Messy" is not actionable; "Mysterious Name" is. Each smell is a labelled heuristic and always a judgement call ("possible Feature Envy"), never a hard violation:

Repo standards override baseline: if the repo's documented conventions endorse something this baseline would flag, suppress the smell.

AI-Generated Anti-Patterns

Patterns commonly produced by AI code generation — flag with elevated priority:

• Over-eager memoization — useMemo/useCallback/React.memo wrapping everything without profiling evidence
• State duplication — same state stored in 2+ places, kept in sync manually (source of truth unclear)
• Sequential awaits — independent async calls awaited sequentially instead of Promise.all (latency multiplier)
• Over-fetching — fetching full objects (or more than the current view needs) when only one field is needed
• Premature abstraction / speculative generality — interface with single implementation "for future flexibility"
• Configurable when it should be constant — adding options/flags for flexibility nobody asked for
• Defensive coding for impossible states — null checks / over-engineered error handling for scenarios that can't happen (values typed non-nullable, internal code boundaries)
• Test mirrors implementation — test recomputes expected value using the same logic as the code (tautological test)
• Factory overkill — factory pattern for objects with no polymorphism
• Type assertions instead of type guards — as any/as Type instead of narrowing with a runtime check

Metric Honesty Rule

Never fabricate metrics. An LLM reading static source code cannot measure real-world LCP, INP, CLS, memory usage, or runtime performance.

• Can assess from code: algorithmic complexity (O(n) vs O(n²)), N+1 query patterns, obvious hot loops, missing indices
• Cannot assess from code: real-world latency, actual memory pressure, real INP/LCP/CLS values

State what you CAN verify from code. Tag anything else as "potential impact, not measured" — never invent numbers. Recommend specific tools (Lighthouse, profiler, benchmark suite) when runtime measurement is the real answer.

Deferred Findings (Not "Residual" — Already Wired)

Minor/Medium findings you don't fix in this pass are NOT dropped, but you do NOT need a separate file or a separate CONTRACT field for them. Just report them normally with severity and file:line in your output. The router already handles persistence: it reads your findings, appends every non-blocking Minor item to the workflow artifact's deferred_findings array (source, phase, finding, severity), and surfaces the accumulated list for explicit user triage at BUILD-DONE finishing. Nothing is silently discarded — this is automatic on the router side, not something you need to engineer in your response.

False Positive Prevention

Do NOT flag:

• Code that matches an explicit project convention (check patterns.md)
• Intentional simplification documented in the plan
• Test-only code using test patterns (mocks, fixtures, stubs)
• Performance "issues" without a measured bottleneck
• Style preferences that don't match project conventions

Mode: RECEIVING REVIEW

Discipline for acting on external/human review feedback (pasted PR comments, review notes, "can you change X"). This governs the MAIN session, not the internal reviewer→router→fix loop.

The 6-Step Loop

1. Read all feedback before responding to any item
2. Categorize each item: CRITICAL (must fix), IMPORTANT (should fix), MINOR (optional), REJECT (with reason)
3. Verify before agreeing — don't blindly accept. Check if the feedback is correct against the code.
4. Fix accepted items — CRITICAL first, then IMPORTANT
5. Push back on rejected items — with evidence, not opinion
6. Report — what was fixed, what was rejected and why

Verify Before Agreeing

Before implementing a suggestion, check:

• Does the issue actually exist in the code? (read the file:line)
• Is the suggested fix correct? (would it actually fix the issue?)
• Does the fix introduce new problems? (side effects, breaking changes)
• Is the suggestion based on a correct understanding of the code?

YAGNI-Grep Before Implementing

Before implementing a suggestion, grep the codebase for the pattern the reviewer claims is wrong. If the pattern is project convention (appears in many places, is in patterns.md), push back. If it's genuinely isolated, fix it.

When To Push Back

Known misbehaviors (external review surfaces)

Feedback arrives through gh or pasted text; both misbehave in known ways. Symptom → detection → fallback. Do not burn the fix loop retrying a misbehaving surface.

When the user explicitly requests repeated review cycles, name the iteration cap before the first cycle; at the cap, stop and report, resolving each remaining finding by fixing it or rebutting it with stated grounds. A single requested review starts no score loop.

Precedence

Pushing back ≠ refusing. You must either fix the issue or provide evidence why it's not an issue. "I prefer my way" is not a valid push-back. "This is project convention, see patterns.md line X" is valid.

Never perform agreement. "You're absolutely right!" commits you to unverified feedback. Verify before implementing: restate the technical requirement, push back with reasoning, or just do the work and show the fix.