refactor-codebase
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).