nw-progressive-refactoring

# Progressive Refactoring (Refactoring Priority Premise)

Based on the Refactoring Priority Premise (RPP) from the Alcor Academy curriculum.

## RPP Levels (L1-L6)

Execute levels in mandatory sequence. Lower levels before higher.

### Level 1: Foundation (Readability)
Focus: eliminate clutter, improve naming, remove dead code.
Smells: Dead Code | Comments (how-comments) | Speculative Generality | Lazy Class.
Transformations: Rename | Extract (variables/constants) | Safe Delete.
Impact: 80% of readability improvement value.
Test smells: Obscure Test | Hard-Coded Test Data | Assertion Roulette.

### Level 2: Complexity Reduction (Simplification)
Focus: method extraction, duplication elimination.
Smells: Long Method | Duplicate Code | Complex Conditionals.
Transformations: Extract (methods) | Move (common code).
Impact: 20% additional readability improvement.
Test smells: Eager Test | Test Code Duplication | Conditional Test Logic.

### Level 3: Responsibility Organization
Focus: class responsibilities, coupling reduction.
Smells: Large Class | Feature Envy | Inappropriate Intimacy | Data Class | Divergent Change | Shotgun Surgery.
Transformations: Move | Extract (classes).
Test smells: Test Class Bloat | Mystery Guest | General Fixture.

### Level 4: Abstraction Refinement
Focus: parameter objects, value objects, abstractions.
Smells: Long Parameter List | Data Clumps | Primitive Obsession | Middle Man.
Transformations: Extract (objects) | Inline | Move.

### Level 5: Design Pattern Application
Focus: Strategy | State | Command patterns.
Smells: Switch Statements | complex state-dependent behavior.
Transformations: Extract (interfaces) | Move (to polymorphic structure).

### Level 6: SOLID++ Principles
Focus: SOLID principles, architectural patterns.
Smells: Refused Bequest | Parallel Inheritance Hierarchies.
Transformations: Extract (interfaces) | Move (responsibilities) | Safe Delete (violations).

### RPP Cascade Rule
MANDATORY: complete each level fully before moving to the next. Do not skip levels.
80% of refactoring value comes from readability improvements (L1-L2).
Focus effort on L1-L2 for maximum impact. Move to higher levels only when needed.

### Fast-Path for Small Changes
When GREEN phase produced < 30 LOC of new production code:
- Quick scan for obvious naming/duplication issues (2-3 min max)
- Mark COMPLETED with note "fast-path: <30 LOC"

### L4-L6 Timing
L4-L6 architecture refactoring runs at orchestrator Phase 2.25 (once after all steps complete), not during each TDD inner loop.

---

## 22 Code Smell Taxonomy

### Bloaters
| Smell | Detection | Treatment | Level |
|-------|-----------|-----------|-------|
| Long Method | >20 lines, multiple responsibilities | Extract Method, Compose Method | L2 |
| Large Class | >300 lines, too many fields | Extract Class, Extract Subclass | L3 |
| Primitive Obsession | Raw strings for domain concepts, magic numbers | Replace Data Value with Object | L4 |
| Long Parameter List | >=4 parameters | Introduce Parameter Object | L4 |
| Data Clumps | Same parameter groups repeated | Extract Class, Introduce Parameter Object | L4 |

### Object-Orientation Abusers
| Smell | Detection | Treatment | Level |
|-------|-----------|-----------|-------|
| Switch Statements | Switch on type, complex if-else chains | Replace with Polymorphism, Strategy | L5 |
| Temporary Field | Fields empty most of the time | Extract Class, Null Object | L3 |
| Refused Bequest | Subclass doesn't support parent interface | Push Down, Replace Inheritance with Delegation | L6 |
| Alternative Classes, Different Interfaces | Same function, different names | Rename Method, Extract Superclass | L3 |

### Change Preventers
| Smell | Detection | Treatment | Level |
|-------|-----------|-----------|-------|
| Divergent Change | One class changed for different reasons | Extract Class | L3 |
| Shotgun Surgery | Change requires many small changes to many classes | Move Method, Move Field, Inline Class | L3 |
| Parallel Inheritance Hierarchies | Creating subclass requires another subclass | Move Method, Move Field | L6 |

