Cleaning existing codebase

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.