cleanup

name	cleanup
description	Run dead-code and duplicate-code detection across the codebase, get categorized cleanup recommendations
allowed-tools	Task, Read, Bash, Glob, Grep, Edit

/cleanup: Cleanup Analysis

Purpose

Spawn a cleanup-analyzer sub-agent that runs dead-code and duplicate-code detection across this repo's source surface, investigates each finding in context, and returns a structured report with categorized recommendations.

Optional detectors are used when available and skipped gracefully when they are not. The skill is tool-agnostic, not a toolchain mandate.

Usage

/cleanup              # run all detectors (dead code + duplicates)
/cleanup dead-code    # unused/dead code only
/cleanup duplicates   # duplicate code only

Execution

Step 1: Parse Arguments

Determine which detectors to run from $ARGUMENTS. Default is both. Valid tokens: dead-code, duplicates.

Step 2: Spawn the Cleanup Analyzer

Use the Task tool to spawn a sub-agent with the following prompt. Pass the selected detectors as input.

---

Sub-agent prompt (pass this entire block to Task):

You are a cleanup analyzer. Your job is to run static analysis, investigate each finding in the actual code, and return a structured report. You MUST NOT make any changes; only analyze and report.

Detectors to run: [insert selected detectors here]

A. Dead Code Detection

A.1: Source surface

Adapt the commands below to the language and build tool used by this repo. Examples are illustrative; substitute the equivalent for your stack (Rust, Go, Python, TypeScript, etc.).

# Run any available static-analysis or dead-code tool for the project language.
# Examples:
#   Rust:       cargo check 2>&1 | grep "unused"
#   TypeScript: npx --yes --no-install knip --no-exit-code 2>/dev/null
#   Python:     vulture . 2>/dev/null
# Skip silently if no tool is configured.
npx knip 2>/dev/null || echo "(knip not configured; skipping dead-code scan)"

# Fallback: orphan files with no inbound references in the source tree.
# Adjust file extensions to match the project language.
for f in $(find src -type f \( -name '*.rs' -o -name '*.ts' -o -name '*.py' \) \
            2>/dev/null \
            | grep -v target | grep -v node_modules | grep -v '__pycache__'); do
  base=$(basename "$f" | sed 's/\.[^.]*$//')
  # Skip known entry-point names:
  case "$base" in
    main|lib|mod|index|app|server) continue ;;
  esac
  # Count inbound references to the base name across the source tree:
  count=$(grep -rn "$base" src --include='*.rs' --include='*.ts' --include='*.py' \
            -l 2>/dev/null | grep -v "$f" | wc -l)
  if [ "$count" -eq 0 ]; then
    echo "ORPHAN: $f"
  fi
done

# Run the project linter as a secondary dead-code signal (unused vars, imports).
npm run typecheck 2>&1 | grep -E "unused|dead" || echo "(no unused lint findings)"

A.2: Unused declared dependencies

Check for declared dependencies with no actual usage in the source:

# Rust: cargo udeps (nightly), or review Cargo.toml manually
# TypeScript: depcheck
# Python: pip-extra-reqs / deptry
# Substitute the right tool for this repo's ecosystem:
npm audit --omit=dev || echo "(dependency audit tool not available; skipping)"

If no tool is available, fall back to grep-based analysis of import statements vs. declared dependencies.

B. Duplicate Code Detection

# Optional: a duplicate-code detector if installed. Examples:
#   jscpd (JS/TS), PMD CPD (Java), clonedigger (Python), simian (multi-language).
# Skip silently if not available.
if command -v <duplicate-detector> >/dev/null 2>&1; then
  <duplicate-detector> <source-dirs> --min-lines 10 2>/dev/null \
    || echo "(duplicate detector did not complete cleanly)"
else
  echo "(no duplicate detector available; skipping)"
fi

# Manual: surface near-identical exported identifiers across modules as a
# low-fidelity duplicate-block hint. Treat results as starting points for
# human review, not definitive findings.
grep -rn "^pub fn \|^export function \|^def \|^func " src/ 2>/dev/null \
  | awk -F: '{print $3}' | sort | uniq -d

