refactor-guru

Files (4)

• SKILL.md
• patterns-catalog.md · references/
• refactoring-techniques.md · references/
• smells-catalog.md · references/

SKILL.md (first lines)

# Code Refactoring

Diagnose structural problems in code using three lenses: pain (what hurts now), intent (what
the code needs to become), and comprehension (what's hard to understand). Apply the smallest
change that solves the real problem. Language-agnostic.

## When to Use

- User shows code and asks "what's wrong with this?" or "how can I improve this?"
- User describes pain: brittle tests, cascading changes, files that grow endlessly
- User mentions smells by name or informal equivalents ("spaghetti code," "this does too much")
- User wants to apply a specific design pattern or refactoring technique
- User asks why code is hard to change, test, or understand
- User has a structural goal or upcoming need: "make this pluggable," "I need to add N more X,"
  "we need to deploy these independently," "I want to support undo/redo"
- User struggles to understand code: "I can never remember how X works," "new devs take weeks,"
  "the code works but I can't explain it," "what does this even do"

**Don't use when:** Code is a prototype/spike, about to be replaced, or the user just wants a feature added (refactor only if it enables the feature).

## Quick Reference — Most Common Smell → Fix

| Pain | Likely Smell | Primary Fix |
|------|-------------|-------------|
| Method is 200+ lines | Long Method | Extract Method |
| Class has 30+ fields | Large Class | Extract Class |
| Same 4 params everywhere | Data Clumps | Introduce Parameter Object |
| Huge switch/case keeps growing | Switch Statements | Replace Conditional with Polymorphism |
| Method uses another class's data more than its own | Feature Envy | Move Method |
| One change touches 10+ files | Shotgun Surgery | Move Method / Move Field (consolidate) |
| One class changes for unrelated reasons | Divergent Change | Extract Class (split by responsibility) |
| Two classes know too much about each other | Inappropriate Intimacy | Move Method + Hide Delegate |
| Copy-pasted code blocks | Duplicate Code | Extract Method / Extract Superclass |
| Getters/setters only, no behavior | Data Class | Move behavior into the data class |

## Quick Reference — Common Intent → Pattern

| Goal | Likely Pattern | Key Technique |
|------|---------------|---------------|
| Add N more variants (formats, providers, rules) | Strategy | Extract Interface + Extract Class per variant |
| Make pluggable/extensible | Strategy / Observer | Extract Interface + dependency injection |
| Support undo/redo | Command + Memento | Extract Method → Command objects |
| Deploy modules independently | Facade | Extract Class + boundary interface |
| React to changes elsewhere | Observer | Extract event interface |
| Handle object in multiple states | State | Replace Type Code with State/Strategy |
| Simplify complex subsystem access | Facade | Hide Delegate + Extract Class |

---

## Step 1: Understand the Context

Before diagnosing, establish:

1. **What code?** Read it carefully. Understand what it does.
2. **What's the driver?** Identify which lens is strongest — they're not mutually exclusive, and
   requests often combine signals. Lead with the strongest one.
   - **Pain**: Something hurts now — hard to change, test, read, keeps breaking
   - **Intent**: Upcoming need — "I need to add X," "make this pluggable," "support Y"
   - **Comprehension**: Hard to understand — "can't follow this," "new devs struggle," "can't explain it"
3. **What language?** Idiomatic solutions differ across languages.
4. **How mature?** Prototype vs production changes the threshold for action.
5. **Is now the right time?** Rule of Three: first time, just do it; second time, wince; third time, refactor. Best times: before adding a feature, when fixing a bug, during code review.

**Routing:**
- Pain / "what's wrong?" → **Step 2** (smell detection)
- Structural goal / upcoming need → **Step 2B** (structural gap analysis), optionally **Step 2** too
- Understanding struggle → **Step 2C** (domain alignment), optionally **Step 2** too
- Mixed signals → lead with the strongest driver, draw from other lenses as needed
- Problem described, no code → Ask to see the code first
- Asks about a specific pattern/technique → **Step 4** or **Step 5**
- Wants to refactor specific code → **Step 2**, move quickly to **Step 6**
- No clear signal → default to **Step 2** (smell detection)

---

## Step 2: Detect the Smell

Analyze the code against the five smell categories. Most code has multiple smells — focus on
the one causing the most pain, not every smell you can find.

### The Five Categories

Think of these as lenses to look through:

**Bloaters** — Things that have grown too large to manage
- Long Method, Large Class, Primitive Obsession, Long Parameter List, Data Clumps

**Object-Orientation Abusers** — OO principles applied incorrectly or incompletely
- Switch Statements, Temporary Field, Refused Bequest, Alternative Classes with Different Interfaces

**Change Preventers** — Code structures that make changes ripple everywhere
- Divergent Change (one class changes for many reasons), Shotgun Surgery (one change touches many classes), Parallel Inheritance Hierarchies

**Dispensables** — Things that could be removed to make code cleaner
- Duplicate Code, Lazy Class, Data Class, Dead Code, Speculative Generality, Comments (as deodorant)

**Couplers** — Excessive coupling between classes
- Feature Envy, Inappropriate Intimacy, Message Chains, Middle Man

For the full catalog with all smells, their symptoms, and mapped refactoring techniques,
read `references/smells-catalog.md`.

### How to Identify the Primary Smell

Start from the user's pain, not from a checklist:

- "I keep changing this file for unrelated reasons" → **Divergent Change**
- "Every small change requires editing 10+ files" → **Shotgun Surgery**
- "This method is 200 lines long" → **Long Method**
- "This class has 30 fields" → **Large Class**
- "I pass the same 4 parameters everywhere" → **Data Clumps** or **Long Parameter List**
- "There's a huge switch/case I keep extending" → **Switch Statements**
- "This method uses more of another class than its own" → **Feature Envy**
- "These two classes know too much about each other" → **Inappropriate Intimacy**
- "Half this subclass is overriding parent to do nothing" → **Refused Bequest**
- "I can't test this without mocking everything" → often **Feature Envy** or **Inappropriate Intimacy**
- "There's a lot of copy-pasted code" → **Duplicate Code**
- "This class is just getters and setters" → **Data Class**

From guillevc/skills, MIT.

More from guillevc/skills