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

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
}