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.