SKILL

---
name: refactor-planner
description: Plan a safe step-by-step refactor. Expand-then-contract; every step ships green; rollback per step.
category: architecture
version: 0.1.0
triggers: ["refactor", "migrate", "restructure", "split this file", "rewrite", "untangle"]
applies_to: [openclaw, cursor, claude-code]
---

# Refactor Planner

You take a "we should refactor X" request and turn it into a sequence of small, safe,
shippable steps. The default for refactors is **expand-then-contract**, the same pattern
that keeps database migrations safe: introduce the new shape alongside the old, switch
consumers piece by piece, remove the old shape only after everything is on the new one.

The most common refactor failure isn't getting the design wrong — it's the all-at-once
rewrite that breaks 12 things and gets reverted. This skill exists to prevent that.

## When to use

- "Split this 1,200-line file into modules"
- "Move from React Context to Zustand" (or any library swap)
- "Rename / restructure this module"
- "Extract this duplicated logic"
- "Collapse these three near-duplicate components"
- "Migrate from REST to tRPC" / "from Pages Router to App Router" / similar
- After `review/frontend-audit` or `review/database-review` produces findings that need
  multi-step execution

Do not invoke for:
- One-line edits or trivial renames (just do them)
- Greenfield work (use `architecture/frontend-feature` / `architecture/backend-api`)
- The actual code-writing — this skill produces the plan, the architecture skills execute

## Scope

In scope:
- Step-by-step plan with each step independently shippable
- Risk and rollback strategy per step
- Order of operations to keep the codebase green throughout
- Estimated size of each step (S/M/L)
- Dependencies between steps
- Tests / verification needed at each step
- What stays in scope vs explicit out-of-scope

Out of scope:
- Executing the plan — refactor-planner produces the plan, not the diff
- Architectural redesign that hasn't been agreed on — confirm the *destination* with the
  user before planning the journey
- Renames / cleanups outside the stated scope — propose as follow-ups, don't bundle

## Inherits

- [`meta/engineering-principles`](../../meta/engineering-principles/SKILL.md) — DRY, file size, single responsibility shape *what* is being refactored toward.
- [`meta/reuse-before-create`](../../meta/reuse-before-create/SKILL.md) — a refactor that introduces brand-new abstractions instead of consolidating into existing ones is the failure mode this skill exists to prevent; the destination must reuse before it creates.
- [`meta/token-discipline`](../../meta/token-discipline/SKILL.md) — read the target area, not the whole repo.
## Token discipline (specific)

- Read the **specific area being refactored**, not the whole codebase.
- Read 1–2 sibling modules / patterns to understand what "good" looks like in this project.
- Read the project's existing test setup once — knowing what tests cover the area
  determines how aggressive each step can be.
- Skip historical commits unless the refactor is explicitly to undo a past change.
- Do NOT read every consumer of a function before planning — list them via grep, sample
  the most representative ones, plan the migration shape.

## The cardinal rule: every step ships green

A step is **shippable** when:
- The codebase compiles / typechecks
- Tests pass
- The application works as before from a user's perspective
- It can be merged and deployed without breaking anything

A plan that has a "WIP" step in the middle has failed. If you can't see how to keep the
build green, the step is too big — split it.

## The expand-then-contract pattern

Borrowed from database migration discipline, applied to code: