nWave-ai 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.
Source: nWave-ai/nWave → nWave/skills/nw-progressive-refactoring/SKILL.md
Also appears in: nWave-ai/nWave/plugins/nw/skills/nw-progressive-refactoring/SKILL.md