dead-code-removal · diff
git:20260502.ad38d3a to git:20260606.0d81f34
56 added, 9 removed. Audit A to A.
---
name: dead-code-removal
- description: "Use to identify and safely delete unused functions, classes, exports, and files."
+ description: Use when unused functions, classes, exports, or files need to be identified and safely deleted.
---
- # Dead Code Removal
+ ## Purpose
- Dead code increases maintenance overhead and confuses developers.
+ 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.
- ## The Removal Protocol
+ ## When to Use
- 1. **Verify Unused**: Before deleting anything, you must search the *entire repository* to ensure the symbol or file is truly unused. Do not assume it is dead just because the current file doesn't use it.
- 2. **Check for Dynamic Invocation**: Be wary of dynamically invoked code (e.g., reflection, dependency injection by string name, ORM mappers). 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.
+ - 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:
+
+ ```bash
+ 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:
+
+ ```bash
+ 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.
+