Review Verification Protocol
This protocol MUST be followed before reporting any code review finding. Skipping these steps leads to false positives that waste developer time and erode trust in reviews.
Anti-confabulation (gate 0 — runs before every other gate)
Before issuing any verdict — flag, reject, or downgrade a finding — you MUST echo the exact artifact you are judging, quoted from a source you read in this turn:
- For a code finding: the file:line plus the cited code, read freshly now (not recalled from earlier in the session).
- For a diff review: the actual diff hunk under review.
The artifact is the only source of truth. Never infer what you are reviewing from the branch name, the working directory, surrounding files, or recollection. If your mental model differs from the freshly read source, the source wins. A verdict issued without a same-turn echo of its target is invalid — emit the echo first, or do not emit the verdict.
This gate exists because an LLM under contextual priming will confidently flag code that is not in the file. It runs before the hard gates below.
Hard gates (sequence)
Complete gates in order for each finding (or finding class). A gate passes only when the pass condition is objectively met—internal confidence is not enough.
- Read scope — PASS when: You cite the full enclosing unit you judged (e.g. function, method, or class): file path plus start–end line range or symbol name. Diff-only context without full-unit read fails this gate.
- Reference check (required for “unused”, “dead code”, “orphaned export”, “never called”) — PASS when: You ran a workspace-wide search for the symbol (ripgrep, IDE references, or
find_referencing_symbols-style lookup) and noted whether non-definition matches exist. If use may be dynamic (decorators, getattr, entry points, plugins), PASS when: you state that and name the registration or import path that could justify the symbol.
- Upstream / downstream (required for “missing validation”, “no error handling”, “race”, “leak”) — PASS when: You checked at least one of: caller, route/middleware, parent task, framework hook, or lifecycle (e.g. teardown, signal), and recorded whether responsibility already sits there.
- Evidence line — PASS when: The finding includes
[FILE:LINE] to the line that shows the issue (same requirement as Before Submitting Review).
If any gate fails, do not report the issue; gather evidence or drop it.
Pre-Report Verification Checklist
Before flagging ANY issue, verify (after Hard gates above):
Verification by Issue Type
"Unused Variable/Function"
Before flagging, you MUST:
- Search for ALL references in the codebase (grep/find)
- Check if it's exported and used by external consumers
- Check if it's used via reflection, decorators, or dynamic dispatch
- Verify it's not a callback passed to a framework
Common false positives:
- State setters in React (may trigger re-renders even if value appears unused)
- Variables used in templates/JSX
- Exports used by consuming packages
"Missing Validation/Error Handling"
Before flagging, you MUST:
- Check if validation exists at a higher level (caller, middleware, route handler)
- Check if the framework provides validation (Pydantic, Zod, TypeScript)
- Verify the "missing" check isn't present in a different form
Common false positives:
- Framework already validates (FastAPI + Pydantic, React Hook Form)
- Parent component validates before passing props
- Error boundary catches at higher level
"Type Assertion/Unsafe Cast"
Before flagging, you MUST:
- Confirm it's actually an assertion, not an annotation
- Check if the type is narrowed by runtime checks before the point
- Verify if framework guarantees the type (loader data, form data)
Valid patterns often flagged incorrectly:
# Type annotation, NOT cast
data: UserData = await load_user()
# Type narrowing with isinstance
if isinstance(data, User):
data.name # Mypy knows this is User
"Potential Memory Leak/Race Condition"
Before flagging, you MUST:
- Verify cleanup function is actually missing (not just in a different location)
- Check if AbortController signal is checked after awaits
- Confirm the component can actually unmount during the async operation
Common false positives:
- Cleanup exists in useEffect return
- Signal is checked (code reviewer missed it)
- Operation completes before unmount is possible
"Performance Issue"
Before flagging, you MUST:
- Confirm the code runs frequently enough to matter (render vs click handler)
- Verify the optimization would have measurable impact
- Check if the framework already optimizes this (React compiler, memoization)
Do NOT flag:
- Functions created in click handlers (runs once per click)
- Array methods on small arrays (< 100 items)
- Object creation in event handlers
Severity Calibration
Critical (Block Merge)
ONLY use for:
- Security vulnerabilities (injection, auth bypass, data exposure)
- Data corruption bugs
- Crash-causing bugs in happy path
- Breaking changes to public APIs
Major (Should Fix)
Use for:
- Logic bugs that affect functionality
- Missing error handling that causes poor UX
- Performance issues with measurable impact
- Accessibility violations
Minor (Consider Fixing)
Use for:
- Code clarity improvements
- Documentation gaps
- Inconsistent style (within reason)
- Non-critical test coverage gaps
Informational (No Action Required)
Use for:
- Improvements that require adding new dependencies or modules
- Suggestions for net-new code that didn't exist in the codebase before (new modules, test suites, abstractions)
- Architectural ideas for future consideration
- Test infrastructure suggestions (new mock libraries, behaviour extraction)
- Optimizations without measurable impact in the current context
These are NOT review blockers. They should be noted for the author's awareness but must not appear in the actionable issue count. The Verdict should ignore informational items entirely.
Do NOT Flag At All
- Style preferences where both approaches are valid
- Optimizations with no measurable benefit
- Test code not meeting production standards (intentionally simpler)
- Library/framework internal code (shadcn components, generated code)
- Hypothetical issues that require unlikely conditions
Valid Patterns (Do NOT Flag)
Python
| Pattern |
Why It's Valid |
dict.get(key, []) |
Returns default for missing keys, not error suppression |
Optional[T] return type |
Standard way to express nullable in Python typing |
assert in test code |
pytest uses assertions, not try/except |
| Type annotation on variable |
Not a cast, just a hint for type checkers |
typing.cast() with prior validation |
Valid after runtime check confirms type |
FastAPI
| Pattern |
Why It's Valid |
Depends() without explicit type |
FastAPI infers dependency type from function signature |
async def endpoint without await |
May use sync DB calls or simple returns |
| Response model different from DB model |
Separation of concerns between API and persistence |
BackgroundTasks parameter |
Valid for fire-and-forget operations |
Direct request.state access |
Standard pattern for middleware-injected data |
Testing
| Pattern |
Why It's Valid |
assert without message |
pytest rewrites assertions to show detailed diffs |
@pytest.fixture without explicit scope |
Default function scope is correct for most fixtures |
monkeypatch over unittest.mock |
Simpler API, pytest-native |
| Fixture returning mutable state |
Each test gets fresh fixture invocation by default |
General
| Pattern |
Why It's Valid |
+? lazy quantifier in regex |
Prevents over-matching, correct for many patterns |
| Direct string concatenation |
Simpler than template literals for simple cases |
| Multiple returns in function |
Can improve readability |
| Comments explaining "why" |
Better than no comments |
Context-Sensitive Rules
Type Annotations
Flag missing type annotation ONLY IF ALL of these are true:
Exception Handling
Flag bare except ONLY IF:
Error Handling
Flag missing try/except ONLY IF:
Before Submitting Review
Final verification:
- Re-read each finding and ask: "Did I verify this is actually an issue?"
- For each finding, can you point to the specific line that proves the issue exists?
- Would a domain expert agree this is a problem, or is it a style preference?
- Does fixing this provide real value, or is it busywork?
- Format every finding as:
[FILE:LINE] ISSUE_TITLE
- For each finding, ask: "Does this fix existing code, or does it request entirely new code that didn't exist before?" If the latter, downgrade to Informational.
- If this is a re-review: ONLY verify previous fixes. Do not introduce new findings.
If uncertain about any finding, either:
- Remove it from the review
- Mark it as a question rather than an issue
- Verify by reading more code context
1---2name: review-verification-protocol-63description: Mandatory verification steps for all code reviews to reduce false positives. Load this skill before reporting ANY code review findings.4---56# Review Verification Protocol78This protocol MUST be followed before reporting any code review finding. Skipping these steps leads to false positives that waste developer time and erode trust in reviews.910## Anti-confabulation (gate 0 — runs before every other gate)1112Before issuing **any** verdict — flag, reject, or downgrade a finding — you MUST echo the exact artifact you are judging, quoted from a source you read in **this** turn:1314- For a code finding: the **file:line** plus the cited code, read freshly now (not recalled from earlier in the session).15- For a diff review: the actual **diff hunk** under review.1617> The artifact is the only source of truth. **Never** infer what you are reviewing from the branch name, the working directory, surrounding files, or recollection. If your mental model differs from the freshly read source, **the source wins.** A verdict issued without a same-turn echo of its target is invalid — emit the echo first, or do not emit the verdict.1819This gate exists because an LLM under contextual priming will confidently flag code that is not in the file. It runs **before** the hard gates below.2021## Hard gates (sequence)2223Complete gates **in order** for each finding (or finding class). A gate **passes** only when the pass condition is objectively met—internal confidence is not enough.24251. **Read scope** — **PASS when:** You cite the **full** enclosing unit you judged (e.g. function, method, or class): file path plus **start–end line range** or symbol name. Diff-only context without full-unit read **fails** this gate.262. **Reference check** (required for “unused”, “dead code”, “orphaned export”, “never called”) — **PASS when:** You ran a **workspace-wide search** for the symbol (ripgrep, IDE references, or `find_referencing_symbols`-style lookup) and noted whether non-definition matches exist. If use may be dynamic (decorators, `getattr`, entry points, plugins), **PASS when:** you state that and name the registration or import path that could justify the symbol.273. **Upstream / downstream** (required for “missing validation”, “no error handling”, “race”, “leak”) — **PASS when:** You checked at least one of: caller, route/middleware, parent task, framework hook, or lifecycle (e.g. teardown, signal), and recorded whether responsibility already sits there.284. **Evidence line** — **PASS when:** The finding includes **`[FILE:LINE]`** to the line that **shows** the issue (same requirement as *Before Submitting Review*).2930If any gate fails, **do not** report the issue; gather evidence or drop it.3132## Pre-Report Verification Checklist3334Before flagging ANY issue, verify (after **Hard gates** above):3536- [ ] **I read the actual code** - Not just the diff context, but the full function/class37- [ ] **I searched for usages** - Before claiming "unused", searched all references38- [ ] **I checked surrounding code** - The issue may be handled elsewhere (guards, earlier checks)39- [ ] **I verified syntax against current docs** - Framework syntax evolves (Tailwind v4, TS 5.x, React 19)40- [ ] **I distinguished "wrong" from "different style"** - Both approaches may be valid41- [ ] **I considered intentional design** - Checked comments, project conventions (e.g. AGENTS.md or CLAUDE.md), architectural context4243## Verification by Issue Type4445### "Unused Variable/Function"4647**Before flagging**, you MUST:481. Search for ALL references in the codebase (grep/find)492. Check if it's exported and used by external consumers503. Check if it's used via reflection, decorators, or dynamic dispatch514. Verify it's not a callback passed to a framework5253**Common false positives:**54- State setters in React (may trigger re-renders even if value appears unused)55- Variables used in templates/JSX56- Exports used by consuming packages5758### "Missing Validation/Error Handling"5960**Before flagging**, you MUST:611. Check if validation exists at a higher level (caller, middleware, route handler)622. Check if the framework provides validation (Pydantic, Zod, TypeScript)633. Verify the "missing" check isn't present in a different form6465**Common false positives:**66- Framework already validates (FastAPI + Pydantic, React Hook Form)67- Parent component validates before passing props68- Error boundary catches at higher level6970### "Type Assertion/Unsafe Cast"7172**Before flagging**, you MUST:731. Confirm it's actually an assertion, not an annotation742. Check if the type is narrowed by runtime checks before the point753. Verify if framework guarantees the type (loader data, form data)7677**Valid patterns often flagged incorrectly:**78```python79# Type annotation, NOT cast80data: UserData = await load_user()8182# Type narrowing with isinstance83if isinstance(data, User):84 data.name # Mypy knows this is User85```8687### "Potential Memory Leak/Race Condition"8889**Before flagging**, you MUST:901. Verify cleanup function is actually missing (not just in a different location)912. Check if AbortController signal is checked after awaits923. Confirm the component can actually unmount during the async operation9394**Common false positives:**95- Cleanup exists in useEffect return96- Signal is checked (code reviewer missed it)97- Operation completes before unmount is possible9899### "Performance Issue"100101**Before flagging**, you MUST:1021. Confirm the code runs frequently enough to matter (render vs click handler)1032. Verify the optimization would have measurable impact1043. Check if the framework already optimizes this (React compiler, memoization)105106**Do NOT flag:**107- Functions created in click handlers (runs once per click)108- Array methods on small arrays (< 100 items)109- Object creation in event handlers110111## Severity Calibration112113### Critical (Block Merge)114115**ONLY use for:**116- Security vulnerabilities (injection, auth bypass, data exposure)117- Data corruption bugs118- Crash-causing bugs in happy path119- Breaking changes to public APIs120121### Major (Should Fix)122123**Use for:**124- Logic bugs that affect functionality125- Missing error handling that causes poor UX126- Performance issues with measurable impact127- Accessibility violations128129### Minor (Consider Fixing)130131**Use for:**132- Code clarity improvements133- Documentation gaps134- Inconsistent style (within reason)135- Non-critical test coverage gaps136137### Informational (No Action Required)138139**Use for:**140- Improvements that require adding new dependencies or modules141- Suggestions for net-new code that didn't exist in the codebase before (new modules, test suites, abstractions)142- Architectural ideas for future consideration143- Test infrastructure suggestions (new mock libraries, behaviour extraction)144- Optimizations without measurable impact in the current context145146**These are NOT review blockers.** They should be noted for the author's awareness but must not appear in the actionable issue count. The Verdict should ignore informational items entirely.147148### Do NOT Flag At All149150- Style preferences where both approaches are valid151- Optimizations with no measurable benefit152- Test code not meeting production standards (intentionally simpler)153- Library/framework internal code (shadcn components, generated code)154- Hypothetical issues that require unlikely conditions155156## Valid Patterns (Do NOT Flag)157158### Python159160| Pattern | Why It's Valid |161|---------|----------------|162| `dict.get(key, [])` | Returns default for missing keys, not error suppression |163| `Optional[T]` return type | Standard way to express nullable in Python typing |164| `assert` in test code | pytest uses assertions, not try/except |165| Type annotation on variable | Not a cast, just a hint for type checkers |166| `typing.cast()` with prior validation | Valid after runtime check confirms type |167168### FastAPI169170| Pattern | Why It's Valid |171|---------|----------------|172| `Depends()` without explicit type | FastAPI infers dependency type from function signature |173| `async def` endpoint without await | May use sync DB calls or simple returns |174| Response model different from DB model | Separation of concerns between API and persistence |175| `BackgroundTasks` parameter | Valid for fire-and-forget operations |176| Direct `request.state` access | Standard pattern for middleware-injected data |177178### Testing179180| Pattern | Why It's Valid |181|---------|----------------|182| `assert` without message | pytest rewrites assertions to show detailed diffs |183| `@pytest.fixture` without explicit scope | Default `function` scope is correct for most fixtures |184| `monkeypatch` over `unittest.mock` | Simpler API, pytest-native |185| Fixture returning mutable state | Each test gets fresh fixture invocation by default |186187### General188189| Pattern | Why It's Valid |190|---------|----------------|191| `+?` lazy quantifier in regex | Prevents over-matching, correct for many patterns |192| Direct string concatenation | Simpler than template literals for simple cases |193| Multiple returns in function | Can improve readability |194| Comments explaining "why" | Better than no comments |195196## Context-Sensitive Rules197198### Type Annotations199200Flag missing type annotation **ONLY IF ALL** of these are true:201- [ ] Function is public API (not prefixed with `_`)202- [ ] Types are not obvious from context (e.g., `x = 5` is clearly `int`)203- [ ] Not a test function or fixture204- [ ] Codebase has existing typing conventions205206### Exception Handling207208Flag bare `except` **ONLY IF**:209- [ ] Not in a top-level error boundary / middleware210- [ ] The caught exception is actually swallowed (not logged/re-raised)211- [ ] Specific exception types are known and available212- [ ] Not in cleanup/teardown code where any error should be caught213214### Error Handling215216Flag missing try/except **ONLY IF**:217- [ ] No middleware or error handler catches this at a higher level218- [ ] The framework doesn't handle errors (FastAPI exception handlers)219- [ ] The error would cause a crash, not just a failed operation220- [ ] User needs specific feedback for this error type221222## Before Submitting Review223224Final verification:2251. Re-read each finding and ask: "Did I verify this is actually an issue?"2262. For each finding, can you point to the specific line that proves the issue exists?2273. Would a domain expert agree this is a problem, or is it a style preference?2284. Does fixing this provide real value, or is it busywork?2295. Format every finding as: `[FILE:LINE] ISSUE_TITLE`2306. For each finding, ask: "Does this fix existing code, or does it request entirely new code that didn't exist before?" If the latter, downgrade to Informational.2317. If this is a re-review: ONLY verify previous fixes. Do not introduce new findings.232233If uncertain about any finding, either:234- Remove it from the review235- Mark it as a question rather than an issue236- Verify by reading more code context