refactor

Files (10)

• CREDITS.md
• DATA-OVER-ABSTRACTIONS.md
• DESIGN-IS-TAKING-APART.md
• EXPENSIVE-TO-ADD-LATER.md
• HOTSPOTS.md
• MECHANICAL-SWEEPS.md
• NOTICE
• SIMPLICITY-VS-EASY.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Refactor

Improve code structure without changing behavior. Works at three scopes: **project**, **file**, or **method**. Starts by assessing whether refactoring is even warranted: if the code is already clean, say so and stop.

**Refactoring vs architecture:** this skill handles code-level improvements: complexity, duplication, naming, dead code, method extraction. If the assessment shows that the real problem is module boundaries, coupling between packages, or shallow modules that need deepening, say so. That is an architecture problem this skill won't fix: tell the user to run `/improve-architecture` in Claude linked installs or Cursor, `/supermatt:improve-architecture` from the Claude plugin, `$improve-architecture` in Codex, or `/skill:improve-architecture` in OMP.

## Philosophy

These principles calibrate what "good enough" means and guide every step below:

- **Measure the end state, not the effort.** Writing 50 lines that delete 200 is a win.
- **Simple over easy.** Simple means one concept, not intertwined. Easy means familiar. Choose simple.
- **Separate, don't combine.** Good design is taking things apart: removing dependencies, not adding abstractions.
- **Data over abstractions.** 100 functions on one data structure beat 10 functions on 10 custom types.
- **Less total code.** If "better organized" means more lines, it's more entropy, not less.
- **When in doubt, leave it alone.** The default verdict is Clean. Don't invent work.

Read a reference only when the assessment actually turns on it:

- `SIMPLICITY-VS-EASY.md`: when the choice is between a familiar approach and a simpler one
- `DATA-OVER-ABSTRACTIONS.md`: when custom types could be plain data structures
- `DESIGN-IS-TAKING-APART.md`: when a coupled system needs decomposing
- `EXPENSIVE-TO-ADD-LATER.md`: when deciding whether something missing is worth adding now

## Step 1: Determine scope

Infer from the user's request:

| Trigger | Scope |
|---------|-------|
| "refactor this method/function" or a specific symbol name | **method** |
| "refactor this file" or a file path | **file** |
| "refactor this project/codebase" or no specific target | **project** |

"The changes on this branch since `<ref>`" is file scope over each file in `git diff --name-only <ref>...HEAD`, judged on the changed code. If the scope is still ambiguous, ask the user, with the three scopes as the options.

## Step 2: Assess whether refactoring is warranted

**This step is mandatory.** Read the target code and evaluate it against the criteria below. The default verdict is **Clean**: only escalate when there's clear evidence.

### Method scope

- Cognitive complexity: nesting depth >3, boolean expressions with >2 operators, or branch count that makes the flow hard to follow. Investigate, but a long method that reads linearly is not automatically a smell.
- Length: functions over ~50 lines warrant a look, but length alone isn't a verdict. A 70-line function with clear flow is better than 5 tiny functions that scatter the logic.
- Parameter count: >4 parameters on a public API boundary suggests grouping. Internal helpers can have more.
- Single responsibility: does it do one thing?
- Naming clarity: do names describe intent or mechanics?

### File scope

All method-level checks, plus:
- Dead code (unused functions, imports, variables)
- Duplicated logic across functions in the same file
- God class or kitchen-sink module: too many unrelated responsibilities
- Cohesion: do all parts belong together?

### Project scope

All file-level checks, plus:
- Circular dependencies between modules
- Duplicated logic across files/modules
- Overly deep module nesting or excessive file count for what the code does
- Total codebase size: could fewer files/functions achieve the same result?

A whole codebase always offers more findings than are worth acting on. Read `HOTSPOTS.md` and rank by change frequency crossed with complexity before listing anything. It decides what to look at first, not what is wrong.

Read the ranked candidates through subagents, one per area, each returning findings rather than file contents. A project-scope assessment reads far more code than it reports on, and most of it comes back Clean. Step 4 reads what it actually edits. A project under about 1,000 source lines is the exception: read it directly, a few files per call, so each output stays under the 30,000-character limit that moves a result to a file.

### Planned and settled work

Before you list any finding, read each issue the target's commits reference, with its comments, through the **Read an issue** operation in `docs/agents/issue-tracker.md`. Drop a finding that a comment already settled, such as a user's answer to the same question during `implement`, and name that comment in the verdict.

A finding that removes an indirection (a function where a value would do, a parameter, a hook, a seam) can take out what the next planned change needs. Before you list one, also read the open children of those issues' parent issue. Drop a finding that a planned issue needs, and name that issue in the verdict.

### The verdict

| Rating | Meaning | Action |
|--------|---------|--------|
| **Clean** | No meaningful improvements available | Tell the user the code looks good and end the run there. **Stop here** unless they provide a specific reason to continue. An item worth offering the user makes the verdict Minor. |
| **Minor** | Small improvements possible (naming, minor duplication) | List findings. Recommend applying them or leaving the code as is, give the deciding reason, then ask. These are optional. |
| **Significant** | Clear code smells or structural issues | List findings with priorities. Proceed to Step 3. |
| **Critical** | Major structural problems blocking maintainability | List findings urgently. Proceed to Step 3. |

**Idempotency rule:** if you run this skill on the same code twice and it's already been refactored, the verdict must be **Clean**.

**User override:** if the user provides a specific reason to refactor code rated Clean (e.g., "I know it looks fine but I want to extract this into smaller functions"), proceed with their request, but scope the changes strictly to what they asked for. Don't expand into a broader refactoring.

**Architecture signal:** if the assessment shows problems that are really about module boundaries (tightly coupled packages, shallow modules, missing abstractions at the architectural level), say so: refactoring code inside a badly-bounded module won't fix the real problem. Tell the user to run `/improve-architecture` in Claude linked installs or Cursor, `/supermatt:improve-architecture` from the Claude plugin, `$improve-architecture` in Codex, or `/skill:improve-architecture` in OMP.

## Step 3: Plan

For **method** scope, skip to Step 3.5. Planning is unnecessary for single-symbol changes, but the test gate still applies.

Enter plan mode, where the host has one, before planning, so no file changes while the plan is drafted. If the request is too ambiguous to plan safely, ask rather than start.

For **file** scope with 1-3 changes, a bullet list is sufficient:
```
Changes:
- Extract X into helper function
- Remove unused imports
- Rename Y to describe intent
```

For **file** scope with 4+ changes or **project** scope, produce a structured plan:

```
## Refactor Plan: [title]

### Current State
[What's wrong and why it matters]

### Target State
[What the code looks like after: fewer lines, fewer concepts, clearer boundaries]

### Changes
| File | Action | Why | Blocked by |
|------|--------|-----|------------|
| path | modify/create/delete | reason | dependencies |

From svyatov/supermatt, MIT.

More from svyatov/supermatt