rockclaver Refactor Codebase
Restructure incrementally. Never attempt the full restructure in one go — plan phases first, execute one at a time, keep the system working between every step.
Two modes:
- Plan-only: interview → tiny-commit plan → GitHub issue. Stop there.
- Execute: plan (as above or from an existing issue) → run phases one at a time.
Workflow
1. Audit the current structure
Read the codebase for: folder layout and module boundaries, coupling hotspots (files imported everywhere, god modules), mixed responsibilities, test coverage (refactor risk), and build/lint/test tooling. Ask the user what pain they're fixing (navigation, extensibility, build time, team scaling) and what's explicitly out of scope.
2. Define the target and scope
Write a short problem/goal statement with a target folder/module sketch, constraints (stay green, no behavior changes, incremental only), and non-goals. Interview the user on alternatives they considered and hammer out exact scope. If coverage is thin, agree on a Phase 0 safety net (see REFERENCE.md).
3. Break into tiny phases
Follow Fowler: each step small enough that the program is always working. Each phase must be:
- one concern (e.g. "move auth module", "extract shared utils")
- independently verifiable (test/build/lint command named in the phase)
- safe to stop after — no half-migrated state
- ≤ ~20 files; split anything bigger
Per phase, record: what moves/changes, migration strategy (copy-then-delete, re-export shim, codemod — see REFERENCE.md), and the verification command.
Plan-only mode: file the plan as a GitHub issue with sections: Problem Statement, Solution, Commits (tiny, each leaving the codebase working), Decision Document (modules, interfaces, architecture — no file paths or code snippets, they go stale), Testing Decisions, Out of Scope. Return the issue URL and stop.
4. Execute one phase at a time
- Read every file in scope.
- Make the structural change; update all imports (codemod if available).
- Run the phase's verification command.
- Commit (
refactor: phase N – <title>); prefergit mvto preserve history. - Mark the phase complete in the plan, note surprises, report back before the next phase.
Guardrails
- Never change behavior during a structural refactor — note bugs, don't fix them in the same commit.
- Move first, rename in a separate phase.
- Do not chain phases without user confirmation.
References
- REFERENCE.md — architecture patterns, migration strategies, Phase 0 safety net, verification commands, red flags.