# Dead Code Cleaner

> Use when finishing a task, after completing edits, or when code feels cluttered with unused imports, unreferenced functions, commented-out blocks, orphaned files, or duplicate utilities. Reduces the 41% code churn rate caused by AI agents leaving obsolete artifacts behind.

- Skill: `owen-dev-6174/dead-code-cleaner` (Agent Skill)
- Install (CLI): `npx skillmds@latest add owen-dev-6174/dead-code-cleaner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/owen-dev-6174/dead-code-cleaner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: owen-dev-6174 (https://skillmd.com/u/owen-dev-6174)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/owen-dev-6174/dead-code-cleaner

---


# Dead Code Cleaner: If It Serves No Purpose, It Must Go

AI agents leave debris. Unused imports, orphaned functions, commented-out blocks, duplicate utilities -- dead code that inflates churn to 41%. This skill runs a cleanup pass after every task.

## The Iron Law

> **Code that serves no purpose is not neutral -- it is a lie that the next reader must investigate.**

Every dead line forces the next developer to ask: "Is this important? Is it used somewhere I can't see? Was it left here intentionally?" That wasted investigation multiplies across every future reader.

## The Process

### Step 1 -- Scan for the Five Categories

After completing a task, sweep all modified and newly created files for:

1. **Unused imports** -- Modules imported but never referenced in the file
2. **Unreferenced functions/variables** -- Declared but never called or accessed
3. **Commented-out code** -- Not comments explaining why, but old code preserved "just in case"
4. **Orphaned files** -- Files created during development (scratch files, old versions, temp utilities) that are not imported or referenced anywhere
5. **Duplicate utilities** -- Functions that do the same thing as an existing utility, often created because the agent did not discover the original

### Step 2 -- Verify Before Removing

For each candidate, confirm it is truly dead:

- **Unused imports**: Search the file for any reference to the imported name. Check for side-effect imports (CSS modules, polyfills, init scripts) that are intentionally reference-free.
- **Unreferenced functions**: Search the entire project, not just the current file. Check for dynamic references (`getattr`, bracket notation, reflection). Check for exports consumed elsewhere.
- **Commented-out code**: Distinguish code from documentation. `// Calculate the hash using SHA-256` is a comment. `// const result = oldApi.fetch(url)` is dead code.
- **Orphaned files**: Verify no imports, requires, or references point to the file. Check build configs, test configs, and scripts.
- **Duplicates**: Confirm identical behavior before removing. Keep the version with better naming, tests, or documentation. Update all callers to use the surviving version.

### Step 3 -- Remove With Precision

- Remove one category at a time. Verify the build and tests still pass after each category.
- Do NOT remove code that is outside the scope of your current task unless it was created or modified as part of this task.
- If unsure whether something is dead, leave it and flag it for the user.

### Step 4 -- Report What Was Cleaned

After cleanup, summarize:

- What was removed and why
- What was flagged as suspicious but left (with reasoning)
- Any duplicates found that may warrant consolidation in a future task

## Red Flags -- Common Dead Code Patterns

| Pattern | Category |
|---|---|
| `import { helper } from './utils'` but `helper` never appears below | Unused import |
| `function oldHandler() { ... }` with zero call sites | Unreferenced function |
| `// const config = loadLegacyConfig()` | Commented-out code |
| `temp_solution.ts` or `utils_backup.js` in project | Orphaned file |
| `formatDate()` in `helpers.ts` AND `formatDateString()` in `utils.ts` doing the same thing | Duplicate utility |
| `TODO: remove after migration` still present months later | Stale dead code |
| Variable assigned but never read | Unreferenced variable |
| Entire `else` branch that returns the same value as the `if` branch | Redundant logic |

## Flowchart

```dot
digraph dead_code_cleaner {
    rankdir=TB
    node [shape=box style=rounded]

    done [label="Task completed"]
    scan [label="Step 1: Scan modified/created files\nfor 5 dead code categories"]
    found [label="Dead code\ncandidates found?" shape=diamond]
    verify [label="Step 2: Verify each candidate\nis truly dead\n(search project-wide)"]
    confirmed [label="Confirmed dead?" shape=diamond]
    flag [label="Flag as suspicious\nfor user review"]
    remove [label="Step 3: Remove one\ncategory at a time"]
    test [label="Build + tests\nstill pass?" shape=diamond]
    revert [label="Revert removal.\nFlag for user."]
    more [label="More categories\nto clean?" shape=diamond]
    report [label="Step 4: Report\nwhat was cleaned\nand what was flagged"]
    finish [label="Present clean work"]

    done -> scan
    scan -> found
    found -> finish [label="None"]
    found -> verify [label="Yes"]
    verify -> confirmed
    confirmed -> remove [label="Yes"]
    confirmed -> flag [label="Unsure"]
    remove -> test
    test -> more [label="Yes"]
    test -> revert [label="No"]
    revert -> more
    more -> verify [label="Yes"]
    more -> report [label="No"]
    flag -> more
    report -> finish
}
```