Dead Code Review

Systematically find and remove dead code, stale documentation, unused database objects, and orphaned files across the entire codebase. Uses parallel agents tiered by reasoning load (Haiku / Sonnet) for exhaustive analysis, then applies fixes with test verification.

Process

Phase 1: Establish Test Baseline

Run the configured test suites (from .claude/project.json test.* — unit, frontend, e2e) and record pass/fail counts. Skip any key that is not configured, and say which you skipped. No project.json and no discoverable suite means no baseline: say so plainly and restrict the run to report-only, because "zero regressions" is unverifiable without one.

Phase 2: Launch Parallel Analysis Agents

Launch up to 6 agents in parallel. Each agent does research only — no edits — and reports back findings with confidence levels. Models are tiered by reasoning load: Haiku for grep-heavy hygiene work and Sonnet for code-pattern reasoning — including the data lens, whose cross-module dependency calls have the highest blast radius (raise it with models.dead_code_review: {data: opus}). Models: the tiers below are the defaults of models.dead_code_review in project.json (a string for all lenses, or a map keyed server, client, data, docs, scripts); resolve per skills/sdlc/templates/models.md, print model: dead_code_review <lens>=<tier>, … (cap: <cap|none>) and pass model explicitly on every dispatch.

Read references/lenses.md (next to this SKILL.md) now — it carries the five lenses and their per-surface checklists, plus the shared reporting contract.

First resolve which lenses apply. The surfaces are roles, not paths: read .claude/project.json modules if present, otherwise infer them from the repo layout. A repo with no client code skips the client lens; a repo with no database skips the data lens. Say which lenses you dropped and why — a silent skip reads as "clean".

Dispatch the applicable lenses in one message. There is no separate test-runner agent — Phase 1 already established the baseline.

Phase 3: Consolidate & Execute

After all agents report back:

1. Triage findings by confidence level (HIGH/MEDIUM/LOW)
2. Execute HIGH-confidence removals first — deletions, import cleanups, dead function removal
3. Restart or rebuild the running stack if the repo has one (project.json stack.*)
4. Re-run test suite to verify zero regressions
5. Execute MEDIUM-confidence removals if tests pass
6. Final test run to confirm everything

Phase 4: Report

Provide a summary table:

• Files deleted (count + line count)
• Files modified (count + lines removed)
• Database objects dropped (tables, indexes, columns)
• Test comparison (baseline vs after cleanup)

Scope Options

Rules

• If a specific run genuinely needs deeper analysis (e.g., the database agent flags ambiguous cross-module references), promote that single agent — not the whole fleet.
• Never commit during the review — the user decides when to commit
• Always run tests before AND after to verify zero regressions
• Only remove code at HIGH confidence unless the user explicitly approves MEDIUM items
• Consult GOTCHAS.md at repo root (or project.json gotchas_file) for known patterns
• If a function appears unused but is referenced by a string-based dispatch (like intent routing), do NOT remove it
• If a type is used as a return type of a live API method, do NOT remove it even if never imported externally