### Dispensables
| Smell | Detection | Treatment | Level |
|-------|-----------|-----------|-------|
| Comments (how-comments) | Comments explaining complex code | Extract Method, Rename Method | L1 |
| Duplicate Code | Same code structure in multiple places | Extract Method, Pull Up Method | L2 |
| Lazy Class | Class with few methods, little functionality | Inline Class, Collapse Hierarchy | L1 |
| Data Class | Only fields and getters/setters | Move Method, Encapsulate Field | L3 |
| Dead Code | Unused variables, methods, classes | Delete unused code | L1 |
| Speculative Generality | Abstractions for future features | Collapse Hierarchy, Inline Class | L1 |

### Couplers
| Smell | Detection | Treatment | Level |
|-------|-----------|-----------|-------|
| Feature Envy | Method uses another object's data more than its own | Move Method, Extract Method | L3 |
| Inappropriate Intimacy | Classes know too much about each other | Move Method, Extract Class, Hide Delegate | L3 |
| Message Chains | a.getB().getC().getD() | Hide Delegate, Extract Method | L3 |
| Middle Man | Class only delegates to another | Remove Middle Man, Inline Method | L4 |

---

## 5 Atomic Transformations

### Rename
Change name without changing behavior. Applies to: variables | methods | classes | fields | parameters.
Safety: use IDE refactoring tools, verify all references updated, run tests, commit.

### Extract
Take portion of code, create new element. Applies to: methods | classes | variables | constants | interfaces.
Safety: identify code, create element with intention-revealing name, move code, replace original with call, test, commit.

### Inline
Replace code element with its implementation. Applies to: methods | variables | classes.
Safety: verify no side effects, replace all calls, remove original, test, commit.

### Move
Relocate code element to different scope or class. Applies to: methods | fields | classes.
Safety: check dependencies, create in target, update references, remove from source, test, commit.

### Safe Delete
Remove unused code elements. Applies to: methods | fields | classes | parameters | variables.
Safety: verify truly unused, check for dynamic references, remove, compile and test, commit.

---

For test code smells (9 smells with detection patterns and before/after examples), load the test-refactoring-catalog skill.

---

## Refactoring Techniques Catalog (Fowler)

### Composing Methods
- **Extract Function**: workhorse refactoring. If you need a comment to explain a block, extract to method with that explanation as name.
- **Compose Method** (Kerievsky): transform method into composition at same abstraction level. Repeated Extract Function until body reads like pseudocode.
- **Inline Function**: remove unnecessary abstraction when body is as clear as name. Use in "inline then re-extract" dance.
- **Replace Temp with Query**: replace temporary variable with method call.

### Moving Features
- **Move Function**: relocate to more appropriate class/module. Addresses Feature Envy.
- **Move Field**: move field to class that uses it most.
- **Extract Class**: decompose Large Class by moving related data+methods to new class.

### Organizing Data
- **Replace Data Value with Object**: turn simple data value into full object. Addresses Primitive Obsession.
- **Introduce Parameter Object**: group parameters that go together. Addresses Long Parameter List.
- **Encapsulate Variable/Collection**: protect data from direct access. Return unmodifiable view.

### Simplifying Conditionals
- **Decompose Conditional**: extract condition + branches to named functions showing intent.
- **Guard Clauses**: handle exceptional cases early, return, leave main logic unnested.
- **Replace Conditional with Polymorphism**: replace type-based conditionals with class hierarchy.

### Refactoring to Patterns (Kerievsky)
Don't design patterns upfront - refactor toward them as needs emerge:
- Extract Method repeatedly -> Compose Method -> Template Method
- Encapsulate Field + Move Method -> Strategy
- Extract Class + Move Method -> Decorator

### Key Principles
- Behavior-preserving: if behavior changes, it's not refactoring
- Automated refactoring (IDE) preferred over manual
- Cohesion and clarity over line-count thresholds
- Function size: Single Responsibility + Consistent Abstraction + Self-Documenting names

---

For complex architectural refactoring, load the mikado-method skill.