---
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-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
compatible-with: claude-code, codex, openclaw
tags: [code-quality, cleanup, refactoring, dead-code, deduplication, type-safety, security]
argument-hint: "[scope] [--dimensions d1,d2,...] [--changed]"
---

# 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](references/dimensions.md)
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](references/safety.md) 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](references/patterns.md)
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](references/tools.md) for language-specific tool commands (knip, madge, ruff, jscpd, etc.).

### Step 4: Build Verification Gate

After each auto-applied dimension:

```bash
# 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](references/dimensions.md) — detection criteria, verification, risk profiles
- [Tool Reference](references/tools.md) — language-specific cleanup tools
- [Grep Patterns](references/patterns.md) — detection patterns by dimension
- [Safety Protocol](references/safety.md) — revert procedures, confidence scoring