refactor · diff
git:20260711.e00cba7 to git:20260714.429242b
12 added, 15 removed. Audit A to A.
---
name: refactor
description: >-
- Evidence-driven refactoring — "where does structural improvement actually
- pay off here, and make that change without changing behavior." Survey mode
- diagnoses by evidence, not aesthetics: git churn × complexity hotspots,
- the recurring-bug log, upcoming work — then a verdict per candidate
- (REFACTOR / PREP / LEAVE / WATCH) where LEAVE is the default and "the
- textbook recommends it" is never a reason; every proposal names a located
- problem in this codebase. Execute mode takes one
- approved candidate: characterization tests first where untested,
- then small named behavior-preserving moves, suite green and checkpoint
- commit after each — a red step is reverted, never patched forward.
- Mid-refactor bugs are logged for bugfix, not fixed in flight. Keeps a
- debt register in out/refactor/tracker.md so repeat surveys open with what
- changed. Use for "clean up this module", "improve the architecture", "pay
- down tech debt" — e.g. "/refactor", "/refactor <target>". For new
- behavior use feature; for something broken use bugfix.
+ Evidence-driven refactoring — where does structural improvement actually
+ pay off, then make that change without changing behavior. Survey mode
+ diagnoses by evidence, not aesthetics — git churn × complexity hotspots,
+ the recurring-bug log, upcoming work — and verdicts each candidate
+ REFACTOR/PREP/LEAVE/WATCH, where LEAVE is the default and "the textbook
+ recommends it" is never a reason. Execute mode takes one approved
+ candidate in small behavior-preserving moves, suite green after each.
+ Keeps a debt register in out/refactor/tracker.md so repeat surveys open
+ with what changed. Use for "clean up this module", "improve the
+ architecture", "pay down tech debt" — e.g. "/refactor",
+ "/refactor <target>". For new behavior use feature; for something broken
+ use bugfix.
---
# refactor — earn it first, then preserve behavior
`/refactor` — survey the repo, emit a brief of where improvement pays off
`/refactor <target or goal>` — execute one candidate, safely
Answer one question: **where does structural improvement actually pay for
itself in this codebase — and how is that change made without changing
behavior?** The skill exists to prevent the two documented failure modes of
"improve the architecture": refactoring the wrong code (most ugly code is
never touched again, so cleaning it returns nothing), and **pattern-itis** —
applying design patterns because they're best practices rather than because
a problem here demands them, turning straight-line code into abstraction
lasagna.
## Survey mode — `/refactor`
### Step 1 — Evidence, not aesthetics
Candidates come from signals, never from "this code looks bad":
- **Hotspots** — churn × complexity. Churn from git itself:
`git log --format= --name-only --since="12 months ago" | sort | uniq -c |
sort -rn | head -30`, crossed with a complexity proxy (file length,
indentation depth). Code that is both complex *and* frequently edited is
where interest compounds; complex-but-cold code is a LEAVE by default.
- **The bug log** — `out/dev/bugfix-log.md` if present. A file that shows up
repeatedly is structural debt announcing itself.
- **Upcoming work** — the user's stated goals, open specs and plans under
`out/dev/`. These seed **PREP** candidates: make the change easy, then
make the easy change — preparatory refactoring is the highest-payoff kind
because the payoff is scheduled, not hoped for.
- **The map** — `AGENTS.md` gotchas and conventions; a documented gotcha is
often a workaround for structure that could stop needing one.
- **Memory** — `out/refactor/tracker.md` if it exists: verdicts already
made. A LEAVE with a reason isn't re-litigated unless its evidence
changed; repeat surveys open with **"Since last survey"**.
### Step 2 — Verdicts, with the pattern gate
For each candidate: **REFACTOR / PREP / LEAVE / WATCH**.
- **LEAVE is the default.** Promotion needs positive evidence: churn, a
recurring bug, or scheduled work in the area. "This violates a principle"
alone promotes nothing — cold code keeps its sins.
- **The pattern gate:** a design pattern is vocabulary, not a goal. Every
proposal that introduces one names the problem *in this codebase* (with a
file:line locator and its evidence), why *this* pattern fits, and what
simpler shape was considered first. "The textbook recommends it" is
discarded, not weighed.
- **The score is interface depth, not pattern count.** A proposal wins if
interfaces get simpler and callers get dumber — abstractions that hide
more than they add. A refactor that grows the number of things a reader
must understand has failed even if every step was clean.
- Each REFACTOR/PREP carries: the problem + locator, the target shape, a
sketch of the move sequence, effort, and risk. Candidates too big to stay
behavior-preserving (real redesigns) are phrased as ready `/feature` or
`/autopilot` handoffs instead — offered, never performed.
### Step 3 — Brief and register
Render the brief **in chat** per `references/brief-template.md` (read it
when you reach this step), save to `out/refactor/<slug>-<YYYY-MM-DD>.md`
(date via `date +%F`; create the folder if needed; committing is the user's
call), and update `out/refactor/tracker.md` — one row per candidate:
candidate · verdict · evidence · date · status. The user picks what to
execute; the survey never starts cutting on its own.
## Execute mode — `/refactor <target>`
### Step 1 — Safety net before scalpel
- Find the test command (`AGENTS.md`, manifests, CI config) and run the
suite for a **green baseline**. A pre-existing red is reported and stops
the run — refactoring on red has no arbiter.
- Area untested? Write **characterization tests** around exactly the code
to be touched — pin current behavior *as it is, bugs included* — and
commit them separately before any restructuring. Without them, "behavior
preserved" is an opinion.
### Step 2 — Small named moves, green after each
Plan the sequence as named moves — extract function, move module, rename,
inline, introduce parameter object — then per move: apply it, run the
suite, checkpoint commit titled with the move. The rhythm is the safety:
- **Red after a step → revert that step.** Never patch forward to green — a
patched-forward red is a behavior change wearing a refactor's name.
Rethink the move or split it smaller.
- Every checkpoint leaves the tree shippable. There is no big-bang branch
where everything is broken until the end.
### Step 3 — Behavior-preserving is the definition
- **A bug found mid-refactor is logged** (`out/dev/bugfix-log.md`, offered
as a ready `/bugfix` invocation) and its behavior deliberately preserved.
Fixing it in flight changes behavior and poisons the diff's reviewability.
- No new features, no "while I'm here" improvements outside the stated
goal, no public-interface changes the goal didn't name.
### Step 4 — Ship, then refresh the map
- Run **done** on the diff. The spec it reviews against is exactly:
*behavior unchanged, structure goal met* — its evidence checklist and
fresh-context review apply verbatim.
- Update the tracker row (status, date, commit).
- Structure changed means the map is stale: finish with `/map refresh`.
## Auto mode — under autopilot
Driven by **autopilot** (or explicit auto), the survey's brief-approval
becomes a self-approval on the record in the run's `log.md`, and only
candidates whose evidence survives the pattern gate proceed; anything
arguable parks. Execution changes nothing — the suite was already the
arbiter, and every hard rule above holds verbatim.
## State
`out/refactor/`: `tracker.md` (the debt register) and dated briefs. An
interrupted execution resumes from `git log` — the checkpoint commits *are*
the state — plus the tracker row; never from conversation memory.
## Guardrails
- **LEAVE is the default.** Payoff requires churn, bugs, or scheduled work;
aesthetics promote nothing.
- **"The textbook recommends it" is never a reason.** A pattern needs a
named, located problem in this codebase.
- **Behavior-preserving or it isn't refactoring.** Bugs are logged and kept,
features wait, the goal bounds the diff.
- **Tests are the arbiter.** No suite → characterization tests first; red
step → revert, never patch forward.
- **Interface depth is the score.** If callers didn't get simpler, adding a
pattern made it worse — pattern count is not a metric.
- **The survey never cuts.** Diagnosis and execution are separate consents;
the brief recommends, the user picks the target.