dead-code-removal

Purpose

Dead code increases maintenance overhead and confuses developers. Verify a symbol is truly unused across the entire repository, then delete it outright — never comment it out.

When to Use

• A symbol, file, or export looks unused
• A feature removal or migration left orphaned helpers behind
• A coverage or lint report flags unreachable code

Inputs

• The candidate symbols/files to remove
• The repo's test and type-check commands

Workflow

1. Verify unused — search the entire repository. Do not assume code is dead just because the current file doesn't use it:

   grep -rn "symbolName" . --include="*.ts" --include="*.tsx"    # all references
   grep -rn "from ['\"].*module-name" src/                       # import sites
   git log -3 --oneline -- path/to/suspect-file                  # recent touches

   Ecosystem tools can shortcut the inventory when available (e.g., knip or ts-prune for TypeScript exports, vulture for Python).

2. Check for dynamic invocation. Be wary of dynamically invoked code — reflection, dependency injection by string name, ORM mappers, route tables, config-driven dispatch:

   grep -rn "\"symbolName\"\|'symbolName'" .    # string-keyed references

   If there is any doubt, leave it alone or ask the user.

3. Delete aggressively. Once confirmed unused, delete the code. Do not comment it out.
4. Prune dependencies. If you delete the only code that was using an imported module, remove the import statement as well.
5. Run tests. Always run tests and/or type checkers (e.g., tsc --noEmit) after removal to ensure you didn't accidentally break a hidden dependency.

Output

• The deletion diff plus, per removed symbol, the search evidence that it was unused

Verification

• Whole-repo search performed per symbol — including string-keyed/dynamic references
• No commented-out code left behind
• Orphaned imports pruned along with the dead code
• Tests and type checker green after removal

Failure Modes

• Current-file blindness — "this file doesn't use it" is not "the repo doesn't use it".
• Dynamic-invocation casualties — reflection/DI/ORM references don't appear as imports; search string keys too.
• Commenting instead of deleting — commented-out code is still dead code; git history already preserves it.