cleanup-code

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 <[e-mail]>
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:

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

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