refactoring · git:20260314.a3b7738 · 2026-03-14 · sha256 d8b578aadbb63a46

refactoring git:20260314.a3b7738A

Immutable. This exact content never changes and is served at /api/v1/blob/d8b578aadbb63a46.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_aiogg6w3nv5iqhnk/d8b578aadbb63a4681678100bcd9be4c2b0e1f1bc5942e76e5f6f4d2935ca302.json

Then /plugin install refactoring@markdownregistry-aiogg6w3nv5iqhnk in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: refactoring
description: >-
  Guides the agent through safe, systematic code refactoring — improving structure
  without changing behavior. Use this skill when asked to clean up code, reduce
  duplication, simplify complexity, extract components or functions, reorganize file
  structure, or improve maintainability. Also use when the demand-elegance skill
  identifies a hacky solution that needs restructuring.
---

# Refactoring

Improve the structure of existing code without changing its behavior. Every refactoring is a series of small, safe transformations.

## When to Use

- Codebase has accumulated technical debt
- Duplication across multiple files or functions
- A function or class has grown too large
- Naming doesn't reflect current purpose
- The demand-elegance skill flagged a hacky solution
- Before adding new features to a messy area of code

## How to Use

### Principle: Behavior Preservation

The golden rule of refactoring: **tests pass before and after every step**. If you don't have tests, write them first.

### Step 1: Establish a Safety Net

Before changing anything:
1. **Identify existing tests** that cover the code you're about to change
2. **Run them** — confirm they pass on the current code
3. **If no tests exist**, write characterization tests that capture current behavior
4. **Commit the tests** separately from the refactoring

### Step 2: Identify the Smell

Common code smells and their refactoring:

| Smell | Refactoring |
|-------|-------------|
| **Long function** (>30 lines) | Extract smaller, named functions |
| **Duplicate code** | Extract shared function or module |
| **Deep nesting** (>3 levels) | Early returns, extract conditions |
| **God class/file** | Split by responsibility |
| **Primitive obsession** | Introduce domain types |
| **Feature envy** | Move logic to the class that owns the data |
| **Long parameter list** (>4 params) | Introduce parameter object |
| **Dead code** | Delete it. That's what version control is for. |

### Step 3: Small Steps

Make one transformation at a time:

1. **Make the change** — One refactoring move
2. **Run tests** — Confirm behavior is preserved
3. **Commit** — Small, atomic commits with clear messages
4. **Repeat** — Next transformation

```
Refactoring commit messages:
  refactor: extract validateInput() from handleRequest()
  refactor: rename UserManager to UserRepository
  refactor: move email logic to NotificationService
  refactor: remove unused formatLegacyDate()
```

### Step 4: Verify the Whole

After all transformations:
- Run the complete test suite
- Review the full diff — does the result look cleaner?
- Check that no behavior changed (same inputs → same outputs)

## Examples

**Before — Nested Mess:**
```python
def process_order(order):
    if order:
        if order.items:
            if order.customer:
                if order.customer.verified:
                    for item in order.items:
                        if item.in_stock:
                            # actual business logic buried 5 levels deep
                            ...
```

**After — Early Returns:**
```python
def process_order(order):
    if not order or not order.items:
        return
    if not order.customer or not order.customer.verified:
        raise UnverifiedCustomerError()

    in_stock_items = [item for item in order.items if item.in_stock]
    # business logic at the top level, clear and readable
    ...
```

## Guidelines

- Write tests before refactoring, not after
- One transformation per commit — makes it easy to bisect if something breaks
- The goal is clarity, not cleverness
- If a refactoring makes the code harder to understand, revert it
- Don't refactor and add features in the same PR

## Anti-Patterns

- **Refactoring without tests** — You're just rearranging code and hoping for the best
- **Big bang refactoring** — Rewriting everything at once. Small steps, always.
- **Refactoring for hypothetical futures** — "We might need this to be pluggable someday" — no, just make it clear
- **Mixing refactoring with feature work** — Separate PRs. Always.
- **Renaming without search** — Rename a function and forget the 5 other files that call it