refactoring

name

refactoring

description

Use proactively at the end of each implementation slice when project workflow requires it, or when a user asks to refactor, simplify, clean up, or restructure code while preserving behavior. Do not wait for an explicit user request if the workflow already mandates a post-implementation pass (features and bug fixes). Applies Martin Fowler style refactoring discipline and points to one reference file per refactoring from the official catalog.

Refactoring Fowler

Use this skill when the goal is to improve code structure without changing observable behavior.

When your repository agent guide or team workflow mandates it, run this skill as a required pass after each implementation slice finishes green—feature or bug fix—before calling that slice complete or moving to the next review gate. Start that pass on your own initiative; do not wait for the user to say “refactor” or ask for cleanup. In-loop tidy-ups while coding are not a substitute.

The official source is Martin Fowler's Refactoring and the online catalog:

• https://martinfowler.com/books/refactoring.html
• https://refactoring.com/catalog/

Read references/fowler-refactoring.md for the high-level principles. Read exactly one per-refactoring reference file from references/refactorings/ when you decide which transformation to apply.

Core Rules

• Refactor in small, behavior-preserving steps.
• Keep the code working at each meaningful checkpoint.
• Run fast tests often while refactoring.
• Prefer many safe changes over one large rewrite.
• Rename for clarity early when names are misleading.
• Remove duplication only when it is real duplication, not coincidence.
• Inline indirection that no longer earns its keep.
• Delete dead code, debug scaffolding, and speculative abstractions.

Standard Workflow

1. Identify the behavior that must not change.
2. Find or add the smallest useful tests around that behavior.
3. Choose the lightest refactoring that addresses the current smell.
4. Make one small structural change.
5. Run the fastest relevant tests.
6. Repeat until the design is materially simpler.
7. Run the broader validation pass.

Refactoring Index

Use the linked file for the exact mechanics you want. Do not load all references by default.

• Change Function Declaration: Safely evolve a function's name, parameters, or calling contract.
• Change Reference to Value: Replace shared identity semantics with explicit value semantics.
• Change Value to Reference: Replace duplicate values with shared canonical references.
• Collapse Hierarchy: Remove an unnecessary inheritance layer by folding behavior together.
• Combine Functions into Class: Group related functions and shared data into one cohesive class.
• Combine Functions into Transform: Unify related derivations into one explicit transformation step.
• Consolidate Conditional Expression: Merge several conditions that lead to the same outcome.
• Decompose Conditional: Split a dense conditional into named condition and branch helpers.
• Encapsulate Collection: Hide direct collection mutation behind intention-revealing operations.
• Encapsulate Record: Wrap open record access in a clearer data abstraction.
• Encapsulate Variable: Control access to mutable state through a defined boundary.
• Extract Class: Split one overloaded class into smaller cohesive responsibilities.
• Extract Function: Pull a coherent code fragment into a named function.
• Extract Superclass: Move shared behavior and state into a common parent.
• Extract Variable: Give a complex expression a name that explains its purpose.
• Hide Delegate: Stop callers from reaching through an object to its internals.
• Inline Class: Remove a class that no longer justifies its existence.
• Inline Function: Remove a function that adds only indirection.
• Inline Variable: Remove a temporary that does not improve clarity.
• Introduce Assertion: Make an important assumption explicit in the code.
• Introduce Parameter Object: Group related parameters into one meaningful object.
• Introduce Special Case: Represent an edge case with a dedicated object or code path.
• Move Field: Relocate state to the type that really owns it.
• Move Function: Relocate behavior to the module or type it belongs with.
• Move Statements into Function: Pull repeated setup or policy statements into the callee.
• Move Statements to Callers: Push statements outward when only some callers need them.
• Parameterize Function: Replace several near-identical functions with one parameterized function.
• Preserve Whole Object: Pass the source object instead of multiple values extracted from it.
• Pull Up Constructor Body: Move shared constructor steps into a common parent path.
• Pull Up Field: Move duplicate subclass state into the superclass.
• Pull Up Method: Move duplicate subclass behavior into the superclass.
• Push Down Field: Move superclass state down to only the subclasses that use it.
• Push Down Method: Move superclass behavior down to the subclasses that need it.
• Remove Dead Code: Delete code that is no longer reachable or needed.
• Remove Flag Argument: Replace boolean mode switches with explicit entry points.
• Remove Middle Man: Let callers talk directly to a collaborator when delegation adds no value.
• Remove Setting Method: Prevent uncontrolled mutation by eliminating the setter.
• Remove Subclass: Delete a trivial subclass and fold its behavior into a simpler model.
• Rename Field: Rename a field so its purpose is clear.
• Rename Variable: Rename a variable so its role is obvious.
• Replace Command with Function: Turn a lightweight command object back into a plain function.
• Replace Conditional with Polymorphism: Move variant-specific branches into dedicated implementations.
• Replace Constructor with Factory Function: Use a named factory instead of a direct constructor call.
• Replace Control Flag with Break: Use structured exits instead of sentinel control flags.
• Replace Derived Variable with Query: Compute a derived value on demand instead of storing it.
• Replace Error Code with Exception: Use exceptions for exceptional flow instead of return codes.
• Replace Exception with Precheck: Use an explicit guard when failure is expected and testable.
• Replace Function with Command: Turn a complex function into an object with an explicit lifecycle.
• Replace Inline Code with Function Call: Replace repeated inline logic with one named call.
• Replace Loop with Pipeline: Rewrite collection-oriented loops as clearer pipeline operations.
• Replace Magic Literal: Replace an unexplained literal with a named symbol or object.
• Replace Nested Conditional with Guard Clauses: Flatten nested branching by handling special cases first.
• Replace Parameter with Query: Let the callee derive data instead of receiving it as a parameter.
• Replace Primitive with Object: Wrap a primitive in a richer domain abstraction.
• Replace Query with Parameter: Pass in a value when deriving it internally is the wrong dependency.
• Replace Subclass with Delegate: Use delegation instead of subclassing for specialization.
• Replace Superclass with Delegate: Replace inheritance with delegation when reuse is the only reason for the relationship.
• Replace Temp with Query: Replace a mutable temp with a side-effect-free query.
• Replace Type Code with Subclasses: Replace explicit type codes with dedicated subtype behavior.
• Return Modified Value: Return the updated value explicitly instead of hiding mutation.
• Separate Query from Modifier: Split a method that both returns data and changes state.
• Slide Statements: Move related statements together to clarify and prepare the code.
• Split Loop: Break one loop with several jobs into focused loops.
• Split Phase: Separate work into distinct sequential stages with clear outputs.
• Split Variable: Stop reusing one variable for multiple meanings.
• Substitute Algorithm: Swap in a simpler or clearer algorithm while preserving behavior.

Validation Discipline

• Run fast unit tests often during the refactor.
• Run integration tests before declaring the work done.
• If UI changed, do a manual visual verification pass after automated tests.
• If behavior is uncertain, stop and add characterization coverage before proceeding.