| name | cleanup-code |
| description | Comprehensive codebase cleanup across 11 quality dimensions: dead code, duplication,
weak types, circular deps, defensive cruft, legacy code, AI slop, type consolidation,
security, performance, and async patterns. Analyzes code with confidence scoring and
verifies changes with build/test gates. Use when codebase has accumulated tech debt,
after major feature work, before releases, or when code quality metrics are declining.
Trigger with "/cleanup-code", "clean up the codebase", "remove dead code", "fix code quality".
|
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash(git:*), Bash(npm:*), Bash(npx:*), Bash(pnpm:*), Bash(python3:*), Bash(tsc:*), Bash(wc:*), Bash(ls:*), AskUserQuestion |
| version | 1.0.0 |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| license | MIT |
| tags | ["code-quality","cleanup","refactoring","dead-code","deduplication","type-safety","security"] |
| argument-hint | [scope] [--dimensions d1,d2,...] [--changed] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
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:
- Verify clean git state:
git status --porcelain must be empty (or stash changes)
- Record baseline:
git rev-parse HEAD as rollback point
- Run existing tests to confirm green baseline
- 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):
- Scan using patterns from patterns reference
- Score confidence — HIGH (certain, safe to fix), MEDIUM (likely, needs review), LOW (possible, flag only)
- Apply or flag based on the dimension's auto-apply policy (see table above)
- 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
| 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
