Codebase Cleanup

Systematic code cleanup across 11 quality dimensions, ordered by risk. Each finding includes confidence scoring (HIGH/MEDIUM/LOW) and all changes are verified through build/test gates.

Environment Detection

!git rev-parse --show-toplevel 2>/dev/null && echo "---" && git diff --stat HEAD~5 2>/dev/null | tail -5 !ls package.json pyproject.toml Cargo.toml go.mod Makefile 2>/dev/null | head -5 !cat package.json 2>/dev/null | head -3; echo "---"; ls tsconfig.json .eslintrc* 2>/dev/null

Prerequisites

• Git repository with clean working tree (no uncommitted changes)
• Language toolchain installed (Node.js/Python/Go/Rust as applicable)
• Optional: knip, madge, jscpd, ruff, bandit for tool-verified scanning

Overview

This skill orchestrates cleanup across 11 dimensions, each with a dedicated agent. Dimensions are ordered LOW → HIGH risk. See dimensions reference for full detection criteria, verification steps, and risk profiles.

The 11 Dimensions (by risk level):

| # | Dimension | Key | Risk | Auto-apply? | |---|-----------|-----|------|-------------| | 1 | Dead code removal | dead | LOW | Yes (after build) | | 2 | AI slop removal | slop | LOW | Comments only | | 3 | Weak type elimination | types | MED | Yes (after typecheck) | | 4 | Security cleanup | security | MED | Flag only | | 5 | Legacy code removal | legacy | MED | With confirmation | | 6 | Type consolidation | typecons | MED | Yes (after typecheck) | | 7 | Defensive code cleanup | defensive | MED | Flag only | | 8 | Performance optimization | perf | MED | Flag only | | 9 | DRY deduplication | dry | HIGH | Flag only (>=10 lines) | | 10 | Async pattern fixes | async | HIGH | Flag only | | 11 | Circular dep untangling | circular | HIGH | Flag only |

Instructions

Step 1: Safety Checkpoint

Before any changes:

1. Verify clean git state: git status --porcelain must be empty (or stash changes)
2. Record baseline: git rev-parse HEAD as rollback point
3. Run existing tests to confirm green baseline
4. See safety protocol for revert procedures

Step 2: Determine Scope

Parse user arguments to set scope:

• Full codebase (default): scan all source files
• Specific path: cleanup src/api/ — limit to directory
• Changed files only: --changed flag — git diff --name-only HEAD~10
• Specific dimensions: --dimensions dead,types,security
• Single dimension: cleanup --dimensions dry

Exclude from all scans: node_modules/, dist/, build/, .git/, vendor dirs, generated files.

Step 3: Execute Dimensions

For each selected dimension (in risk order):

1. Scan using patterns from patterns reference
2. Score confidence — HIGH (certain, safe to fix), MEDIUM (likely, needs review), LOW (possible, flag only)
3. Apply or flag based on the dimension's auto-apply policy (see table above)
4. Verify — run build/typecheck/tests after each dimension with auto-apply

Use tools reference for language-specific tool commands (knip, madge, ruff, jscpd, etc.).

Step 4: Build Verification Gate

After each auto-applied dimension:

text
# TypeScript/JavaScript
npx tsc --noEmit 2>&1 | tail -20
npm test 2>&1 | tail -30

# Python
python3 -m py_compile <changed_files>
python3 -m pytest --tb=short 2>&1 | tail -30

# General
git diff --stat  # Show what changed

If verification fails, revert that dimension: git checkout -- .

Step 5: Generate Report

Produce a cleanup report in this format:

## Cleanup Report

**Scope:** [path or "full codebase"]
**Baseline:** [commit hash]
**Dimensions:** [list of dimensions run]

### Summary
| Dimension | Findings | Applied | Flagged | Confidence |
|-----------|----------|---------|---------|------------|
| dead      | 12       | 10      | 2       | HIGH       |
| types     | 8        | 8       | 0       | HIGH       |
| security  | 3        | 0       | 3       | MEDIUM     |

### Changes Applied
- [file:line] description of change

### Flagged for Review
- [file:line] description + reasoning + suggested fix

### Lines Removed: N | Lines Modified: N | Files Touched: N

Output

A structured cleanup report containing:

• Summary table with findings per dimension (count, applied, flagged, confidence)
• List of changes applied with file:line references
• List of flagged items with reasoning and suggested fixes
• Stats: lines removed, lines modified, files touched

Error Handling

| Error | Recovery | |-------|----------| | Dirty git state | Ask user to commit or stash first | | Build fails after cleanup | git checkout -- . to revert dimension | | No test command found | Skip verification, flag all as "unverified" | | Tool not installed | Fall back to grep patterns (see references/patterns.md) | | Confidence unclear | Default to flag-only, never auto-apply |

Examples

Full cleanup:

/cleanup-code

Security-focused:

/cleanup-code --dimensions security,async

Changed files only:

/cleanup-code src/api/ --changed

Single dimension deep-dive:

/cleanup-code --dimensions dead

Resources

• All 11 Dimensions — detection criteria, verification, risk profiles
• Tool Reference — language-specific cleanup tools
• Grep Patterns — detection patterns by dimension
• Safety Protocol — revert procedures, confidence scoring