Memstack Development Refactor Planner

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

| Context | Status | |---------|--------| | User says "refactor", "refactoring plan", "code cleanup" | ACTIVE | | User says "tech debt", "god class", "tight coupling", "reduce duplication" | ACTIVE | | User wants to improve existing code structure without changing behavior | ACTIVE | | User wants to write a new feature | DORMANT — use Feature Spec | | User wants to change database schema | DORMANT — use Migration Planner |

Common Mistakes

| Mistake | Why It's Wrong | |---------|---------------| | "Big bang rewrite" | Rewriting everything at once introduces cascading failures. Incremental changes are safer and shippable. | | "Refactor without tests" | No test coverage = no safety net. Add characterization tests BEFORE touching code. | | "Refactor and add features simultaneously" | Mixing behavior changes with structural changes makes bugs impossible to isolate. Separate commits. | | "No measurable goal" | "Clean up the code" is vague. Define metrics: reduce file from 800 to 200 lines, eliminate 5 duplicate blocks, etc. | | "Skip the risk assessment" | A function called by 47 files is higher risk than a utility used in 2. Assess blast radius first. |

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):

| Smell | Detection | Severity | |-------|----------|----------| | Long method | Function >30 lines or >3 levels of nesting | Medium | | Large class / God object | Class >300 lines or >10 public methods | High | | Long parameter list | Function takes >4 parameters | Medium | | Primitive obsession | Raw strings/numbers instead of domain types | Low | | Data clumps | Same group of variables passed together repeatedly | Medium |

Couplers (too connected):

| Smell | Detection | Severity | |-------|----------|----------| | Feature envy | Method uses another class's data more than its own | Medium | | Inappropriate intimacy | Classes access each other's private internals | High | | Message chains | a.getB().getC().getD().doThing() — chain >2 deep | Medium | | Middle man | Class delegates nearly everything to another class | Low |

Dispensables (unnecessary):

| Smell | Detection | Severity | |-------|----------|----------| | Dead code | Unreachable code, unused variables, commented-out blocks | Low | | Duplicate code | Same logic in 2+ places (exact or structural) | High | | Speculative generality | Abstractions, interfaces, or config for cases that don't exist | Medium | | Lazy class | Class does too little to justify its existence | Low |

Change preventers (hard to modify):

| Smell | Detection | Severity | |-------|----------|----------| | Divergent change | One class changed for many different reasons | High | | Shotgun surgery | One change requires edits across many files | High | | Parallel inheritance | Creating a subclass in one hierarchy requires one in another | Medium |

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:

| Factor | Low Risk | Medium Risk | High Risk | |--------|----------|------------|-----------| | Dependents | 0-2 callers | 3-10 callers | 10+ callers | | Test coverage | >80% covered | 40-80% covered | 80% test coverage

Step 4: Select Refactoring Patterns

Match each smell to the appropriate pattern:

Extraction patterns:

| Pattern | Use When | Before → After | |---------|---------|----------------| | Extract Method | Long method, duplicated logic block | Inline code → Named function | | Extract Class | God class, divergent change | One class → Two focused classes | | Extract Interface | Tight coupling, testing difficulty | Concrete dependency → Interface + implementation | | Extract Variable | Complex expression, magic numbers | `if (a > 86400 && b 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:

```markdown
## 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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cwinvestments
• Source: cwinvestments/memstack
• License: MIT
• Homepage: https://memstack.pro

Install and usage instructions live in the source repository linked above.