dead-code-find

---
name: "dead-code-find"
description: "Find and report dead code (unused imports, variables, functions, exports, unreachable code); report-only by default; optional removal when user asks. Language-agnostic; infer rules from file syntax."
license: "MIT"
---

# Dead code find

## Trigger

User runs `/dead-code` or asks to find dead code, unused code, audit dead code, find unused imports, find unused exports, remove dead code, or clean up unused code.

## Scope resolution

- **Explicit:** If the user names a path, file, or glob (e.g. `src/`, `**/*.ts`), use that.
- **Selection:** If the user has a selection in the editor, scope to that file (and optionally the selection region for context).
- **Default:** Current file. If the user said "project" or "repo" or "everywhere", scope to workspace and warn if the repo is large (e.g. suggest `src/` or a subfolder).
- **Limit:** For workspace scope, skip non-source by default (see Skip paths). Process a bounded set of files; if the scope would be huge, say so and suggest narrowing.

## Skip paths (do not analyze by default)

- Build/cache/dependency dirs typical in projects (e.g. `node_modules/`, `vendor/`, `dist/`, `build/`, `out/`, coverage and cache dirs, minified or bundled artifacts).
- Generated or lockfiles. Adapt the list to the project (infer from presence of manifest files or common conventions).
- Optionally treat test/fixture files as in-scope but note that "unused" there may be intentional (e.g. mocks). Do not skip them unless the user asks to focus only on app code.

## What to detect (language-agnostic)

**Infer from the file:** Use the file extension and syntax to recognize imports, declarations, exports, and control flow. **Verify by searching the codebase** for references (by symbol name, including re-exports and barrel/index files) before marking as unused. Prefer semantic search or grep over guessing.

### Categories

| Type | Meaning | Verification |
|------|---------|--------------|
| `unused-import` | Something brought in (import/require/include) but never used in the file | No reference to that symbol in the same file. Respect the language: type-only or metadata-only use may not count as "use" if it disappears at runtime. |
| `unused-variable` | Named storage declared but never read | No read of that name in scope; ignore type-only or annotation-only use when appropriate for the language. |
| `unused-function` | Callable defined but never invoked in analyzed scope | No call site in scope; for exported callables, search whole scope. |
| `unused-export` | Exposed for use elsewhere but not referenced in scope | Search all files in scope for any reference to this export; note "scope-only" in report. |
| `unreachable` | Code that cannot run (after exit/return/throw or in a branch that is never taken) | Control flow shows it is never executed. |

**Any language:** Adapt to how the language expresses imports, exports, and types. Side-effect-only imports (e.g. loading a module for its effects) are not unused. When symbols might be used via reflection, dynamic loading, or external consumers, mark as "possible unused" or note the caveat instead of asserting unused. When in doubt, report with a **confidence** note: "likely unused" vs "unused (verified no references)".

## Workflow

1. **Resolve scope** from user message (and selection if any). Apply skip paths. If scope is very large, cap or warn and suggest narrowing.
2. **Build file list** for the scope (any source-like files; infer syntax from extension or content).
3. **Per file:** Identify candidates using the file’s syntax (unused imports, unused variables/functions, unreachable blocks). For **exports**, search other files in scope for references to that symbol (and re-exports).
4. **Deduplicate and annotate:** One row per finding. Add a short **remediation** (e.g. "Remove import", "Remove variable and its assignment", "Delete unreachable block").
5. **Output report** (see Report format). **Do not edit files** unless the user explicitly asked to "remove", "fix", or "clean up" dead code.
6. **If user asked to remove:** Apply removals in a safe order: (a) remove unused imports, (b) remove unused variables and their initializers, (c) remove or comment unreachable code, (d) remove unused functions (and unused exports that are now unused). After each change, re-check that the file still parses; summarize what was removed.

## Report format

- **Header:** Scope (e.g. "Current file: `src/foo.ext`" or "Workspace: `src/`").
- **Table or list:** For each finding: **File** | **Line(s)** | **Type** | **Symbol / snippet** | **Remediation**. Optionally add a **Confidence** column (verified / likely) when relevant.
- **Summary line:** e.g. "N dead-code findings in M files." If zero: "No dead code found in the given scope."
- **Caveats (when applicable):** "Unused-export is scope-only; symbols may be used by other packages or at runtime."

## Guardrails

- Do not remove code that might be used dynamically (reflection, string-based imports, plugins, or external consumers) unless the user confirmed or it is clearly internal and unused.
- Unused-export analysis is limited to the analyzed scope; state that in the report when reporting unused exports.
- All removals must be semantics-preserving (no behavior change).
- If the user did not ask to remove, only report; do not edit files.

## Output

- Structured report (scope, findings table, summary, optional caveats).
- If removal was requested: list of edits applied and a one-line summary (e.g. "Removed 3 unused imports and 1 unused variable in 2 files.").