Gap Check

Thorough post-implementation review covering what's missing (quality gaps) and what's left behind (dead code). The counterpart to simplify: gap-check finds missing things, simplify finds excess things.

When to Use

• Right after implementing a feature or fix
• User asks "any gaps?", "anything missing?", "anything left?", "did we cover everything?"
• User asks "did we remove old files?" or "anything unused?"
• End of an implementation session, before marking the task done
• After a refactor, to catch stale imports / dead files left behind

Do not use this skill for:

• Plan review before implementation — use plan-review
• Simplification / DRY / over-engineering — use simplify
• Production readiness — use pre-ship

Preflight — classify the review target

Before starting, identify what kind of change surface you're reviewing. The 6 quality-gap categories are code-biased — they work best on TypeScript/JavaScript/Python/Go application code. On docs, skill files, shell scripts, or config-only changes, some categories don't apply.

Target types:

• Code repo / app feature — default. Use all 6 quality-gap categories.
• Docs / markdown / skills repo — substitute the doc-consistency rubric below instead of (or alongside) the code rubric.
• Shell / infra / tooling — use quality-gap categories 1 (incomplete paths), 2 (error handling), 5 (happy-path bias) + the infra additions below.
• Mixed — scope to each surface appropriately.

State the target type in the first line of your output.

Doc / skills repo rubric (substitute for Phase 2 when target is docs)

• Broken internal references — links, file paths, skill names that don't exist
• Frontmatter drift — name doesn't match dir, required fields missing, description under 80 chars
• Stale examples — worked examples referencing removed files or outdated APIs
• Cross-file divergence — sibling docs that drift out of sync (e.g., README vs CONTRIBUTING describing the same thing differently)
• Typos / copy errors — real misspellings, not style preferences
• Structural inconsistency — one skill uses "Phase 1/2/3", another uses "Step 1/2/3"

Infra / shell additions (add to code rubric when target is shell/infra)

• Idempotency — can steps be re-run safely?
• Destructive ops — rm -rf, ln -sfn, force-push, drop-table — explicit + guarded?
• Dry-run support — can the user preview without mutating?

Steps

Phase 1 — Identify the change surface

Determine what code to review. In order of preference:

1. Git diff of uncommitted changes: git diff --stat + git diff
2. Session-touched files — what this session edited or created
3. User-specified scope — the files or feature the user names

If the scope is unclear, ask. Do not audit the entire repo unless explicitly asked.

Phase 2 — Quality Gaps (6 categories)

1. Incomplete code paths. Branches reaching dead ends. Functions returning undefined instead of a real value. switch without default. try without meaningful catch. Early returns skipping necessary cleanup.
2. Missing error handling. Network calls without try/catch. File reads without error checking. Third-party API calls that could throw. External inputs consumed without validation. Silent failures swallowing exceptions and logging nothing.
3. Cross-cutting concerns. Missing middleware (auth, rate limit, logging). Missing analytics events on new user actions. Missing i18n keys on new user-facing strings. Missing feature flag guards. Missing CORS headers on new public endpoints.
4. State consistency. Can this put the system into an inconsistent state across client/server/worker/DB? DB updates without cache updates. Events emitted without handlers waited on. Multi-step flows without transactions or compensation. Optimistic UI updates without rollback on failure.
5. Happy-path bias. What's the worst thing a user or external system could do to break this? Malicious input (XSS, SQL injection, path traversal). Adversarial users (double-submit, replay, concurrent edits). Misbehaving integrations (delayed webhooks, out-of-order events, truncated payloads).
6. Race conditions. Async operations that could interleave dangerously. Setting state from stale closures. Updating state based on stale state. DB TOCTOU. Event handlers firing after unmount. Timers outliving their components.

Phase 3 — Dead Code Cleanup (5 categories)

Post-refactor work often leaves orphans:

1. Unused files. Components, services, utils, tests no longer imported anywhere. Grep every new file's name to verify imports exist.
2. Dead routes. Frontend routes or backend endpoints no longer referenced. Navigation entries pointing to removed pages. API routes with no client caller.
3. Stale imports. Imports pointing to moved/deleted files. Unused imports. Barrel files re-exporting things that no longer exist.
4. Duplicate implementations. New code duplicating something that already existed. Cross-reference new functions against existing utility modules.
5. Leftover debug code. console.log, debugger, commented-out blocks, TODOs added in this session, placeholder strings ("Hello World", "lorem ipsum").

