| name | refactor-plan |
| description | Plan and execute safe refactors — map dependencies, identify risks, break into steps, preserve behavior. Trigger on /refactor-plan, or when planning a refactor, restructuring, or migration. |
| user-invocable | true |
| allowed-tools | Read, Grep, Glob, Bash, Edit |
Refactor Plan
Safe, step-by-step refactoring. The goal is behavior-preserving change.
Workflow
1. Map the territory
- Find all callers/usages of the code being refactored.
- Map dependencies: what depends on this? what does this depend on?
- Identify implicit contracts (return types, error semantics, side effects).
- Search for tests that exercise this code.
2. Risk assessment
- Breaking changes — API signature changes, type changes, removed exports.
- Behavior changes — subtle shifts in error handling, edge case behavior, performance.
- Ripple effects — what else breaks if this changes?
- Test gaps — areas with no test coverage that won't catch regressions.
3. Plan steps
Break the refactor into the smallest possible steps. Each step must:
- Keep the code working (or have its own verification).
- Be independently reviewable.
- Be reversible if something goes wrong.
Example:
Step 1: Extract helper function (preserves original)
Step 2: Migrate caller A to use new helper
Step 3: Migrate caller B
Step 4: Remove old code
4. Execution
- Make one change at a time.
- Verify after each step (compile, test, lint).
- If a step breaks something, roll back that step, not everything.
5. Verification
- Run existing tests — all should still pass.
- Check for behavioral drift (different error messages, different return values).
- Verify edge cases that the original handled.
Anti-patterns
- Big bang refactor — changing everything at once. Don't.
- Refactor + feature in same step — separate concerns.
- Golden hammer — replacing working code with "better" pattern unnecessarily.
- Untrusted refactor — no test coverage but changing critical code anyway.
Experience Log
This skill learns from experience. Mechanism:
- Read
.claude/experience/refactor-plan.md at skill start to benefit from past lessons.
- Write to
.claude/experience/refactor-plan.md after use if you learned something new.
- Format:
YYYY-MM-DD: <lesson> — one line per entry.
- Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.
