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
- 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
1---2name: cleanup-code3description: |4 Comprehensive codebase cleanup across 11 quality dimensions: dead code, duplication,5 weak types, circular deps, defensive cruft, legacy code, AI slop, type consolidation,6 security, performance, and async patterns. Analyzes code with confidence scoring and7 verifies changes with build/test gates. Use when codebase has accumulated tech debt,8 after major feature work, before releases, or when code quality metrics are declining.9 Trigger with "/cleanup-code-code", "clean up the codebase", "remove dead code", "fix code quality".10allowed-tools: Read, Write, Edit, Glob, Grep, Bash(git:*), Bash(npm:*), Bash(npx:*), Bash(pnpm:*), Bash(python3:*), Bash(tsc:*), Bash(wc:*), Bash(ls:*), AskUserQuestion11version: 1.0.012author: Jeremy Longshore <jeremy@intentsolutions.io>13license: MIT14compatible-with: claude-code, codex, openclaw15tags: [code-quality, cleanup, refactoring, dead-code, deduplication, type-safety, security]16argument-hint: "[scope] [--dimensions d1,d2,...] [--changed]"17metadata:18 source: https://skillmd.com/skills/aibot88/cleanup-code19---2021# Codebase Cleanup2223Systematic code cleanup across 11 quality dimensions, ordered by risk. Each finding includes24confidence scoring (HIGH/MEDIUM/LOW) and all changes are verified through build/test gates.2526## Environment Detection2728!`git rev-parse --show-toplevel 2>/dev/null && echo "---" && git diff --stat HEAD~5 2>/dev/null | tail -5`29!`ls package.json pyproject.toml Cargo.toml go.mod Makefile 2>/dev/null | head -5`30!`cat package.json 2>/dev/null | head -3; echo "---"; ls tsconfig.json .eslintrc* 2>/dev/null`3132## Prerequisites3334- Git repository with clean working tree (no uncommitted changes)35- Language toolchain installed (Node.js/Python/Go/Rust as applicable)36- Optional: `knip`, `madge`, `jscpd`, `ruff`, `bandit` for tool-verified scanning3738## Overview3940This skill orchestrates cleanup across **11 dimensions**, each with a dedicated agent.41Dimensions are ordered LOW → HIGH risk. See [dimensions reference](references/dimensions.md)42for full detection criteria, verification steps, and risk profiles.4344**The 11 Dimensions** (by risk level):4546| # | Dimension | Key | Risk | Auto-apply? |47|---|-----------|-----|------|-------------|48| 1 | Dead code removal | `dead` | LOW | Yes (after build) |49| 2 | AI slop removal | `slop` | LOW | Comments only |50| 3 | Weak type elimination | `types` | MED | Yes (after typecheck) |51| 4 | Security cleanup | `security` | MED | Flag only |52| 5 | Legacy code removal | `legacy` | MED | With confirmation |53| 6 | Type consolidation | `typecons` | MED | Yes (after typecheck) |54| 7 | Defensive code cleanup | `defensive` | MED | Flag only |55| 8 | Performance optimization | `perf` | MED | Flag only |56| 9 | DRY deduplication | `dry` | HIGH | Flag only (>=10 lines) |57| 10 | Async pattern fixes | `async` | HIGH | Flag only |58| 11 | Circular dep untangling | `circular` | HIGH | Flag only |5960## Instructions6162### Step 1: Safety Checkpoint6364Before any changes:65661. Verify clean git state: `git status --porcelain` must be empty (or stash changes)672. Record baseline: `git rev-parse HEAD` as rollback point683. Run existing tests to confirm green baseline694. See [safety protocol](references/safety.md) for revert procedures7071### Step 2: Determine Scope7273Parse user arguments to set scope:7475- **Full codebase** (default): scan all source files76- **Specific path**: `cleanup src/api/` — limit to directory77- **Changed files only**: `--changed` flag — `git diff --name-only HEAD~10`78- **Specific dimensions**: `--dimensions dead,types,security`79- **Single dimension**: `cleanup --dimensions dry`8081Exclude from all scans: `node_modules/`, `dist/`, `build/`, `.git/`, vendor dirs, generated files.8283### Step 3: Execute Dimensions8485For each selected dimension (in risk order):86871. **Scan** using patterns from [patterns reference](references/patterns.md)882. **Score confidence** — HIGH (certain, safe to fix), MEDIUM (likely, needs review), LOW (possible, flag only)893. **Apply or flag** based on the dimension's auto-apply policy (see table above)904. **Verify** — run build/typecheck/tests after each dimension with auto-apply9192Use [tools reference](references/tools.md) for language-specific tool commands (knip, madge, ruff, jscpd, etc.).9394### Step 4: Build Verification Gate9596After each auto-applied dimension:9798```bash99# TypeScript/JavaScript100npx tsc --noEmit 2>&1 | tail -20101npm test 2>&1 | tail -30102103# Python104python3 -m py_compile <changed_files>105python3 -m pytest --tb=short 2>&1 | tail -30106107# General108git diff --stat # Show what changed109```110111If verification fails, revert that dimension: `git checkout -- .`112113### Step 5: Generate Report114115Produce a cleanup report in this format:116117```118## Cleanup Report119120**Scope:** [path or "full codebase"]121**Baseline:** [commit hash]122**Dimensions:** [list of dimensions run]123124### Summary125| Dimension | Findings | Applied | Flagged | Confidence |126|-----------|----------|---------|---------|------------|127| dead | 12 | 10 | 2 | HIGH |128| types | 8 | 8 | 0 | HIGH |129| security | 3 | 0 | 3 | MEDIUM |130131### Changes Applied132- [file:line] description of change133134### Flagged for Review135- [file:line] description + reasoning + suggested fix136137### Lines Removed: N | Lines Modified: N | Files Touched: N138```139140## Output141142A structured cleanup report containing:143- Summary table with findings per dimension (count, applied, flagged, confidence)144- List of changes applied with file:line references145- List of flagged items with reasoning and suggested fixes146- Stats: lines removed, lines modified, files touched147148## Error Handling149150| Error | Recovery |151|-------|----------|152| Dirty git state | Ask user to commit or stash first |153| Build fails after cleanup | `git checkout -- .` to revert dimension |154| No test command found | Skip verification, flag all as "unverified" |155| Tool not installed | Fall back to grep patterns (see references/patterns.md) |156| Confidence unclear | Default to flag-only, never auto-apply |157158## Examples159160**Full cleanup:**161```162/cleanup-code163```164165**Security-focused:**166```167/cleanup-code --dimensions security,async168```169170**Changed files only:**171```172/cleanup-code src/api/ --changed173```174175**Single dimension deep-dive:**176```177/cleanup-code --dimensions dead178```179180## Resources181182- [All 11 Dimensions](references/dimensions.md) — detection criteria, verification, risk profiles183- [Tool Reference](references/tools.md) — language-specific cleanup tools184- [Grep Patterns](references/patterns.md) — detection patterns by dimension185- [Safety Protocol](references/safety.md) — revert procedures, confidence scoring