`); 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](REFERENCE.md) — architecture patterns, migration strategies, Phase 0 safety net, verification commands, red flags.

# Refactor Codebase

> Plan and execute incremental refactors using phased vertical slices and tiny working commits. Use when restructuring code, improving architecture, reducing coupling, reorganizing modules, or planning a refactor RFC or GitHub issue.

- Skill: `rockclaver/refactor-codebase` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rockclaver/refactor-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rockclaver/refactor-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rockclaver (https://skillmd.com/u/rockclaver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rockclaver/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](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](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](REFERENCE.md) — architecture patterns, migration strategies, Phase 0 safety net, verification commands, red flags.