code-cleanup

name	code-cleanup
description	Dead code detection and removal using knip (recommended) or standard tooling. Use when removing unused imports, variables, or dead files.

SKILL: Code Cleanup

Purpose: Dead code detection and removal using knip (recommended) or ESLint/TypeScript fallback Target: Coder Agent, cleanup commands

---

⚠️ EXECUTION DIRECTIVE

IMPORTANT: Execute ALL steps IMMEDIATELY and AUTOMATICALLY.

Core Philosophy: Auto-apply Low/Medium risk | High-risk: User confirmation | Safe flags: --dry-run, --apply | Verification after each batch

---

Quick Start

When to Use This Skill

• Remove unused import statements
• Detect and delete dead files (zero references)
• Clean up codebase after refactoring

Usage

MODE="${1:-files}"  # imports|files|all
SCOPE="${2:-repo}"  # repo|path=...

---

.cleanup-ignore Support

Create .cleanup-ignore file in project root:

# Core infrastructure
**/auth/**
**/database/**
**/*.config.*

# Entry points
**/index.ts
**/main.ts

# Generated files
**/generated/**
**/*.gen.ts

Loading order: Read .cleanup-ignore → Apply patterns → Exclude protected files

---

Step 1: Detect Dead Code

Detection Tools

Recommended: knip

npx knip                    # Full analysis
npx knip --reporter compact # Concise output
npx knip --fix              # Auto-fix safe issues

Fallback: Standard tooling

grep -r "import.*from" src/ --include="*.ts"  # Unused imports
find src/ -name "*.ts" -exec grep -l "{}" \;   # Dead files

Dead File Detection Procedure

EXCLUDE="--glob '!*.test.ts' --glob '!*.spec.ts' --glob '!index.ts'"
rg --files $EXCLUDE src/ | while read file; do
  refs=$(rg -c "from.*['\"]$file" src/ || echo 0)
  [ "$refs" -eq 0 ] && echo "$file: 0 references"
done

---

Step 2: Risk Classification (4-Level)

Risk	File Types	Action
SAFE	Tests (*.test.*), mocks, fixtures	auto-remove
CAUTION	Utils, helpers, internal modules	auto-remove + prompt
WARNING	Components, services, hooks	tests pass first
DANGER	Auth, database, config, API routes	require --force

classify_risk() {
  case "$1" in
    *.test.* | *.spec.* | */__mocks__/*) echo "SAFE" ;;
    */utils/* | */helpers/* | */lib/*) echo "CAUTION" ;;
    */components/* | */services/* | */hooks/*) echo "WARNING" ;;
    */auth/* | */database/* | *.config.* | */api/*) echo "DANGER" ;;
    *) echo "CAUTION" ;;
  esac
}

---

Step 3: Cleanup with Confirmation

detect_dead_files() {
  rg --files --glob '!*.test.ts' src/ | while read file; do
    refs=$(rg -c "from.*['\"]$file" src/ || echo 0)
    [ "$refs" -eq 0 ] && echo "$file|$(classify_risk "$file")"
  done
}
# Auto-apply SAFE/CAUTION/WARNING, confirm DANGER
detect_dead_files | while IFS='|' read -r file risk; do
  if [ "$risk" = "DANGER" ]; then
    echo "DANGER: $file [A) Delete / B) Skip]"
    read -p "Choose: " choice
    [ "$choice" = "A" ] && rm "$file"
  else
    echo "Auto-deleting: $file" && rm "$file"
  fi
done

---

Step 4: Verification

npm test || { echo "❌ Tests failed"; git checkout -- .; exit 1; }
npm run type-check || { echo "❌ Type check failed"; git checkout -- .; exit 1; }
npm run lint || { echo "❌ Lint failed"; git checkout -- .; exit 1; }
echo "✅ All checks passed"

Rollback on failure: git checkout -- .

---

Step 5: Execution Logging

mkdir -p .cleanup
LOG_FILE=".cleanup/$(date +%Y-%m-%d_%H%M%S).log"
if [ "$DELETED_COUNT" -gt 0 ]; then
  echo "# Cleanup Log - $(date +%Y-%m-%d)" > "$LOG_FILE"
  echo "## Deleted: $DELETED_COUNT files" >> "$LOG_FILE"
  echo "✓ Log saved: $LOG_FILE"
fi

stdout: ✅ Cleanup Complete - Deleted: 5 files, Tests: PASS

---

Parallel Detection (Optional)

Task A: npx knip --reporter json
Task B: eslint . --report-unused-disable-directives --format json
Task C: tsc --noUnusedLocals --noEmit 2>&1
# Merge: Deduplicate → Apply .cleanup-ignore → Classify by risk

Safe: All detection commands are read-only.

---

Pre-flight Safety

[ -n "$(git status --porcelain)" ] && { echo "⚠️  Working directory not clean"; exit 2; }

---

Troubleshooting

False Positives: Dynamic imports, runtime requires | Test Failures: git checkout -- .

---

Best Practices

• Run tests after each batch: Max 10 deletions per batch | Conservative exclusion: Exclude index., main., .config. | Risk-based approach: Auto-apply Low/Medium, confirm High | Clean working directory: Block if modified/staged files exist

---

Further Reading

Internal: @.claude/skills/code-cleanup/REFERENCE.md | @.claude/skills/vibe-coding/SKILL.md

External: ESLint Unused Vars Rule | knip | ⚠️ SAFETY: Auto-rollback on verification failure