refactor-plan

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:

1. Keep the code working (or have its own verification).
2. Be independently reviewable.
3. 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.