---
name: cleaning-existing-codebase
description: Use when the user asks to "clean up", "apply repo-hygiene to", or "fix the hygiene of" an existing codebase — orchestrates the other hygiene skills in a phased, reviewable order rather than firing a 200-file mega-diff
---

# Cleaning an Existing Codebase

## Overview

When a user asks to apply hygiene to an existing project, the seductive path is to start with the visible, mechanical work — docstrings on every file, README rewrite, dep pruning — and ship a 200-file diff. That optimizes for *appearing* thorough; it does NOT optimize for *being* useful. The god-class is usually the real liability; everything else is decoration.

**Core principle:** Survey, propose, get buy-in, work in small reviewable phases. Don't type any cleanup code until the user has approved a plan.

## When To Use

- User asks to "clean up" / "apply repo-hygiene" / "fix the hygiene of" an existing project
- Onboarding into a long-running codebase with obvious hygiene debt
- Tech-debt sprint where hygiene is the focus

## The Process

### 1. Survey

Invoke `repo-hygiene:orienting-to-repo` first. Then quantify the hygiene gaps with concrete numbers:

- **File-size offenders** — files >500 lines, ranked. `find . -type f \( -name '*.py' -o -name '*.ts' -o -name '*.go' \) -exec wc -l {} + | sort -rn | head -20`
- **Docstring coverage** — sample 10 random functions across the codebase; how many have useful docstrings?
- **Test coverage** — count test files vs source files. Run the suite if possible; capture pass rate and gaps.
- **Stale docs** — `git log -1 --format=%cs README.md CHANGELOG.md`; spot-check the README against current code
- **Dead-code candidates** — unused imports, unreferenced exports. Don't act yet; just note.
- **Dep hygiene** — unused deps in `requirements.txt` / `package.json`

Output a concise inventory (~10 bullets with numbers). NOT a 5-page audit.

### 2. Propose a Phased Plan

Show the plan to the user BEFORE touching code. Default ordering, by leverage and dependency:

| Phase | Why this position |
|---|---|
| **0 — Safety net** | Add a smoke test or characterization test for the biggest module BEFORE any refactor. Refactoring without tests is reckless. |
| **1 — Cheap visibility wins** | Fix README, prune unused deps, add CHANGELOG entry. Reviewable in minutes; signals progress. |
| **2 — Architecture** | Decompose god-files / god-classes. Highest risk; needs Phase 0 done first. |
| **3 — Documentation sweep** | Docstrings across files. Last, so docs describe the SHAPE AFTER restructuring, not the moving target. |
| **4 — Test backfill** | Coverage floor on changed code. Use `repo-hygiene:testing-new-code` per file. |

Adjust per the survey. Some projects skip Phase 2 entirely; others ARE Phase 2.

**Wait for explicit user approval before starting Phase 0.**

### 3. Execute, One Phase Per PR

- One phase = one PR. Not one mega-PR.
- Inside a phase, many small commits (one logical change each). Use `repo-hygiene:writing-commit-messages`.
- After each phase, ask the user to review and merge before starting the next.
- If a phase surfaces more issues, NOTE them for a future phase. Don't expand the current scope.

### 4. Use the Other Hygiene Skills as Tools

This skill orchestrates; the others do the work:

- File-size offenders → `repo-hygiene:keeping-files-small` for split proposals
- New code added during refactor → `repo-hygiene:writing-docstrings`
- Public-API changes during refactor → `repo-hygiene:keeping-docs-fresh`
- Each commit → `repo-hygiene:gating-commits` and `repo-hygiene:writing-commit-messages`

## What NOT To Do

| Anti-pattern | Why bad |
|---|---|
| Start with docstring sweep | Highest visibility, lowest leverage. Decorates without fixing. |
| Refactor a god-class before adding tests | Reckless. You'll break things you can't detect. |
| One mega-PR with everything | Unreviewable. Reverting one issue reverts everything. |
| Skip the survey, just start fixing | You'll fix visible issues and miss load-bearing ones. |
| Expand scope mid-phase ("while I'm here…") | Phases stop being focused. Note and move on. |

## Red Flags — STOP

- About to write docstrings on file #1 of 47 with no plan presented
- Refactoring a large file with no test coverage in place first
- Bundling architecture + docs + deps in one commit
- "Appearing thorough" — if your gut says you're optimizing for looking busy over being useful, you are. Pause and check the plan.
- More than ~10 files changed in a single commit during cleanup

## The Bottom Line

A good cleanup leaves the codebase reviewable. A bad cleanup ships a diff so big nobody reads it and no one can revert any single piece of it.