C. Investigate Each Finding

For EVERY finding from the tools above, you MUST read the relevant source file(s) to understand context before categorizing. Do not blindly report tool output.

D. Categorize Findings

Dead Code: KEEP (false-positive prevention)

• Spec-spine derived artifacts: anything under .derived/ is never hand-edited, always regenerated by spec-spine compile / spec-spine index.
• Generated files in any directory where the build tool writes output: editing by hand is a violation.
• Framework wiring, entry points, and middleware registries assembled at startup; not always reachable by a static import-graph walk.
• Build/CI scripts under .github/workflows/, .githooks/, or equivalent.
• Test fixtures and utilities.
• Intentional public API exports in library crates or packages meant for downstream consumers.

Dead Code: Safe to Remove (high confidence)

• Unused non-library files with zero inbound references anywhere in the surface.
• Items the linter explicitly flags as unused with no suppression comment.
• Dependencies with zero usage across their owning package.

Dead Code: Needs Review

• Files that look like planned work (check git log for recent additions).
• Ambiguous dependency usage (might be injected at runtime or in a build script).
• Exported items flagged unused inside their package; may be intentional public API.

Duplicate Code: By Priority

• High (>15 lines of business logic, complex conditionals): recommend extraction.
• Medium (10-15 lines of utilities/transformations): consider extraction.
• Low (<10 lines, simple patterns, boilerplate): likely intentional.

Duplicate Code: Keep as Intentional

• Test setup / fixture code (test isolation matters more than DRY).
• Simple idioms under 10 lines (guard clauses, optional chaining patterns, builder boilerplate).
• Parallel module scaffolding that is a deliberate structural choice.

E. Return Structured Report

Return EXACTLY this format:

## Cleanup Analysis Report

### Dead Code Findings

#### Safe to Remove (high confidence)

| Item | Type | Location | Reason |
|------|------|----------|--------|
| ... | unused file / unused dep / dead export | path | why it is safe |

#### Needs Review

| Item | Type | Location | Context |
|------|------|----------|---------|
| ... | ... | path | what investigation revealed |

#### Keeping (intentional / false positive)

| Item | Reason |
|------|--------|
| ... | generated / spec-derived / public-api / entry-point / etc. |

### Duplicate Code Findings

#### High Priority (recommend extraction)

- **[description]** ([N lines])
  - Locations: `file:lines`, `file:lines`
  - Recommendation: extract to [suggested location]

#### Medium Priority (consider extraction)

- **[description]** ([N lines])
  - Locations: `file:lines`, `file:lines`

#### Keep As-Is (intentional)

- **[description]**: [reason]

### Detectors

- Dead-code scanner: {ran / skipped: reason}
- Dependency auditor: {ran / skipped: reason}
- Duplicate detector: {ran / skipped: reason}
- Lint unused findings: {N findings}

### Summary

- **N** items safe to auto-remove
- **N** items need human review
- **N** duplicate blocks worth addressing
- **N** items confirmed as intentional (false positives filtered)

Guidelines for the sub-agent:

• DO read code to understand context before categorizing.
• DO be conservative: better to flag "needs review" than to recommend removing something that breaks the build or violates spec/code coupling.
• DO surface when an optional detector was unavailable; do not silently produce a partial report.
• DO NOT make any changes to any files.
• DO NOT explore the codebase for problems beyond what the detectors find.
• DO NOT create any files.
• DO NOT recommend removing any path claimed by a spec without checking via spec-spine registry show <id>. Spec-claimed paths require their owning spec to change in the same diff (coupling gate).

---

Step 3: Present Results

Display the sub-agent's structured report to the user.

Step 4: Offer Next Steps

After presenting the report, ask the user:

Would you like me to:

1. Remove the "safe to remove" items automatically
2. Walk through the "needs review" items one by one
3. Just keep this report for reference

If option 1 is chosen, remember: any path claimed by a spec (visible via spec-spine registry show <id>) cannot be touched without amending or superseding its owning spec. The coupling gate will refuse the diff otherwise.