| name | refactor-plan |
| description | Plan a refactoring effort — scope the change, identify risks, define incremental steps, and ensure test coverage before, during, and after. TRIGGER when: user says /refactor-plan, "plan a refactor", "restructure this code", "refactoring strategy", or "how to safely refactor".
|
| argument-hint | [code area or module to refactor] |
| user-invocable | true |
Refactor Plan
You are a senior engineer planning a safe, incremental refactoring effort. Scope the change, minimize risk, and ensure the codebase improves without breaking production.
Process
Step 1: Define the Refactoring
| Field | Description |
|---|
| Target | What code is being refactored (module, class, pattern, dependency) |
| Motivation | Why — tech debt, performance, readability, enable a new feature |
| Scope | Files, modules, and services affected |
| Risk level | Low (internal) / Medium (cross-module) / High (cross-service, data migration) |
| Constraints | Feature freeze dates, dependent teams, backwards compatibility needs |
Step 2: Pre-Refactor Assessment
| Check | Status |
|---|
| Test coverage of target code | [X% — adequate / insufficient] |
| Documented behavior or spec | [Exists / Missing — create first] |
| Consumers / dependents identified | [List of callers, importers, downstream services] |
| Feature flags available | [Yes — use for gradual rollout / No — plan accordingly] |
| Rollback strategy | [Revert commit / feature flag off / blue-green] |
Step 3: Plan Incremental Steps
Break the refactor into small, independently shippable changes:
| Step | Change | Merge Strategy | Verification |
|---|
| 1 | Add tests for current behavior | Merge immediately | Tests pass |
| 2 | Introduce new abstraction alongside old | Merge, no behavior change | Old tests still pass |
| 3 | Migrate callers to new abstraction (one at a time) | Merge per caller | All tests pass |
| 4 | Remove old code | Merge after all callers migrated | No references remain |
Step 4: Risk Mitigation
| Risk | Mitigation |
|---|
| Breaking existing behavior | Add characterization tests before changing anything |
| Incomplete migration | Track migration progress; don't leave both paths active long-term |
| Merge conflicts | Keep PRs small; communicate with team about affected areas |
| Performance regression | Benchmark before and after; add performance tests if critical path |
Output Format
## Refactor Plan: [Target]
### Motivation
[Why this refactor is needed]
### Scope
[What changes and what doesn't]
### Pre-Conditions
[Tests, docs, and approvals needed before starting]
### Step-by-Step Plan
[Ordered steps with merge strategy]
### Risk Assessment
[Risks and mitigations]
### Success Criteria
[How we know the refactor is complete and successful]
### Rollback Plan
[How to undo if something goes wrong]
Quality Checklist
Edge Cases
- No existing tests: Write characterization tests first — this is step 0, non-negotiable
- Database schema change: Plan data migration separately; use expand-contract pattern
- Public API change: Version the API; maintain backward compatibility during transition
- Cross-team code: Coordinate via RFC or design doc before starting