Phase 4 — Produce the report

# Gap Check — {{scope}}

## 🐛 Critical (will cause bugs or crashes in production)
1. [path:line] — [issue] — [proposed fix]

## ❌ Should fix (bad pattern, technical debt)
...

## ⚠️ Minor (cosmetic, optional)
...

## Dead code found
- [file path] — [what it is] — [safe to delete / needs review]

## Verdict
**Ready to ship** / **Ship with caveats** (list them) / **Not ready** (list blockers)

Phase 5 — Ask before fixing

Do not fix during review. After listing:

• User says "fix all" → implement critical + should-fix, ask about minors individually
• User says "fix N, 3, 5" → implement only those
• User says "delete dead files X, Y" → delete only those, never delete without explicit go-ahead

Never delete files automatically. Dead-code findings are highest-stakes — false positives delete working code.

Output Format

See Phase 4. Rules:

• Severity labels mandatory: 🐛 Critical, ❌ Should fix, ⚠️ Minor
• File/line references required: path:line format
• Dead code: list each file's purpose, not just the path
• Verdict is binary-ish: Ready / Caveats / Not ready

Rules

1. Scope discipline. Review only the change surface. Do not grep the whole repo unless asked — that's pre-ship's job.
2. Never delete files silently. Dead code goes in a list. User approves each deletion.
3. Don't say "looks good" unless it genuinely is. Zero-findings reviews are fine when earned.
4. Ask before evaluating the unknown — when an interactive user is present. In subagent / headless mode, flag the uncertainty and continue with a "needs user confirmation" note. Do not prompt.
5. Separate quality gaps from dead code in the output. They have different risk profiles.
6. Don't re-audit what simplify would catch. DRY violations, over-engineering, clever code — those belong in simplify.
7. Always end with a verdict.
8. In subagent / headless mode, emit the report and stop. The calling agent handles Phase 5 decisions. Do not wait for "fix all" input.

Worked Example — Output

# Gap Check — Team invites implementation

## 🐛 Critical (will cause bugs or crashes in production)

1. `src/api/invites/create.ts:42` — `await sendEmail(user.email)` has no
   try/catch. If Resend is down, invite row is already inserted but user
   sees 500 with no retry path.
   - **Fix:** wrap in try/catch, mark row `email_pending` on failure,
     schedule retry via `src/workers/email-retry.ts`.

2. `src/pages/invite/[token].tsx:18` — uses `token` from URL without
   validation. Malformed URL crashes the client when `useUser` throws.
   - **Fix:** validate token with `z.string().uuid()` before hook calls;
     show 404 if invalid.

## ❌ Should fix (bad pattern, technical debt)

3. `src/api/invites/create.ts:58` — no rate limit. 1000 invites/min possible.
   - **Fix:** apply existing `rateLimit(50, '1h')` middleware at
     `src/middleware/rate-limit.ts:15`.

4. `src/api/invites/create.ts:72` — race condition on "already invited" check.
   - **Fix:** DB unique constraint on `(org_id, email)`; catch
     `UNIQUE_VIOLATION` and return 409.

## ⚠️ Minor

5. `src/components/InviteButton.tsx:24` — icon button missing `aria-label`.
   - **Fix:** `aria-label="Invite team member"`.

## Dead code found

- `src/lib/invites/legacyInviteSystem.ts` — 180-line module from the previous
  invite system. No imports (grep confirmed). **Safe to delete.**
- `src/pages/invite/accept.tsx` — old accept route, replaced by
  `[token].tsx`. Still referenced in nav menu. **Needs review** — update
  nav first, then delete.
- `src/styles/invite-legacy.css` — only imported by the file above.
  **Safe to delete** after the above.

## Verdict

**Ship with caveats.** Blockers 1 and 2 must be fixed before deploying.
Finding 3 (rate limit) should ship in the same PR. Findings 4, 5, and
dead code cleanup can follow in a second PR if deadline is tight.

Pipeline Position

write-plan → plan-review → (implement) → [gap-check] → simplify → pre-ship → (deploy) → pr-triage

Gap-check is the first review pass after implementation. Run it before simplify so simplify doesn't strip away code you still need to complete. Run it before pre-ship so pre-ship gets a clean codebase.