Refactoring

Refactoring

A structured approach to improving the design of existing code without changing its behavior. This skill acts as a router — it identifies which category of refactoring applies and delegates to the appropriate sub-skill.

When to Use This Skill

Triggers:

• User asks to "refactor," "clean up," or "improve" code
• User mentions code smells or design problems
• User wants to reduce complexity or improve readability
• User asks to restructure a class, method, or module
• User wants to prepare code for a new feature by improving its structure first
• Code review identifies maintainability concerns

Don't Triggers:

• User wants to add new functionality (add the feature first, then refactor)
• User wants to fix a bug (fix the bug first, then refactor)
• User wants to optimize for performance (that's a different concern)
• User is writing greenfield code from scratch
• User asks about testing strategies (use testing skills instead)

Core Principles

The Two Hats

When developing, you wear one of two hats:

• Add Functionality: You add new capabilities. You don't change existing code. You write tests for the new behavior.
• Refactor: You improve structure. You don't add functionality. Existing tests should continue to pass.

Never wear both hats at the same time. If you need to add a feature AND the code is messy, first refactor to make the feature easy to add, then add the feature.

When to Refactor

• Before adding a feature: Clean code is easier to extend. If the code isn't structured for what you need, refactor it first.
• After adding a feature: You often learn about the design as you go. Clean up what you learned.
• During a code review: Code review is the natural point for refactoring suggestions.
• When you see duplicated code: DRY violations are the most common signal.
• When a method is too long: If you need comments to explain sections, extract methods.
• When a class does too many things: Each class should have a single responsibility.

When NOT to Refactor

• When you should rewrite instead: If the code is fundamentally broken or unsalvageable.
• When you're close to a deadline: Refactoring in a time crunch introduces risk.
• When there are no tests: Refactoring without tests is dangerous. Write characterization tests first.
• When the code is throwaway: Don't polish code you'll delete.

Sub-Skill Routing

Determine which sub-skill to use based on the problem you observe:

Problem Observed	Route To	Sub-Skill
Code duplication, long methods, large classes, primitive obsession, data classes, or other structural problems	Code Smells	refactoring-code-smells
A single method is too long or does too many things; you need to break it into smaller, well-named pieces	Composing Methods	refactoring-composing-methods
Behavior or data is in the wrong class; responsibilities need to move between objects	Moving Features	refactoring-moving-features
Complex conditional logic (nested if/else, switch statements) is hard to follow	Simplifying Conditionals	refactoring-simplifying-conditionals

Routing Decision Flowchart

Is the problem about a method's internal structure?
  ├─ YES → refactoring-composing-methods
  └─ NO
    Is the problem about where responsibilities live?
      ├─ YES → refactoring-moving-features
      └─ NO
        Is the problem about complex conditionals?
          ├─ YES → refactoring-simplifying-conditionals
          └─ NO
            Are you trying to identify what's wrong?
              ├─ YES → refactoring-code-smells
              └─ NO → Use your judgment; multiple sub-skills may apply

Workflow

1. Identify the smell: What is the code doing that feels wrong? Use refactoring-code-smells to name it.
2. Choose the refactoring: Based on the smell, select the appropriate technique from the relevant sub-skill.
3. Ensure test coverage: Make sure existing behavior is covered by tests before changing anything.
4. Apply one refactoring at a time: Small, incremental changes. Run tests after each one.
5. Verify: All tests pass. The behavior is unchanged. The code is cleaner.

Important Reminders

• Refactoring is behavior-preserving. If you change what the code does, you're not refactoring.
• Always run tests after each refactoring step.
• Prefer many small refactorings over one large one.
• If a refactoring feels risky, stop and ensure you have better test coverage first.

---

Source: Martin Fowler, "Refactoring: Improving the Design of Existing Code" (2nd Edition)