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

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

1. Read every file in scope.
2. Make the structural change; update all imports (codemod if available).
3. Run the phase's verification command.
4. Commit (refactor: phase N – <title>); prefer git mv to preserve history.
5. 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.