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 / Opus)
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, Sonnet for code-pattern reasoning across one language, and an Opus tier for cross-module
dependency reasoning where wrong calls have high blast radius. Model cap: these are defaults —
resolve each per skills/sdlc/templates/models.md (--model <tier> > project.json models.cap >
the tier here). The fan-out is Sonnet-first, so the Opus tier runs Sonnet unless you opt up with
--model opus; print model: <tier> (cap: <cap|none>) before each dispatch. NO subagents.
Read skills/dead-code-review/references/lenses.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".
| Lens |
Tier |
Applies when |
| 1 — Server / backend code |
Sonnet |
there is a service or library layer |
| 2 — Client / frontend code |
Sonnet |
there is a UI surface |
| 3 — Data layer and migrations |
Opus tier |
there is a schema or migration directory |
| 4 — Documentation and plans |
Haiku |
always |
| 5 — Scripts, config, test infra |
Haiku |
always |
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:
- Triage findings by confidence level (HIGH/MEDIUM/LOW)
- Execute HIGH-confidence removals first — deletions, import cleanups, dead function removal
- Restart or rebuild the running stack if the repo has one (
project.json stack.*)
- Re-run test suite to verify zero regressions
- Execute MEDIUM-confidence removals if tests pass
- 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
| Scope |
What runs |
full (default) |
every lens that applies to this repo |
backend |
lenses 1 + 3 |
frontend |
lens 2 |
database |
lens 3 |
docs |
lenses 4 + 5 |
Rules
- Use the tiered assignments in
references/lenses.md (Haiku / Sonnet / Opus) — do NOT promote everything to Opus.
The fan-out is Sonnet-first, so the Opus tier is an explicit opt-up (--model opus); each agent's
tier is chosen based on reasoning load and blast radius of a wrong
call. 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.
- Agents do NOT use subagents — each does all its own work
- 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
1---2name: dead-code-review3description: Launches a parallel fan-out of review agents (tiered by load, Sonnet-first — capped per project.json models.cap / --model) to find dead code, dead docs, and dead plans, then removes them and runs the test suite before and after to verify zero regressions. THIS IS THE SKILL FOR "launch a few agents to review everything for dead code / anything no longer needed" — use it instead of hand-composing an ad-hoc agent fan-out. Scans whatever surfaces the repo actually has — server code, client code, data/migrations, documentation, scripts — for unused imports, dead functions, orphaned components, stale plans, and redundant migrations. Use when the user says /dead-code-review, "what can be deleted", "what's no longer needed", "what docs are worth keeping vs getting rid of", "clean this up", "look for dead code", or asks to sweep the repo after a feature lands, a refactor, or before a release.4---56# Dead Code Review78Systematically find and remove dead code, stale documentation, unused database objects, and orphaned9files across the entire codebase. Uses parallel agents tiered by reasoning load (Haiku / Sonnet / Opus)10for exhaustive analysis, then applies fixes with test verification.1112## Process1314### Phase 1: Establish Test Baseline1516Run the configured test suites (from `.claude/project.json` `test.*` — `unit`, `frontend`,17`e2e`) and record pass/fail counts. Skip any key that is not configured, and say which you18skipped. No `project.json` and no discoverable suite means **no baseline**: say so plainly and19restrict the run to report-only, because "zero regressions" is unverifiable without one.2021### Phase 2: Launch Parallel Analysis Agents2223Launch up to 6 agents in parallel. Each agent does **research only** — no edits — and reports back24findings with confidence levels. Models are tiered by reasoning load: Haiku for grep-heavy hygiene25work, Sonnet for code-pattern reasoning across one language, and an Opus tier for cross-module26dependency reasoning where wrong calls have high blast radius. **Model cap:** these are *defaults* —27resolve each per `skills/sdlc/templates/models.md` (`--model <tier>` > `project.json` `models.cap` >28the tier here). The fan-out is **Sonnet-first**, so the Opus tier runs Sonnet unless you opt up with29`--model opus`; print `model: <tier> (cap: <cap|none>)` before each dispatch. NO subagents.3031**Read `skills/dead-code-review/references/lenses.md` now** — it carries the five lenses and32their per-surface checklists, plus the shared reporting contract.3334First resolve which lenses apply. The surfaces are **roles, not paths**: read35`.claude/project.json` `modules` if present, otherwise infer them from the repo layout. A repo36with no client code skips the client lens; a repo with no database skips the data lens. Say which37lenses you dropped and why — a silent skip reads as "clean".3839| Lens | Tier | Applies when |40|---|---|---|41| 1 — Server / backend code | Sonnet | there is a service or library layer |42| 2 — Client / frontend code | Sonnet | there is a UI surface |43| 3 — Data layer and migrations | Opus tier | there is a schema or migration directory |44| 4 — Documentation and plans | Haiku | always |45| 5 — Scripts, config, test infra | Haiku | always |4647Dispatch the applicable lenses in one message. There is no separate test-runner agent — Phase 148already established the baseline.4950### Phase 3: Consolidate & Execute5152After all agents report back:53541. **Triage findings** by confidence level (HIGH/MEDIUM/LOW)552. **Execute HIGH-confidence removals first** — deletions, import cleanups, dead function removal563. **Restart or rebuild** the running stack if the repo has one (`project.json` `stack.*`)574. **Re-run test suite** to verify zero regressions585. **Execute MEDIUM-confidence removals** if tests pass596. **Final test run** to confirm everything6061### Phase 4: Report6263Provide a summary table:64- Files deleted (count + line count)65- Files modified (count + lines removed)66- Database objects dropped (tables, indexes, columns)67- Test comparison (baseline vs after cleanup)6869## Scope Options7071| Scope | What runs |72|-------|-----------|73| `full` (default) | every lens that applies to this repo |74| `backend` | lenses 1 + 3 |75| `frontend` | lens 2 |76| `database` | lens 3 |77| `docs` | lenses 4 + 5 |7879## Rules8081- Use the tiered assignments in `references/lenses.md` (Haiku / Sonnet / Opus) — do NOT promote everything to Opus.82 The fan-out is **Sonnet-first**, so the Opus tier is an explicit opt-up (`--model opus`); each agent's83 tier is chosen based on reasoning load and blast radius of a wrong84 call. If a specific run genuinely needs deeper analysis (e.g., the database agent flags ambiguous85 cross-module references), promote that single agent — not the whole fleet.86- Agents do NOT use subagents — each does all its own work87- Never commit during the review — the user decides when to commit88- Always run tests before AND after to verify zero regressions89- Only remove code at HIGH confidence unless the user explicitly approves MEDIUM items90- Consult `GOTCHAS.md` at repo root (or `project.json` `gotchas_file`) for known patterns91- If a function appears unused but is referenced by a string-based dispatch (like intent routing), do NOT remove it92- If a type is used as a return type of a live API method, do NOT remove it even if never imported externally
exerias21