/refactor-planner

name: memstack-development-refactor-planner
description: "Use this skill when the user says 'refactor', 'refactoring plan', 'code cleanup', 'reduce duplication', 'simplify code', 'tech debt', 'god class', 'tight coupling', or needs to systematically improve existing code. Identifies targets, assesses risk, and builds incremental execution plans. Do NOT use for writing new features or database migrations."
version: 1.0.0
license: "Proprietary, MemStack™ Pro by CW Affiliate Investments LLC. See LICENSE.txt"

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 | <40% covered | | **Complexity** | Simple extraction | Cross-file changes | Architectural change | | **Reversibility** | Easy to revert | Requires migration | Data format changes | | **Blast radius** | Single file | Single module | Cross-module |

**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