refactoring-pass

Files (6)

• SKILL.md
• evals.json · evals/
• code-smells.md · references/
• preparatory-refactoring.md · references/
• refactoring-moves.md · references/
• technique-safety.md · references/

SKILL.md (first lines)

# Refactoring Pass

## When This Skill Loads

If you are reading this, the user wants to improve code structure without changing what the code does. **Refactoring is behavior-preserving design work in small steps.** Do not turn cleanup into a rewrite, a hidden feature change, or speculative architecture.

## Core Principle

**Preserve observable behavior.** Every structural change must leave the code doing exactly what it did before — just better organized.

## The Refactoring Workflow

### 1. Identify the Friction
What makes the current code hard to change? Common smells:
- **Duplication** — same code in multiple places
- **Long functions** — too much in one method
- **Long parameter lists** — too many arguments
- **Divergent change** — one class changes for many reasons
- **Shotgun surgery** — one change requires edits across many files
- **Feature envy** — a method uses another class's data more than its own
- **Primitive obsession** — primitives where value objects would carry meaning
- **Repeated conditionals** — same switch/if-else chain in multiple places
- **Middle man** — a class that only delegates to another
- **Speculative generality** — abstractions with one caller

### 2. Establish a Safety Net
Before refactoring, make sure you can detect regressions:
- **Existing tests:** Run them. They must pass before you start.
- **No tests:** Write characterization tests around the area you're changing. Capture current behavior, even if it's ugly.
- **Unclear behavior:** Characterize first. Don't refactor code you don't understand.
- **Never delete a failing test to complete a refactoring.** A failing test is a signal, not an obstacle.

### 3. Refactor in Small Steps
Each step should be:
- **Reversible** — you can undo it if something breaks
- **Buildable** — the code compiles/passes after each step
- **Testable** — you can run tests after each step
- **Reviewable** — the diff is small enough to reason about

**Commit after each step that passes tests.**

### 4. Preparatory Refactoring (Before a Feature)
When a requested feature is awkward to make:
1. Identify the structural friction that blocks the change.
2. Reshape that local structure first — just enough to make the feature simple.
3. Make the behavior change.
4. Clean up debt introduced by the change.

### 5. Follow-up Refactoring (After a Feature)
After making a behavior change:
1. Look for smells the change introduced or revealed.
2. Clean them up while the context is fresh.
3. Don't expand beyond what the feature touched.

## Named Moves

Prefer the simplest named move that helps:

| Move | When |
|---|---|
| **Rename** | Name is misleading, vague, or mechanism-focused. Rename before deeper work when bad names block understanding. |
| **Extract method** | A chunk of code has a distinct purpose. Extract it, name the purpose. |
| **Extract class** | A class has two independent responsibilities. Split them. |
| **Inline** | A method's body is as clear as its name. Inline it. |
| **Move method/field** | Behavior lives in the wrong class. Move it where the data is. |
| **Introduce parameter object** | A group of parameters always travels together. Bundle them. |
| **Encapsulate collection** | Callers manipulate a collection directly. Expose intent-revealing methods instead. |
| **Decompose conditional** | A complex conditional or switch. Extract predicates, use guard clauses, or replace with polymorphism. |
| **Replace conditional with polymorphism** | Repeated type codes or switch statements that vary behavior. |
| **Use guard clauses** | Nested conditionals with early exits. Flatten with guard clauses at the top. |

## Decision Rules

- **Separate behavior changes from structural changes.** Never mix a feature change with a refactoring in the same commit.
- **Refactor the blocking smell, not every smell in sight.** Focus on what makes the current task hard.
- **Use abstraction only when current evidence justifies it.** Remove pass-through layers, vague utilities, and just-in-case interfaces.
- **Separate business policy from delivery mechanics** — not just from UI, but from formatting, transport, persistence, I/O, and frameworks.
- **Preserve error semantics** unless intentionally changing behavior. Refactor error handling to reveal the main path.
- **Preserve public compatibility, or provide a transition path.** When a move changes a public signature, class hierarchy, or serialized shape, add the new form and migrate callers before removing the old one; check generated/reflected/serialized/plugin-facing usages before deleting anything "unused." See [Technique Safety](references/technique-safety.md).
- **Keep patches reviewable.** Group related refactorings. Avoid giant patches that rename, move, redesign, and change logic together.

## Trigger Rules

- **Adding behavior:** First ask what structural friction blocks the change. Refactor before the feature only when it makes the feature safer or simpler.
- **Fixing a bug in unclear code:** Characterize the current failure. Refactor only enough to make the fix visible before changing behavior.
- **Weak tests:** Make the smallest possible structural move. Improve testability before broader cleanup.
- **Third repetition:** When the same edit appears for a third time, remove duplication through clearer ownership instead of copying again.
- **Mixed responsibilities:** When a function mixes phases, abstraction levels, or hidden side effects, split them before adding more logic. Keep variable scope tight and each function at one consistent abstraction level.
- **Shotgun surgery:** When one change forces edits across many files, centralize the knowledge or introduce a clearer boundary.
- **Repeated conditionals:** Decompose intent first. Introduce polymorphism or strategy only when the variation is real.
- **UI/domain mixing:** Move rules toward domain objects. Keep presentation in adapters, and verify any required presentation synchronization.
- **Rewrite temptation:** Choose the next small behavior-preserving transformation that recovers control.

## Stop Conditions

Stop refactoring when:
- The requested change is easy to make.
- The blocking smell is gone.
- Readability and local changeability are clearly better.
- The next cleanup would be speculative.

**Do not** turn cleanup into a rewrite, a hidden feature change, or speculative architecture.

## Final Checklist

- [ ] Observable behavior preserved?
- [ ] Structural change, behavior change, and test updates separated?
- [ ] Safety net in place (tests pass before and after)? Any verification gap — behavior not protected by tests during the pass — recorded?
- [ ] At least one real source of friction removed?
- [ ] Names, responsibilities, control flow, data ownership, interfaces clearer?
- [ ] Patch still reviewable and runnable?
- [ ] Cleanup stopped before speculative abstraction or rewrite pressure?

## Reference

| File | Use When |
|---|---|
| [Code Smells](references/code-smells.md) | Identifying which smell to refactor and which move to apply — the six smell families, the full catalog, the smell→treatment priority map, and when *not* to treat a smell |
| [Refactoring Moves](references/refactoring-moves.md) | Step-by-step instructions for specific refactoring techniques |

From dekoza/oh-my-slop, Unlicense.

More from dekoza/oh-my-slop