refactor
Refactor & Clean Up
Improve a codebase's internal structure — removing what's unused or stale, reorganising what's tangled — without changing what it does. That behaviour-preserving constraint is the whole game: a refactor that alters observable behaviour is a bug, not a cleanup.
Two modes, same rules:
- In-flight (during a project): opportunistic and small, scoped to the area you're already working in — leave it tidier than you found it, but don't let a one-line fix sprawl into a rewrite.
- Dedicated pass (after a feature or project): inventory, prioritise, then execute in safe increments.
Reason before you touch anything
This is not a shotgun. Every removal or restructuring needs a reason you could say out loud — what's wrong now, why the change is better, and what might break. If you can't articulate that, don't make the change; "it felt untidy" isn't a reason. For anything beyond the trivial, surface the plan first — what you intend to change and why — and let the user weigh in before you execute, especially for deletions and moves that touch many files. A pile of unexplained diffs is worse than the mess you started with, because now no one can tell the considered changes from the reflexive ones. Work in small, reviewable batches with the reasoning attached, not one sweeping pass.
Safety first — this is deletion and restructuring; it can break things
- Have a safety net before you cut. Tests are how you prove behaviour didn't change — run the relevant suite before and after each step. If coverage is thin around what you're touching, add a characterization test first (one that pins current behaviour), or tread conservatively and lean on the user to verify.
- Verify "unused" before deleting. "I can't see it used" is not proof. Search the whole repo for every reference, including what static search misses: string/dynamic references, reflection, dependency injection, config and env files, build/CI scripts, templates and routes, serialized data. And ask whether it's part of a public API or consumed by another repo — unused here doesn't mean unused everywhere.
- Small, reversible steps; commit each. One logical change per commit with tests green in between, so anything can be bisected and reverted. (Use the
conventional-commitsskill for messages — usuallyrefactor:orchore:.) - Delete, don't comment out. Version control already remembers the old code; commented-out blocks and "keep just in case" cruft are exactly the stale noise this skill removes. Deleting is safe because git has it.