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 (sequenced)
Run these in order. Do not move to the next gate until its pass condition is met (objective evidence, not internal certainty).
Read — Open the file and read the full enclosing function, method, or type (not only the diff hunk).
Pass: You can name the symbol and cite at least one line outside the changed lines that shows control flow, scope, or use relevant to the finding.
Reference (required before any “unused”, “dead code”, or “never called” claim) — Search the workspace for the identifier and for imports/exports that could reference it.
Pass: Recorded outcome: match count or list, or explicit “zero matches in repo” before asserting unused.
Upstream (required before “missing validation” or “missing error handling”) — Inspect the immediate caller, route/middleware, or documented framework behavior that might already enforce the rule.
Pass: One sentence naming where responsibility lives, or “checked caller + framework path; still missing” with which layer you checked.
Severity — Before assigning Critical or Major, map the issue to Severity Calibration and exclude style-only or Informational items.
Pass: Chosen label matches a bullet under that severity; otherwise downgrade, reclassify as Informational, or omit.
Submit — Each retained finding uses [FILE:LINE] plus a one-line proof; complete Before Submitting Review steps 1–7 for this review.
Pass: Every step satisfied or the finding was removed or downgraded.
The checklist below expands these gates by issue type; use both.
Pre-Report Verification Checklist
Before flagging ANY issue, verify:
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 assertion with ok check, NOT unsafe cast
data, ok := value.(UserData)
if !ok {
return fmt.Errorf("unexpected type: %T", value)
}
// Type switch is safe narrowing
switch v := value.(type) {
case User:
v.Name // Go 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)
Go
| Pattern |
Why It's Valid |
val, ok := map[key] |
Comma-ok idiom, standard for maps |
Returning error as last return value |
Go error handling convention |
defer for cleanup |
Correct resource management pattern |
| Short variable names in small scope |
Idiomatic Go (e.g., i, err, ctx) |
interface{} / any in generic code |
Valid for truly heterogeneous data |
Concurrency
| Pattern |
Why It's Valid |
| Unbuffered channel for synchronization |
Correct when goroutines must synchronize |
select with default |
Non-blocking channel operation, intentional |
sync.Once for initialization |
Thread-safe lazy init pattern |
context.Background() in main/tests |
Valid root context for top-level calls |
| Goroutine without explicit join |
Valid for fire-and-forget with proper lifecycle management |
Testing
| Pattern |
Why It's Valid |
| Table-driven tests |
Standard Go testing pattern |
t.Helper() in test utilities |
Correct for accurate error line reporting |
testify/assert alongside stdlib |
Common and acceptable in Go projects |
Test function names without _ |
TestFooBar is idiomatic Go |
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
Error Handling
Flag unchecked error ONLY IF ALL of these are true:
Goroutine Lifecycle
Flag goroutine leak ONLY IF:
Interface Design
Flag missing interface 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
3description: Mandatory verification steps for all code reviews to reduce false positives. Load this skill before reporting ANY code review findings.
4user-invocable: false
5metadata:
6 source: https://skillmd.com/skills/existential-birds/review-verification-protocol
7---
8
9# Review Verification Protocol
10
11This 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.
12
13## Anti-confabulation (gate 0 — runs before every other gate)
14
15Before 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:
16
17- For a code finding: the **file:line** plus the cited code, read freshly now (not recalled from earlier in the session).
18- For a diff review: the actual **diff hunk** under review.
19
20> 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.
21
22This 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.
23
24## Hard gates (sequenced)
25
26Run these **in order**. Do not move to the next gate until its **pass** condition is met (objective evidence, not internal certainty).
27
281. **Read** — Open the file and read the **full** enclosing function, method, or type (not only the diff hunk).
29 **Pass:** You can name the symbol and cite at least one line **outside** the changed lines that shows control flow, scope, or use relevant to the finding.
30
312. **Reference** (required before any “unused”, “dead code”, or “never called” claim) — Search the workspace for the identifier and for imports/exports that could reference it.
32 **Pass:** Recorded outcome: match count or list, or explicit “zero matches in repo” *before* asserting unused.
33
343. **Upstream** (required before “missing validation” or “missing error handling”) — Inspect the immediate caller, route/middleware, or documented framework behavior that might already enforce the rule.
35 **Pass:** One sentence naming where responsibility lives, or “checked caller + framework path; still missing” with which layer you checked.
36
374. **Severity** — Before assigning Critical or Major, map the issue to [Severity Calibration](#severity-calibration) and exclude style-only or [Informational](#informational-no-action-required) items.
38 **Pass:** Chosen label matches a bullet under that severity; otherwise downgrade, reclassify as Informational, or omit.
39
405. **Submit** — Each retained finding uses `[FILE:LINE]` plus a one-line proof; complete [Before Submitting Review](#before-submitting-review) steps 1–7 for this review.
41 **Pass:** Every step satisfied or the finding was removed or downgraded.
42
43The checklist below expands these gates by issue type; use both.
44
45## Pre-Report Verification Checklist
46
47Before flagging ANY issue, verify:
48
49- [ ] **I read the actual code** - Not just the diff context, but the full function/class
50- [ ] **I searched for usages** - Before claiming "unused", searched all references
51- [ ] **I checked surrounding code** - The issue may be handled elsewhere (guards, earlier checks)
52- [ ] **I verified syntax against current docs** - Framework syntax evolves (Tailwind v4, TS 5.x, React 19)
53- [ ] **I distinguished "wrong" from "different style"** - Both approaches may be valid
54- [ ] **I considered intentional design** - Checked comments, project conventions (e.g. AGENTS.md or CLAUDE.md), architectural context
55
56## Verification by Issue Type
57
58### "Unused Variable/Function"
59
60**Before flagging**, you MUST:
611. Search for ALL references in the codebase (grep/find)
622. Check if it's exported and used by external consumers
633. Check if it's used via reflection, decorators, or dynamic dispatch
644. Verify it's not a callback passed to a framework
65
66**Common false positives:**
67- State setters in React (may trigger re-renders even if value appears unused)
68- Variables used in templates/JSX
69- Exports used by consuming packages
70
71### "Missing Validation/Error Handling"
72
73**Before flagging**, you MUST:
741. Check if validation exists at a higher level (caller, middleware, route handler)
752. Check if the framework provides validation (Pydantic, Zod, TypeScript)
763. Verify the "missing" check isn't present in a different form
77
78**Common false positives:**
79- Framework already validates (FastAPI + Pydantic, React Hook Form)
80- Parent component validates before passing props
81- Error boundary catches at higher level
82
83### "Type Assertion/Unsafe Cast"
84
85**Before flagging**, you MUST:
861. Confirm it's actually an assertion, not an annotation
872. Check if the type is narrowed by runtime checks before the point
883. Verify if framework guarantees the type (loader data, form data)
89
90**Valid patterns often flagged incorrectly:**
91```go
92// Type assertion with ok check, NOT unsafe cast
93data, ok := value.(UserData)
94if !ok {
95 return fmt.Errorf("unexpected type: %T", value)
96}
97
98// Type switch is safe narrowing
99switch v := value.(type) {
100case User:
101 v.Name // Go knows this is User
102}
103```
104
105### "Potential Memory Leak/Race Condition"
106
107**Before flagging**, you MUST:
1081. Verify cleanup function is actually missing (not just in a different location)
1092. Check if AbortController signal is checked after awaits
1103. Confirm the component can actually unmount during the async operation
111
112**Common false positives:**
113- Cleanup exists in useEffect return
114- Signal is checked (code reviewer missed it)
115- Operation completes before unmount is possible
116
117### "Performance Issue"
118
119**Before flagging**, you MUST:
1201. Confirm the code runs frequently enough to matter (render vs click handler)
1212. Verify the optimization would have measurable impact
1223. Check if the framework already optimizes this (React compiler, memoization)
123
124**Do NOT flag:**
125- Functions created in click handlers (runs once per click)
126- Array methods on small arrays (< 100 items)
127- Object creation in event handlers
128
129## Severity Calibration
130
131### Critical (Block Merge)
132
133**ONLY use for:**
134- Security vulnerabilities (injection, auth bypass, data exposure)
135- Data corruption bugs
136- Crash-causing bugs in happy path
137- Breaking changes to public APIs
138
139### Major (Should Fix)
140
141**Use for:**
142- Logic bugs that affect functionality
143- Missing error handling that causes poor UX
144- Performance issues with measurable impact
145- Accessibility violations
146
147### Minor (Consider Fixing)
148
149**Use for:**
150- Code clarity improvements
151- Documentation gaps
152- Inconsistent style (within reason)
153- Non-critical test coverage gaps
154
155### Informational (No Action Required)
156
157**Use for:**
158- Improvements that require adding new dependencies or modules
159- Suggestions for net-new code that didn't exist in the codebase before (new modules, test suites, abstractions)
160- Architectural ideas for future consideration
161- Test infrastructure suggestions (new mock libraries, behaviour extraction)
162- Optimizations without measurable impact in the current context
163
164**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.
165
166### Do NOT Flag At All
167
168- Style preferences where both approaches are valid
169- Optimizations with no measurable benefit
170- Test code not meeting production standards (intentionally simpler)
171- Library/framework internal code (shadcn components, generated code)
172- Hypothetical issues that require unlikely conditions
173
174## Valid Patterns (Do NOT Flag)
175
176### Go
177
178| Pattern | Why It's Valid |
179|---------|----------------|
180| `val, ok := map[key]` | Comma-ok idiom, standard for maps |
181| Returning `error` as last return value | Go error handling convention |
182| `defer` for cleanup | Correct resource management pattern |
183| Short variable names in small scope | Idiomatic Go (e.g., `i`, `err`, `ctx`) |
184| `interface{}` / `any` in generic code | Valid for truly heterogeneous data |
185
186### Concurrency
187
188| Pattern | Why It's Valid |
189|---------|----------------|
190| Unbuffered channel for synchronization | Correct when goroutines must synchronize |
191| `select` with `default` | Non-blocking channel operation, intentional |
192| `sync.Once` for initialization | Thread-safe lazy init pattern |
193| `context.Background()` in main/tests | Valid root context for top-level calls |
194| Goroutine without explicit join | Valid for fire-and-forget with proper lifecycle management |
195
196### Testing
197
198| Pattern | Why It's Valid |
199|---------|----------------|
200| Table-driven tests | Standard Go testing pattern |
201| `t.Helper()` in test utilities | Correct for accurate error line reporting |
202| `testify/assert` alongside stdlib | Common and acceptable in Go projects |
203| Test function names without `_` | `TestFooBar` is idiomatic Go |
204
205### General
206
207| Pattern | Why It's Valid |
208|---------|----------------|
209| `+?` lazy quantifier in regex | Prevents over-matching, correct for many patterns |
210| Direct string concatenation | Simpler than template literals for simple cases |
211| Multiple returns in function | Can improve readability |
212| Comments explaining "why" | Better than no comments |
213
214## Context-Sensitive Rules
215
216### Error Handling
217
218Flag unchecked error **ONLY IF ALL** of these are true:
219- [ ] Error return is explicitly ignored (not `_`)
220- [ ] Function can return meaningful errors (not just `Close()`)
221- [ ] Not in test code or example code
222- [ ] Error would indicate a real problem, not a benign condition
223
224### Goroutine Lifecycle
225
226Flag goroutine leak **ONLY IF**:
227- [ ] No context cancellation controls the goroutine
228- [ ] No channel or WaitGroup provides shutdown signal
229- [ ] Goroutine can outlive its parent scope
230- [ ] Not a top-level server goroutine managed by the runtime
231
232### Interface Design
233
234Flag missing interface **ONLY IF**:
235- [ ] Concrete type is used across package boundaries
236- [ ] Testing requires mocking the dependency
237- [ ] Multiple implementations exist or are planned
238- [ ] Not a simple data struct (interfaces for behavior, not data)
239
240## Before Submitting Review
241
242Final verification:
2431. Re-read each finding and ask: "Did I verify this is actually an issue?"
2442. For each finding, can you point to the specific line that proves the issue exists?
2453. Would a domain expert agree this is a problem, or is it a style preference?
2464. Does fixing this provide real value, or is it busywork?
2475. Format every finding as: `[FILE:LINE] ISSUE_TITLE`
2486. 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.
2497. If this is a re-review: ONLY verify previous fixes. Do not introduce new findings.
250
251If uncertain about any finding, either:
252- Remove it from the review
253- Mark it as a question rather than an issue
254- Verify by reading more code context