/code-cleanup

name: code-cleanup
description: "Detect stale TODOs, unused imports, and dead code."
user-invocable: false
argument-hint: "[<path-or-scope>]"
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
triggers:
  - "code cleanup"
  - "find small improvements"
  - "fix neglected issues"
  - "clean up code"
  - "quality of life fixes"
  - "find TODOs"
  - "stale comments"
  - "unused imports"
  - "technical debt scan"
routing:
  triggers:
    - "find dead code"
    - "stale TODOs"
    - "unused imports"
    - "clean up"
    - "tidy code"
    - "remove dead code"
    - "find unused"
  not_for: "multi-phase workflow orchestration or repo reorganization (use workflow). This skill finds dead code and stale TODOs in place."
  category: code-quality
  pairs_with:
    - code-linting
    - universal-quality-gate
    - comment-quality

Code Cleanup Skill

Scan repositories for 9 categories of technical debt (TODOs, unused imports, dead code, missing type hints, deprecated functions, naming inconsistencies, high complexity, duplicate code, missing docstrings), prioritize findings by impact/effort ratio with time estimates, and generate structured markdown reports with exact file:line references. Can apply safe auto-fixes when the user grants explicit permission.

Examples

**Focused cleanup** -- User says "Clean up the API handlers in src/api/". Read project config, scan src/api/ for all 9 categories, prioritize (5 unused imports auto-fixable, 2 stale TODOs >90d, 1 high-complexity function), present tiered report with auto-fix commands.

**Broad debt scan** -- User says "What's the state of technical debt in this repo?". Identify languages and source directories, run all applicable scans, group 47 findings into Quick Wins (12), Important (8), Polish (27), generate full report with effort estimates: 2h quick wins, 6h important, 4h polish.

**Auto-fix request** -- User says "Fix all the unused imports and sort them". Verify ruff/goimports available, scan for F401 and I001 violations only, report 23 unused imports across 8 files, user confirms, apply fixes, run tests, show diff.

---

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | writing the cleanup report | `report-template.md` | Loads detailed guidance from `report-template.md`. | | running per-language scans: unused imports, dead code, debug statements | `scan-commands.md` | Loads detailed guidance from `scan-commands.md`. | | checking which cleanup tools are installed per language | `tools.md` | Loads detailed guidance from `tools.md`. |

Instructions

Phase 1: SCOPE

**Goal**: Determine what to scan and verify tooling is available.

**Step 1: Read project context**

• Check for CLAUDE.md, .gitignore, pyproject.toml, go.mod, package.json -- read and follow any repository CLAUDE.md before doing anything else, since it may contain project-specific exclusions or conventions that override defaults
• Identify primary languages and project structure

**Step 2: Determine scan scope**

• If the user specified a directory or issue type, use that exactly -- only scan for requested issue types or smart defaults, never build elaborate reporting dashboards or speculative features
• If the user specified only an issue type (e.g., "find unused imports"), scan all source directories for that type only
• If the request is vague ("clean up code"), ask the user for a target area rather than scanning the entire codebase, because unfocused scans produce overwhelming noise that users cannot act on
• Always exclude: vendor/, node_modules/, .venv/, build/, dist/, generated/, .git/ -- these contain third-party or generated code that the user cannot fix, so including them buries real findings
• Respect .gitignore patterns when determining what to scan

**Step 3: Verify tool availability**

Check which analysis tools are installed so you know what scans are possible before starting. Report missing tools with install commands.

# Python tools
command -v ruff && echo "ruff: available" || echo "ruff: MISSING (pip install ruff)"
command -v vulture && echo "vulture: available" || echo "vulture: MISSING (pip install vulture)"

# Go tools
command -v gocyclo && echo "gocyclo: available" || echo "gocyclo: MISSING (go install github.com/fzipp/gocyclo/cmd/gocyclo@latest)"
command -v goimports && echo "goimports: available" || echo "goimports: MISSING (go install golang.org/x/tools/cmd/goimports@latest)"

If critical tools are missing, offer to proceed with partial scan using available tools (grep, git blame are always available).

**Gate**: Scope defined, languages identified, tool availability known. Proceed only when gate passes.

Phase 2: SCAN

**Goal**: Detect all cleanup opportunities within scope using deterministic tools.

Run applicable scans based on language and scope. See `references/scan-commands.md` for full command reference.

**Core scans (all languages)**: 1. **Stale TODOs**: grep for TODO/FIXME/HACK/XXX, then age every match with git blame -- a 180-day-old TODO about a data race is fundamentally different from yesterday's "TODO: add test case", so age-based triage is essential for prioritization 2. **Unused imports**: ruff (Python), goimports (Go) 3. **Dead code**: vulture (Python), staticcheck (Go) 4. **Complexity**: radon (Python), gocyclo (Go)

**Extended scans (if tools available)**: 5. Missing type hints (Python: ruff --select ANN) 6. Deprecated function usage (staticcheck, grep for known patterns) 7. Naming inconsistencies (grep for convention violations) 8. Duplicate code (pylint --enable=duplicate-code) 9. Missing docstrings (ruff --select D)

Collect all output with exact file:line references -- never summarize away specifics, because the user needs precise locations to act on findings. For each scan, record:

• Number of findings
• Files affected
• Whether findings are auto-fixable

If a scan tool is unavailable, note it as skipped and continue with remaining scans. Never