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, property, 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/@objc/#selector/SPM symbols 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, parent View / coordinator / ViewModel, app or scene delegate pipeline, 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/ripgrep or IDE references)
- Check if it's
public/open and used by other modules or targets (SPM, app extensions)
- Check if it's used via Objective-C runtime,
#selector, key paths, or dynamic dispatch
- Verify it's not a delegate/callback the framework invokes by contract
Common false positives:
- SwiftUI state (
@State, @Binding, @Observable) that drives updates even when the binding looks “unused” in one branch
- Symbols referenced from Interface Builder, asset catalogs,
#Preview, tests, or other targets
@objc, #selector, or dynamic dispatch to a symbol search may not show as plain call sites
"Missing Validation/Error Handling"
Before flagging, you MUST:
- Check if validation exists at a higher level (caller, parent
ViewModel, coordinator, app/scene delegate)
- Check if the framework or type already enforces invariants (
Codable, property wrappers, URLSession APIs)
- Verify the "missing" check isn't present in a different form (e.g.
Result, async error path, user-facing alert elsewhere)
Common false positives:
- Parent or router validates before this layer runs
- Errors surface via delegate, Combine pipeline, or unified logging — not every call needs local
do/catch
- User-visible failure is handled in a single choke point (e.g. one alert coordinator)
"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 or prior step guarantees the type (parsed JSON, Core Data fetch, async loader result)
Valid patterns often flagged incorrectly:
// Type annotation, NOT forced unwrap
let data: UserData = await loader()
// Type narrowing makes this safe
if let user = data as? User {
user.name // Swift knows this is User
}
"Potential Memory Leak/Race Condition"
Before flagging, you MUST:
- Verify cleanup is actually missing (not
deinit, onDisappear, cancel(), or store teardown elsewhere)
- Check if
Task cancellation, AsyncSequence termination, or Combine subscription disposal is handled after awaits
- Confirm the view or object can actually deallocate or invalidate during the async operation
Common false positives:
[weak self] or [unowned self] already used where needed
Task is cancelled when the view disappears (reviewer missed the link)
- Operation finishes before lifetime issues are possible
"Performance Issue"
Before flagging, you MUST:
- Confirm the code runs frequently enough to matter (SwiftUI body / layout vs one-off action)
- Verify the optimization would have measurable impact (Instruments or clear hot path)
- Check if the framework already mitigates this (SwiftUI diffing, lazy containers,
@Observable granularity)
Do NOT flag:
- Allocations in infrequent actions (sheet presentation, button tap)
- Linear work on small collections without evidence of scale
- Short-lived value types in event handlers when profiling doesn’t justify change
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 (generated Swift, SPM vendored sources, Xcode-generated)
- Hypothetical issues that require unlikely conditions
Valid Patterns (Do NOT Flag)
Swift
| Pattern |
Why It's Valid |
guard let early return |
Standard Swift pattern for unwrapping, not excessive nesting |
weak self in closures |
Required for breaking retain cycles, not unnecessary |
@State / @Binding property wrappers |
SwiftUI state management primitives |
Optional chaining (foo?.bar?.baz) |
Safe access pattern, not error suppression |
as? conditional cast |
Safer than force cast, correct for type narrowing |
SwiftUI
| Pattern |
Why It's Valid |
@StateObject in parent, @ObservedObject in child |
Correct ownership pattern |
| View body computed property without caching |
SwiftUI manages re-rendering efficiently |
AnyView for heterogeneous lists |
Valid when @ViewBuilder or generics aren't practical |
EnvironmentObject injection |
Standard SwiftUI dependency injection |
PreferenceKey for child-to-parent data |
Correct alternative to callbacks for layout data |
Testing
| Pattern |
Why It's Valid |
XCTAssertEqual without custom message |
Default messages are often sufficient |
async let in test methods |
Valid for concurrent test setup |
@MainActor test classes |
Required when testing UI-bound code |
| Mock objects without protocol conformance |
Simple test doubles are acceptable |
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
Swift Optionals
Flag force unwrap (!) ONLY IF ALL of these are true:
View Body Complexity
Flag complex View body ONLY IF:
Error Handling
Flag missing do/catch 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-73description: Mandatory verification steps for all code reviews to reduce false positives. Load this skill before reporting ANY code review findings.4user-invocable: false5metadata:6 source: https://skillmd.com/skills/existential-birds/review-verification-protocol-77---89# Review Verification Protocol1011This 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.1213## Anti-confabulation (gate 0 — runs before every other gate)1415Before 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:1617- 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.1920> 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.2122This 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.2324## Hard gates (sequenced)2526Run these **in order**. Do not move to the next gate until its **pass** condition is met (objective evidence, not internal certainty).27281. **Read** — Open the file and read the **full** enclosing function, method, property, 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.30312. **Reference** (required before any “unused”, “dead code”, or “never called” claim) — Search the workspace for the identifier and for imports/`@objc`/`#selector`/SPM symbols that could reference it. 32 **Pass:** Recorded outcome: match count or list, or explicit “zero matches in repo” *before* asserting unused.33343. **Upstream** (required before “missing validation” or “missing error handling”) — Inspect the immediate caller, parent `View` / coordinator / `ViewModel`, app or scene delegate pipeline, 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.36374. **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.39405. **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.4243The checklist below expands these gates by issue type; use both.4445## Pre-Report Verification Checklist4647Before flagging ANY issue, verify:4849- [ ] **I read the actual code** - Not just the diff context, but the full function/class50- [ ] **I searched for usages** - Before claiming "unused", searched all references51- [ ] **I checked surrounding code** - The issue may be handled elsewhere (guards, earlier checks)52- [ ] **I verified syntax against current docs** - Apple APIs evolve (Swift concurrency, SwiftUI lifecycle, new SDKs); when syntax may have changed, confirm against current Apple documentation53- [ ] **I distinguished "wrong" from "different style"** - Both approaches may be valid54- [ ] **I considered intentional design** - Checked comments, project conventions (e.g. AGENTS.md or CLAUDE.md), architectural context5556## Verification by Issue Type5758### "Unused Variable/Function"5960**Before flagging**, you MUST:611. Search for ALL references in the codebase (grep/ripgrep or IDE references)622. Check if it's `public`/`open` and used by other modules or targets (SPM, app extensions)633. Check if it's used via Objective-C runtime, `#selector`, key paths, or dynamic dispatch644. Verify it's not a delegate/callback the framework invokes by contract6566**Common false positives:**67- SwiftUI state (`@State`, `@Binding`, `@Observable`) that drives updates even when the binding looks “unused” in one branch68- Symbols referenced from Interface Builder, asset catalogs, `#Preview`, tests, or other targets69- `@objc`, `#selector`, or dynamic dispatch to a symbol search may not show as plain call sites7071### "Missing Validation/Error Handling"7273**Before flagging**, you MUST:741. Check if validation exists at a higher level (caller, parent `ViewModel`, coordinator, app/scene delegate)752. Check if the framework or type already enforces invariants (`Codable`, property wrappers, `URLSession` APIs)763. Verify the "missing" check isn't present in a different form (e.g. `Result`, async error path, user-facing alert elsewhere)7778**Common false positives:**79- Parent or router validates before this layer runs80- Errors surface via delegate, Combine pipeline, or unified logging — not every call needs local `do/catch`81- User-visible failure is handled in a single choke point (e.g. one alert coordinator)8283### "Type Assertion/Unsafe Cast"8485**Before flagging**, you MUST:861. Confirm it's actually an assertion, not an annotation872. Check if the type is narrowed by runtime checks before the point883. Verify if framework or prior step guarantees the type (parsed JSON, Core Data fetch, async loader result)8990**Valid patterns often flagged incorrectly:**91```swift92// Type annotation, NOT forced unwrap93let data: UserData = await loader()9495// Type narrowing makes this safe96if let user = data as? User {97 user.name // Swift knows this is User98}99```100101### "Potential Memory Leak/Race Condition"102103**Before flagging**, you MUST:1041. Verify cleanup is actually missing (not `deinit`, `onDisappear`, `cancel()`, or `store` teardown elsewhere)1052. Check if `Task` cancellation, `AsyncSequence` termination, or Combine subscription disposal is handled after awaits1063. Confirm the view or object can actually deallocate or invalidate during the async operation107108**Common false positives:**109- `[weak self]` or `[unowned self]` already used where needed110- `Task` is cancelled when the view disappears (reviewer missed the link)111- Operation finishes before lifetime issues are possible112113### "Performance Issue"114115**Before flagging**, you MUST:1161. Confirm the code runs frequently enough to matter (SwiftUI body / layout vs one-off action)1172. Verify the optimization would have measurable impact (Instruments or clear hot path)1183. Check if the framework already mitigates this (SwiftUI diffing, lazy containers, `@Observable` granularity)119120**Do NOT flag:**121- Allocations in infrequent actions (sheet presentation, button tap)122- Linear work on small collections without evidence of scale123- Short-lived value types in event handlers when profiling doesn’t justify change124125## Severity Calibration126127### Critical (Block Merge)128129**ONLY use for:**130- Security vulnerabilities (injection, auth bypass, data exposure)131- Data corruption bugs132- Crash-causing bugs in happy path133- Breaking changes to public APIs134135### Major (Should Fix)136137**Use for:**138- Logic bugs that affect functionality139- Missing error handling that causes poor UX140- Performance issues with measurable impact141- Accessibility violations142143### Minor (Consider Fixing)144145**Use for:**146- Code clarity improvements147- Documentation gaps148- Inconsistent style (within reason)149- Non-critical test coverage gaps150151### Informational (No Action Required)152153**Use for:**154- Improvements that require adding new dependencies or modules155- Suggestions for net-new code that didn't exist in the codebase before (new modules, test suites, abstractions)156- Architectural ideas for future consideration157- Test infrastructure suggestions (new mock libraries, behaviour extraction)158- Optimizations without measurable impact in the current context159160**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.161162### Do NOT Flag At All163164- Style preferences where both approaches are valid165- Optimizations with no measurable benefit166- Test code not meeting production standards (intentionally simpler)167- Library/framework internal code (generated Swift, SPM vendored sources, Xcode-generated)168- Hypothetical issues that require unlikely conditions169170## Valid Patterns (Do NOT Flag)171172### Swift173174| Pattern | Why It's Valid |175|---------|----------------|176| `guard let` early return | Standard Swift pattern for unwrapping, not excessive nesting |177| `weak self` in closures | Required for breaking retain cycles, not unnecessary |178| `@State` / `@Binding` property wrappers | SwiftUI state management primitives |179| Optional chaining (`foo?.bar?.baz`) | Safe access pattern, not error suppression |180| `as?` conditional cast | Safer than force cast, correct for type narrowing |181182### SwiftUI183184| Pattern | Why It's Valid |185|---------|----------------|186| `@StateObject` in parent, `@ObservedObject` in child | Correct ownership pattern |187| View body computed property without caching | SwiftUI manages re-rendering efficiently |188| `AnyView` for heterogeneous lists | Valid when `@ViewBuilder` or generics aren't practical |189| `EnvironmentObject` injection | Standard SwiftUI dependency injection |190| `PreferenceKey` for child-to-parent data | Correct alternative to callbacks for layout data |191192### Testing193194| Pattern | Why It's Valid |195|---------|----------------|196| `XCTAssertEqual` without custom message | Default messages are often sufficient |197| `async let` in test methods | Valid for concurrent test setup |198| `@MainActor` test classes | Required when testing UI-bound code |199| Mock objects without protocol conformance | Simple test doubles are acceptable |200201### General202203| Pattern | Why It's Valid |204|---------|----------------|205| `+?` lazy quantifier in regex | Prevents over-matching, correct for many patterns |206| Direct string concatenation | Simpler than template literals for simple cases |207| Multiple returns in function | Can improve readability |208| Comments explaining "why" | Better than no comments |209210## Context-Sensitive Rules211212### Swift Optionals213214Flag force unwrap (`!`) **ONLY IF ALL** of these are true:215- [ ] Value CAN actually be nil at runtime216- [ ] No prior `guard let` or `if let` protects the access217- [ ] Not in test code or prototype218- [ ] Not a `@IBOutlet` (which is conventionally force-unwrapped)219220### View Body Complexity221222Flag complex View body **ONLY IF**:223- [ ] Body exceeds 40 lines224- [ ] Nested components could be extracted without losing clarity225- [ ] Performance profiling shows actual rendering issues226- [ ] Not a leaf view with minimal composition227228### Error Handling229230Flag missing `do/catch` **ONLY IF**:231- [ ] No `Result` type wraps the throwing call232- [ ] No higher-level error handler catches this233- [ ] The error would cause a crash, not just a failed operation234- [ ] User needs specific feedback for this error type235236## Before Submitting Review237238Final verification:2391. Re-read each finding and ask: "Did I verify this is actually an issue?"2402. For each finding, can you point to the specific line that proves the issue exists?2413. Would a domain expert agree this is a problem, or is it a style preference?2424. Does fixing this provide real value, or is it busywork?2435. Format every finding as: `[FILE:LINE] ISSUE_TITLE`2446. 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.2457. If this is a re-review: ONLY verify previous fixes. Do not introduce new findings.246247If uncertain about any finding, either:248- Remove it from the review249- Mark it as a question rather than an issue250- Verify by reading more code context