Codebase cleanup — 8-pass refactor

Eight independent specialist passes over a codebase, each scoped to one quality concern. Designed to be run as 8 separate subagent sessions (or sequentially in one) so each pass gets a clean context window and can't be tempted to bleed into another's territory.

Every pass follows the same three-phase protocol — see reference/protocol.md. The recommended pass ordering and why is in reference/pass-ordering.md.

When to use

• "Clean up the codebase" / "do a tech-debt pass"
• "Refactor for quality before we ship"
• "Find and remove dead code / AI slop / weak types"
• Onboarding a codebase and wanting to know what's actually load-bearing
• Pre-1.0 / pre-release quality sweep
• Periodic (quarterly) hygiene runs

When NOT to use

• Narrow targeted asks ("remove this one function", "fix this one type")
• Net-new feature work
• Tight deadline / minimum-viable-fix scenarios — this is a deliberate, careful sweep
• Codebases under active heavy refactor by humans (the passes will fight in-flight work)

The 8 passes

Run in this order (rationale in reference/pass-ordering.md). Each links to the full subagent prompt:

1. AI slop & stale comments → reference/passes/01-ai-slop.md Remove generated noise, in-motion-work comments, larp, unhelpful boilerplate.
2. Legacy / deprecated / fallback code → reference/passes/02-legacy-removal.md Remove dead branches, deprecated APIs, fallback paths that no longer fall back to anything live.
3. Unused code → reference/passes/03-unused-code.md knip-class analysis: exports/files/deps that nothing imports.
4. Circular dependencies → reference/passes/04-circular-deps.md madge-class analysis: untangle import cycles.
5. Weak types → reference/passes/05-weak-types.md Replace any / unknown / Object / dynamic / interface{} with real types backed by research.
6. Type consolidation → reference/passes/06-type-consolidation.md Find duplicated / near-duplicated type definitions and unify.
7. Defensive programming → reference/passes/07-defensive-programming.md Remove try/catch and null-guards that don't handle a real input boundary.
8. DRY / dedup → reference/passes/08-dry.md Consolidate duplicated logic only where it reduces complexity (not the other way).

Tools

Each pass spec lists the tooling it expects (knip, ts-unused-exports, madge, jscpd, language-specific linters, etc.). The skill ships no scripts — orchestration happens in the calling agent runtime, which already has bash/edit/grep/etc.

Reference

• reference/protocol.md — the 3-phase research/assess/implement protocol every pass follows
• reference/pass-ordering.md — why this order, and which passes can run in parallel
• reference/passes/*.md — one self-contained subagent prompt per pass