---
name: dead-code
description: Scan for unused exports, unreachable code, orphaned files, and stale dependencies
type: analysis
version: v0.1
argument-hint: "[optional: specific package or directory to scope the scan]"
---

# Dead Code

Scan the codebase for unused code, orphaned files, and stale dependencies. Outputs a prioritized cleanup list.

## Process

1. **Determine scope:**
   - If `$ARGUMENTS` specifies a package or directory, scope the scan there.
   - Otherwise, scan the entire project (or all packages in a monorepo).
   - Read `CLAUDE.md` for project conventions.

2. **Scan for unused exports:**
   - For each file, identify exported functions, types, constants, and components.
   - Search the rest of the codebase for imports of each export.
   - Flag exports that are never imported anywhere (excluding entry points, API routes, and config files that are consumed externally).

3. **Scan for orphaned files:**
   - Identify files that are not imported by any other file.
   - Exclude entry points (pages, routes, API handlers, config files, scripts referenced in package.json).
   - Exclude test files, config files, and other files that are consumed by tools rather than imports.

4. **Scan for stale dependencies:**
   - Read `package.json` dependencies and devDependencies.
   - Search the codebase for actual usage of each dependency (imports, requires, CLI usage in scripts).
   - Flag dependencies that appear unused.
   - Note: some dependencies are used implicitly (PostCSS plugins, Babel presets, ESLint configs) — do not flag these.

5. **Scan for dead code patterns:**
   - Unreachable code after return/throw statements.
   - Commented-out code blocks (more than 3 lines).
   - Functions defined but never called (within a single file, non-exported).
   - Unused variables and parameters (if not caught by linting).
   - Feature flags or environment checks for conditions that are always true/false.

6. **Cross-reference with git:**
   - For flagged items, check `git log` to see when they were last meaningfully modified.
   - Items untouched for 6+ months get higher priority.

7. **Verify findings (false-positive filter):**
   - Before finalizing, re-read the actual source code for every flagged item. For each one, confirm:
     - The export/function is genuinely unused — re-check imports, re-exports through barrel files, and dynamic usage (`import()`, `require()`, string-based references).
     - The "orphaned" file isn't consumed by a tool, framework convention, or config (e.g., Next.js pages, migration files, seed scripts).
     - The "stale" dependency isn't used implicitly (PostCSS plugins, Babel presets, peer dependencies, CLI tools in npm scripts).
     - Commented-out code isn't an intentional reference or example kept for documentation purposes.
   - **Drop any finding you cannot re-confirm with a second read.** If uncertain, move it to "Needs Investigation" rather than "Safe to Remove."

## Output

### Unused Exports (high confidence)
| File | Export | Last Modified |
|------|--------|---------------|
| `path/to/file.ts` | `unusedHelper` | 4 months ago |

### Orphaned Files
- `path/to/orphan.ts` — not imported anywhere, last modified X ago

### Stale Dependencies
- `some-package` — no imports found in codebase
- `another-package` — only used in deleted file

### Dead Code Patterns
- `file.ts:42` — unreachable code after return
- `file.ts:100-115` — commented-out code block

### Safe to Remove (recommended)
Prioritized list of items safe to remove, grouped by package/directory.

### Needs Investigation
Items that might be unused but have ambiguous usage patterns (dynamic imports, reflection, external consumption).

## Follow-Through

After presenting findings, write actionable cleanup items to `tasks/todo.md`. If a finding is only a non-blocking future validation or condition-gated cleanup record, write it to `tasks/record-todo.md` instead with source, condition, non-blocking reason, evidence, and promotion rule:

1. Read `tasks/todo.md` if it exists — append to the end under a `## Dead Code Cleanup` heading (create the file if it doesn't exist).
2. Add one checkbox item per "Safe to Remove" finding, grouped by package/directory:
   ```markdown
   ## Dead Code Cleanup
   > Generated by `/dead-code` on [date]
   - [ ] Remove unused export `unusedHelper` from `path/to/file.ts`
   - [ ] Delete orphaned file `path/to/orphan.ts`
   - [ ] Remove stale dependency `some-package`
   ```
3. Do **not** add "Needs Investigation" items — only "Safe to Remove" items belong in todo.
4. If `tasks/todo.md` already has a `## Dead Code Cleanup` section, replace it with the fresh scan results.
5. Tell the user how many items were added and suggest `/exec` to execute the cleanup.

## Constraints
- Use subagents to parallelize scanning across packages in a monorepo.
- Never automatically delete anything — only report findings and write todo items.
- Be conservative with false positives — it's better to miss a dead export than to flag a used one.
- Exclude files matching common non-import patterns: `.config.`, `.d.ts`, migration files, seed files, scripts in `bin/`.
- If the codebase has a barrel file pattern (`index.ts` re-exports), trace through barrel files.


## Alignment Page

When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/dead-code-{topic}.html`.

## Default Shipping Contract

Follow the shared shipping contract convention in CLAUDE.md.
