/code-verification

name: code-verification
description: "Use after every code change, after writing tests, or before marking a task complete, and when the user says verify, quality gate, or audit code. Runs a 7-category mechanical check for TDZ, import, dead code, and mock leakage bugs."
domain: engineering

Code Verification Skill

A systematic post-implementation verification workflow that catches the bugs AI coding assistants most commonly introduce. This is NOT a code review for style or architecture — it is a mechanical correctness checklist that catches structural errors (TDZ, imports, dead code, mock leakage, CSS orphans, React anti-patterns) that humans and AI both miss during implementation.

When to Use

• **After every code change** (1-2 files changed -> run immediately)
• **After a multi-file feature** (run on all changed files in one pass)
• **After writing/modifying tests** (switch to Test Verification mode)
• **Before marking any task complete** (final gate)
• **When a subagent completes work** (verify their output)
• **When user says**: "verify", "check quality", "audit code", "run verification", "quality gate", "pre-commit check"

Quick Start

1. Identify changed files (git diff --name-only or manual list)
2. Run the 7-category checklist below on each file
3. Run automated checks (build, lint, tests)
4. Report findings as PASS / FAIL / WARNING
5. Fix all FAIL items before proceeding

---

The 7-Category Verification Checklist

Category 1: Variable Declaration Order (TDZ Prevention)

**What to check:** Variables, constants, and hooks used BEFORE their declaration in the same scope.

**How it breaks:** JavaScript `const` and `let` have a "temporal dead zone" — referencing them before their declaration line throws `ReferenceError` at runtime, but no build error.

**React-specific**: `useMemo`, `useCallback`, `useEffect` that reference state or derived values declared later in the component. This is the #1 AI-introduced bug.

**Scan pattern:**

• For every `useMemo`, `useCallback`, `useEffect`: check that ALL variables in the dependency array AND the callback body are declared ABOVE that hook.
• For every function that references a `const`/`let`: check the declaration is above the function definition.
• For every destructured import used in a module-level `const`: check for circular dependencies.

**Real examples caught:**

• `activeQuestions` useMemo referenced 150 lines before its declaration
• `baseDeps` used in JSX but handler functions declared 100 lines later
• `DR_FIELDS` referenced in `NFR_CATALOG` before `export const DR_FIELDS` line

**Fix:** Move the declaration above all usages. If it's a React hook, reorder hooks so dependencies come first.

---

Category 2: Import/Export Integrity

**What to check:** Every import resolves to a real export. Named vs default matches.

**How it breaks:** Build may succeed (tree-shaking ignores dead imports in dev mode) but runtime throws `undefined is not a function`.

**Scan pattern:**

• For each `import { X } from './file'`: open `./file` and confirm `export { X }` or `export const X` or `export function X` exists.
• For each `import X from './file'`: confirm `export default X` exists.
• Flag: `import { X } from './file'` when file only has `export default X` (or vice versa).

**Real examples caught:**

• `useResizeHandle` imported as default when it's a named export
• `ConfluencePagePicker` imported as default when it's a named export
• Removed component still imported in 3 files

**Automated check:**

npx eslint --rule '{"import/named": "error", "import/default": "error"}' src/

---

Category 3: Reference Integrity

**What to check:** After any rename/remove/move, ALL usages of the old name are updated.

**Scan pattern:**

• Search for ALL usages of the old name across the project
• Verify zero references remain to removed identifiers
• Check that moved code doesn't reference variables from its old scope

**Real examples caught:**

• `setPrdDocViewMode` was removed but `Cmd+E` handler still called it
• Removed component still imported in 3 files

// BUG: setPrdDocViewMode was removed but Cmd+E handler still calls it
useEffect(() => {
  const handler = (e) => {
    if (e.metaKey && e.key === 'e') setPrdDocViewMode(prev => ...);  // ReferenceError
  };
}, []);

---

Category 4: Dead Code Detection

**What to check:** Unused imports, unreachable code, orphaned handlers.

**Scan pattern:**

• Unused imports: variable imported but never referenced in file body.
• Orphaned event handlers: `onClick={handleFoo}` removed from JSX but `const handleFoo = ...` still declared.
• Unreachable code: `return` before a code block, `if (false)` guard, feature-flagged code where flag is always false.
• State setters never called: `const [x, setX] = useState()` where `setX` appears nowhere.
• Functions defined but never called.

**Automated check:**

npx eslint --rule '{"no-unused-vars": "error", "no-unreachable": "error"}' src/file.jsx

---

Category 5: React State & Effects

**What to check:** State variables are used, effects clean up, no updates after unmount, correct dependencies.

5.1 Component Reuse Bugs

When the same component renders for multiple routes (e.g., `OperationalDocEditor` for DR/IRP/Recovery):

• Does it have a `key={uniqueId}` to force remount on route change?
• Does it reset internal state when props change?

5.2 Effect Dependencies

For every `useEffect`:

• Are all referenced variables in the dependency array?
• Are object/array deps stable (memoized) or will they trigger infinite re-renders?
• Does the cleanup function undo what the effect created?

5.3 Ref Safety

• Is `ref.current` used in the render return? (Should be state instead — ref changes don't trigger re-render)
• Are refs initialized before first access? (Common with resize handles)
• Does `useRef` get set in an effect that runs after the component mounts?

5.4 Async State Updates

• D