Refactor Planner — Planning systematic code improvement...

Identifies code smells, assesses refactoring risk, selects appropriate patterns, and builds incremental execution plans with rollback strategies and verification checkpoints.

Activation

When this skill activates, output:

Refactor Planner — Planning systematic code improvement...

Then execute the protocol below.

Context Guard

Common Mistakes

Protocol

Step 1: Gather Refactoring Context

If the user hasn't provided details, ask:

1. Target — what code needs refactoring? (file, module, class, or system)
2. Pain point — what's the specific problem? (hard to modify, duplicated, slow, confusing)
3. Test coverage — does the target code have tests? (yes, partial, none)
4. Constraints — any deadlines, frozen APIs, or deployment concerns?
5. Language/framework — what tech stack?

Step 2: Identify Code Smells

Scan the target code for these smell categories:

Bloaters (too big):

Couplers (too connected):

a.getB().getC().getD().doThing()

Dispensables (unnecessary):

Change preventers (hard to modify):

Code smell report:

## Code Smell Report — [Target]

| # | Smell | Location | Severity | Lines Affected |
|---|-------|----------|----------|---------------|
| 1 | [Smell name] | [file:line] | High/Med/Low | [X] |
| 2 | [Smell name] | [file:line] | High/Med/Low | [X] |
| ... | | | | |

**Summary:** [X] smells found ([X] high, [X] medium, [X] low)
**Estimated scope:** [X] files, [X] lines affected

Step 3: Assess Risk

For each refactoring target, evaluate:

Risk matrix:

Risk score per target:

| Target | Dependents | Coverage | Complexity | Reversibility | Blast Radius | Risk Score |
|--------|-----------|----------|-----------|---------------|-------------|------------|
| [File/Class] | [X] callers | [X]% | Low/Med/High | Easy/Med/Hard | File/Module/System | Low/Med/High |

Risk-based ordering rule:

1. Start with LOW risk, HIGH value targets (quick wins)
2. Then MEDIUM risk targets (with tests added first)
3. HIGH risk targets last (with comprehensive test coverage first)
4. Never refactor HIGH risk targets without >80% test coverage

Step 4: Select Refactoring Patterns

Match each smell to the appropriate pattern:

Extraction patterns:

if (a > 86400 && b < 3)

if (isExpired && belowRetryLimit)

Simplification patterns:

calc(getX(), getY())

calc()

fn(x, y, z, w)

fn(config)

temp = calc(); use(temp)

use(calc())

Structural patterns:

extends Base

has Base

Pattern selection table:

| # | Smell | Pattern | Target | Estimated Effort |
|---|-------|---------|--------|-----------------|
| 1 | [Smell] | [Pattern] | [file:line] | [X] hours |
| 2 | [Smell] | [Pattern] | [file:line] | [X] hours |

Step 5: Build Execution Plan

Structure the refactoring into safe, incremental phases:

Phase template:

## Refactoring Plan — [Target]

### Phase 0: Safety Net (do this first)
- [ ] Add characterization tests for current behavior
- [ ] Verify all existing tests pass
- [ ] Create a feature branch: `refactor/[target-name]`
- [ ] Document current behavior snapshot

### Phase 1: Quick Wins (low risk, high value)
**Target:** [Smell → Pattern]
- [ ] Step 1: [Specific action]
- [ ] Step 2: [Specific action]
- [ ] Verify: Run tests, confirm no behavior change
- [ ] Commit: `refactor: [description]`

### Phase 2: Core Improvements (medium risk)
**Target:** [Smell → Pattern]
- [ ] Step 1: [Specific action]
- [ ] Step 2: [Specific action]
- [ ] Verify: Run tests, confirm no behavior change
- [ ] Commit: `refactor: [description]`

### Phase 3: Structural Changes (higher risk)
**Target:** [Smell → Pattern]
- [ ] Step 1: [Specific action]
- [ ] Step 2: [Specific action]
- [ ] Verify: Run full test suite + manual smoke test
- [ ] Commit: `refactor: [description]`

### Verification Checkpoints
After each phase:
1. All tests pass (unit + integration)
2. No behavior change (same inputs → same outputs)
3. Metrics improved (lines reduced, complexity lowered)
4. Code review approved (if team)

Effort estimation guide:

Step 6: Define Rollback Strategy

For each phase, document how to reverse:

## Rollback Strategy

| Phase | Rollback Method | Time to Revert |
|-------|----------------|---------------|
| Phase 1 | `git revert [commit]` | <5 min |
| Phase 2 | `git revert [commit]` | <5 min |
| Phase 3 | `git revert [commit]` + re-run migrations if applicable | <15 min |

**Abort criteria (stop refactoring if):**
- Test failures that can't be explained within 30 minutes
- Performance regression >10% on critical paths
- Deadline pressure requires shipping current work
- Discovery of architectural issues requiring design discussion

Step 7: Measure Results

Define before/after metrics:

## Refactoring Metrics

| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Lines of code (target) | [X] | [X] | -[X]% |
| Cyclomatic complexity | [X] | [X] | -[X]% |
| Number of methods | [X] | [X] | [+/-X] |
| Average method length | [X] lines | [X] lines | -[X]% |
| Duplicate code blocks | [X] | [X] | -[X] |
| Test coverage | [X]% | [X]% | +[X]% |
| Number of dependencies | [X] | [X] | -[X] |

Output Format

# Refactoring Plan — [Target]

## Code Smell Report
[From Step 2 — smells identified with severity and location]

## Risk Assessment
[From Step 3 — risk matrix for each target]

## Pattern Selection
[From Step 4 — matched patterns with estimated effort]

## Execution Plan
[From Step 5 — phased plan with verification checkpoints]

## Rollback Strategy
[From Step 6 — revert method per phase + abort criteria]

## Success Metrics
[From Step 7 — before/after targets]

Completion

Refactor Planner — Complete!

Target: [Target name]
Smells found: [X] ([X] high, [X] medium, [X] low)
Phases: [X]
Estimated effort: [X] hours
Risk level: [Overall Low/Medium/High]
Patterns applied: [List]

Next steps:
1. Add characterization tests for current behavior (Phase 0)
2. Create feature branch: refactor/[target-name]
3. Execute Phase 1 (quick wins) and verify tests pass
4. Continue through phases, committing after each
5. Measure before/after metrics and document improvements

Level History

• Lv.1 — Base: 4 code smell categories (bloaters, couplers, dispensables, change preventers) with 16 specific smells, 5-factor risk matrix, 12 refactoring patterns in 3 groups (extraction, simplification, structural), phased execution plan template, rollback strategy with abort criteria, before/after metrics tracking. (Origin: MemStack Pro v3.2, Mar 2026)