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):

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:

# 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

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