|
| 1 | +--- |
| 2 | +name: dead-code-remover |
| 3 | +allowed-tools: Read, Bash, Edit, Write, Grep, Glob |
| 4 | +description: Remove statically unreachable code immediately, and instrument suspected-but-unproven dead code with probe logging so a later run can confirm and remove it. Narrow mechanical maintenance routine intended to run on a schedule. |
| 5 | +--- |
| 6 | + |
| 7 | +# /dead-code-remover - Remove dead code, probe suspected dead code |
| 8 | + |
| 9 | +Two lanes each run: (1) delete code that is provably unreachable, (2) plant |
| 10 | +probes on code that looks dead but cannot be proven dead statically, and |
| 11 | +harvest probes planted by earlier runs. |
| 12 | + |
| 13 | +## Lane 1: provably dead - delete now |
| 14 | + |
| 15 | +Static signals, by ecosystem: |
| 16 | + |
| 17 | +```bash |
| 18 | +bunx knip # JS/TS: unused files, exports, deps |
| 19 | +cargo machete # Rust: unused deps |
| 20 | +``` |
| 21 | + |
| 22 | +Plus: exports with zero imports (`rg` the symbol), branches behind |
| 23 | +always-false flags, code behind removed feature flags, unreferenced assets. |
| 24 | + |
| 25 | +Provable means: no dynamic dispatch, no reflection, no string-keyed lookup, |
| 26 | +not a public API of a published package, not referenced from config, |
| 27 | +templates, or CI. If any of those apply, it goes to Lane 2. |
| 28 | + |
| 29 | +Delete it, then verify: build, typecheck, full test suite. One theme per PR |
| 30 | +(e.g. "remove unused exports in packages/x"), max ~400 deleted lines. |
| 31 | + |
| 32 | +## Lane 2: suspected dead - probe, then harvest |
| 33 | + |
| 34 | +For code that looks dead but is only provably-unused at runtime: |
| 35 | + |
| 36 | +1. Plant a probe at the entry point with a greppable marker: |
| 37 | + |
| 38 | +```ts |
| 39 | +// DEADCODE-PROBE 2026-08-23 remove-after 2026-08-30 |
| 40 | +console.warn("[deadcode-probe] <symbol> reached"); |
| 41 | +``` |
| 42 | + |
| 43 | +Use the codebase's existing logger if one exists. Probes ship in their own |
| 44 | +PR labeled `agent:probe`. |
| 45 | + |
| 46 | +2. On every run, harvest expired probes: |
| 47 | + |
| 48 | +```bash |
| 49 | +rg -n "DEADCODE-PROBE" --no-heading |
| 50 | +``` |
| 51 | + |
| 52 | +For each probe past its `remove-after` date, check the log store (or Sentry |
| 53 | +breadcrumbs, or grep production logs if accessible) for the probe message. |
| 54 | + |
| 55 | +- Never fired: delete the probe and the code it guards, in a normal Lane 1 PR. |
| 56 | +- Fired: delete the probe only, and record the symbol under "Confirmed alive" |
| 57 | + below so no future run re-probes it. |
| 58 | + |
| 59 | +## Hard rules |
| 60 | + |
| 61 | +- Never delete: public API of published packages, migration code, error |
| 62 | + handlers for rare-but-real paths, platform-conditional code for platforms |
| 63 | + still supported. |
| 64 | +- Deleting a file also means deleting its tests, mocks, stories, and exports. |
| 65 | + Leftover references fail the verify step. |
| 66 | +- Probe windows are 7 days minimum. Do not remove a probe early. |
| 67 | + |
| 68 | +## PR conventions |
| 69 | + |
| 70 | +- Branch: `chore/dead-code-<slug>` |
| 71 | +- Commit: `chore: remove dead <thing>` / `chore: probe suspected dead <thing>` |
| 72 | +- Labels: `refactor` + `agent:mechanical` (removals), `agent:probe` (probes) |
| 73 | +- PR body: evidence per deletion (tool output or zero-reference proof; for |
| 74 | + harvested probes, the probe date range checked and where logs were checked). |
| 75 | + |
| 76 | +## Tuning |
| 77 | + |
| 78 | +This file is the routine. When a PR is rejected or a deletion gets reverted, |
| 79 | +add the case below and tighten the rules. |
| 80 | + |
| 81 | +Confirmed alive (never re-probe): |
| 82 | + |
| 83 | +- (none yet) |
0 commit comments