sanity-check

name	sanity-check
description	Post-implementation audit — checks codebase against the goal, runs stack-specific checks, security, performance, logic edge cases, and tests, then produces a PASS/WARN/FAIL report with severity tiers.
allowed-tools	Bash, Read, Glob, Grep, AskUserQuestion, Agent

Sanity Check Protocol

A post-implementation audit. Checks paths, imports, security, logic, bugs, and likely failure modes against the stated goal, then reports findings by severity. Report first, fix second.

Step 0 — Determine Mode

Parse the mode from the argument passed to this skill:

• -l or no argument → LOW: scope is the recently changed files only. Run every check category scoped to those files. Apply logic, security, and performance checks to changed files only. Type-check only (e.g. tsc), no full test suite.
• -h → HIGH: scope is the full codebase. Apply stack-specific checks. Run the full test suite. For checks that require finding all usages (e.g. a changed type's call sites), grep the whole codebase.

Both modes check for the exact same categories of bugs — security, logic, careless mistakes, paths, imports, everything. The difference is only how wide you search.

State the mode: MODE: HIGH or MODE: LOW

---

Phase 1 — Establish Ground Truth

Use the conversation context as the primary source for what was changed this session. Then verify with git if available:

git rev-parse --is-inside-work-tree 2>/dev/null && \
  git diff --name-only HEAD && \
  git status --short && \
  git log --name-only --pretty="" -5 || true

If the command produces no output, it's not a git repo — use conversation context only.

State before proceeding:

GOAL: <one sentence from conversation context>
CHANGED FILES: <list>
COMPLETION: <did the work cover the full goal? name any gaps>

Any gap between goal and changed files is a Blocker.

---

Phase 2 — Stack Detection (HIGH only)

Skip in LOW mode.

ls go.mod pyproject.toml requirements.txt next.config.ts next.config.mjs next.config.js vite.config.ts vite.config.js 2>/dev/null
cat package.json 2>/dev/null | grep '"express"'

Priority: Go > Python > Next.js > React SPA > Node/Express > Generic JS

If no stack matches, note "unrecognized stack — universal checks only" and continue.

Apply the stack-specific checks below for whichever stack you detected (and the conditional modules if their condition matches). These run in HIGH mode across the full codebase. If you maintain your own deeper stack checklists, load them here.

Next.js — server/client component boundaries ("use client" correctness), data-fetching in the right place (server vs client), next/image/next/link usage, route handler method/return types, env vars exposed via NEXT_PUBLIC_ only when intended, hydration mismatches.

Python — virtualenv/deps consistency, mutable default args, broad except: swallowing errors, missing context managers for file/DB handles, type hints vs runtime, __init__.py/import path correctness.

Go — error returns checked (not _), goroutine leaks, defer placement, nil-pointer derefs, context propagation, race conditions (go test -race).

React SPA — hook rules (deps arrays, conditional hooks), key props on lists, state-update-on-unmount, controlled vs uncontrolled inputs, effect cleanup.

Node/Express — async error handling in middleware, unhandled promise rejections, missing next(err), body/param validation, route ordering.

Conditional — UI completeness (Next.js or React SPA): loading/empty/error states present, no dead buttons, forms submit and validate, responsive breakpoints not broken.

Conditional — DB migrations (changed files include migrations/, .sql, alembic/, prisma/migrations/): up/down symmetry, no destructive change without a guard, indexes for new lookups, migration matches the model/schema.

Always apply the logic, security, and performance checks below regardless of mode (LOW scoped to changed files, HIGH full codebase).

---

Phase 3 — Bug Checks

Run every category below in both modes. In LOW mode, scope all checks to the changed files only. In HIGH mode, expand scope where noted.

Paths & Imports

• Every new import/require: does the target file actually exist at that path? (Glob to verify)
• Case sensitivity: Button vs button — silent on case-insensitive filesystems, breaks on Linux
• Missing required extensions (.tsx, .js)
• Barrel file imports: does index.ts actually export that symbol?

Package Manager

ls pnpm-lock.yaml yarn.lock package-lock.json bun.lockb 2>/dev/null

The lockfile in the repo must match all install/run commands in scripts, docs, and CI config.

Environment Variables

• New env vars in code: present in .env.example / .env.template?
• Vars used in code that exist in no .env* file → runtime undefined

Dependencies

• Packages imported but not in package.json / requirements.txt / go.mod
• New packages added but lockfile not updated (install never ran)

Leftover Artifacts

grep -n "console\.log\|debugger\|TODO\|FIXME\|xxx\|temp2\|test2" <changed files>

Universal Bug Checks

Go through each item explicitly:

#	Check	Scope
1	Hardcoded localhost/127.0.0.1 not behind env var	changed files
2	Missing await on async calls	changed files
3	Wrong HTTP method at call site vs route definition	changed files
4	Type/schema changed but not all call sites updated	HIGH: full codebase grep / LOW: changed files only
5	Missing try/catch at I/O boundaries (fetch, DB, file, external API)	changed files
6	Copy-paste variable name left over (param name doesn't match usage)	changed files
7	Off-by-one (arr[arr.length], < len vs <= len, fencepost)	changed files
8	New function defined but never called anywhere	HIGH: full codebase grep / LOW: changed files
9	Stub shipped as real implementation (return null, pass, // TODO: implement)	changed files
10	.gitignore gap for new secrets, build artifacts, or upload dirs	changed files
11	Merge conflict markers	grep -r "<<<<<<|>>>>>>|=======" changed files
12	Race condition on shared mutable state (concurrent writes without locks)	changed files

Security

Check for these in all code written or modified (both modes):

• Hardcoded secrets, API keys, tokens, passwords
• Auth gaps: endpoints or operations that should require auth but don't
• Broken access control / IDOR (can user A access user B's data?)
• Injection: SQL, command, LDAP — is user input ever interpolated unsanitized?
• XSS: dangerouslySetInnerHTML, innerHTML, unescaped output
• CORS headers too permissive (* on credentialed routes)
• Sensitive data in logs, error messages, or client-visible responses
• Weak/missing input validation at system boundaries
• Crypto mistakes: MD5/SHA1 for passwords, rolling your own crypto, weak keys

Any security failure is automatically a Blocker.

Logic & Edge Cases

Check for these in all code written or modified (both modes):

• Null/undefined/empty collection not guarded before use
• Division by zero or modulo zero
• Float precision issues (0.1 + 0.2 !== 0.3)
• Array bounds and off-by-one (already in universal checks, double-check here)
• Infinite loops or missing recursion base cases
• State invariants violated (e.g. balance going negative, index out of sync)
• Date/time pitfalls (timezone assumptions, DST, epoch vs ms)
• Business logic edge cases specific to what was just written

Performance

• N+1 queries, work inside loops that belongs outside, unbounded fetches
• Missing pagination/limits, missing indexes for new lookups
• Re-renders / recomputation without memoization where it matters
• Large synchronous work blocking the event loop

---

Phase 4 — Tests

HIGH mode — run the test command matching the detected stack:

Stack	Command
Go	go test ./...
Python	pytest
Next.js / React SPA / Node/Express	`npx vitest run --passWithNoTests
Generic JS / unrecognized	npx tsc --noEmit

LOW mode — type-check only (JS/TS projects):

npx tsc --noEmit

Skip silently if not a JS/TS project.

If no tests exist: run build + type-check as the minimum. Note absence of tests as a finding — it's not a neutral state.

---

Phase 5 — Report

Number issues sequentially across all tiers (1, 2, 3... not restarting per tier). Only list tiers that have issues — omit empty tiers entirely. Be specific: file path + line number on every issue.

Status: FAIL = any Blocker present. WARN = warnings or nitpicks only, no blockers. PASS = no issues.

SANITY CHECK — [HIGH/LOW] — [PASS / WARN / FAIL]
<stack> | Goal: <one sentence>

Blockers
  1. <issue> [file:line]
     → <fix>

Warnings
  2. <issue> [file:line]
     → <fix>

Nitpicks
  3. <issue> [file:line] → <fix>

Tests: <PASS (X) / FAIL (X failed) / type-check PASS / type-check FAIL / NO TESTS>
Verdict: READY / NEEDS FIXES
Auto-fixable: <numbers or none>  |  Needs your call: <numbers — one-line reason each>

If all clear:

SANITY CHECK — [HIGH/LOW] — PASS
<stack> | Goal: <one sentence>

Tests: <result>
Verdict: READY

---

Rules

• Report first, fix second. Never auto-fix without confirmation.
• Security failures are always Blockers. No exceptions.
• Every issue needs a location. "import path wrong" is useless. "line 12 of auth.ts imports from ../../utils/hash but file is at ../utils/hash" is useful.
• Completion gaps are Blockers. If the goal was "add auth to 3 routes" and only 2 were touched, that's a blocker regardless of what else passes.