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

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
}