refactor-it

Refactor It

Improve the code's shape while preserving behavior. If behavior must change, stop and use fix-it (or implement the feature explicitly) instead of hiding changes inside a "refactor."

Paying down development / architecture debt (handbook/concepts/12-bugs-and-debt.md) is a valid reason to refactor — still keep steps behavior-preserving and evidence-backed.

Operating contract

Shared by every DecisionNerd/dev-skills skill. Canonical copy: handbook/concepts/14-operating-contract.md.

• Define done first. Before using tools, write the finish line in one or two lines: acceptance criteria (existing issue AC, BDD scenarios, tests, or contract; otherwise propose them and where they should live) and the evidence that will prove them. Re-check it before reporting done. Never report done on unverified work.
• Requested scope sets the finish line. A question ("is it ready?", "why is it broken?", "what next?") ends with the answer and a Next: line naming the exact next invoke. An outcome request ("fix", "finish", "land", "#42") continues through the chain (diagnose → fix → test → check-readiness → merge-it) until the outcome or a real blocker. Do not end a turn with "Do you want me to…?" for in-scope, in-repo work.
• Stop only for real blockers. Stop and ask only when you cannot continue without the user, or before: deleting data or unmerged work, force-push or history rewrite, changing anything outside this repository (GitHub objects, deployments, live data, production or paid resources, external services), or leaving the requested scope, unless the user's request already named that exact action. Keep the harness's permission prompts for risky commands. Otherwise keep going and put status notes in the same message as the next action.
• Ask well, once. For a genuine question use the harness's structured question tool when it has one (Claude Code: AskUserQuestion; Codex: request_user_input when the current mode supports it; T3 Code: the question tool) with concrete options; otherwise plain text with numbered options. Treat the answer as settled; do not re-open earlier verdicts, plans, or answers unless asked.
• Fan out when work is parallel. Use subagents for independent reads (repo survey, evidence gathering, per-option research, per-area audits) and independent verification (a reviewer that did not write the change). Writes stay single-owner per path set and sequential. Brief every child with goal, done-when, constraints, must-not, and return shape; verify each result before consolidating. Use Claude Code's Workflow tool only when orchestrating many subagents truly needs it; it is expensive. T3 Code: its delegated subagents — with optional worktree isolation for independent verification — cover this without the Workflow tool.
• Pick the model tier per child; defer to routing config. If the harness or user config already routes subagents, follow it and do not pass a model. Otherwise pick a tier per child: mechanical search or inventory → fast/cheap; implementation and evidence gathering → mid; planning, review, adversarial verification → top. Tier names differ per harness (Claude Code: haiku / sonnet / opus or fable; T3 Code: inherit by default or pick from its live provider/model catalog). Set the choice with the harness's spawn model param or agent frontmatter model: (per-harness details: skills/agents/references/sub.md). Where the harness cannot choose, children inherit or the harness picks; say which in the status note.
• Keep a checklist on long runs. For more than about five steps or work that crosses skills, keep TASKS.md at the repo root and tick items as they finish. Do not commit it unless the repo already tracks one.
• Close every run with three headings. Blocked on me (the one genuine question or blocker, else "none"); Changed (files, commits, GitHub objects, deploys, else "nothing"); Found (evidence, verdict, and Next: <exact invoke>).

When to use

• "Refactor it", extract function/module, rename for clarity, decompose god-file
• Prep for a feature when structure blocks a clean change
• After diagnose-bug when the bug fix is done and structure still hurts

When NOT to use

• Product behavior change → fix-it
• Disk/worktree clutter → tidy-up
• Docs-only cleanup → document-it / DocSlime kiss

Workflow

Done when: public contracts unchanged, tests green after every step, diff reviewable. Single writer per path set; parallel read-only scouting (fast tier) for characterization coverage is fine.

1. Characterize current behavior

• Identify entry points, public API, and existing tests that lock behavior.
• If tests are missing for the risky surface, propose test-it before deep refactor (or add characterization tests first).

1. Define non-goals

• No feature work, no dependency upgrades "while we're here," no drive-by style wars outside the touched surface.

1. Plan small steps

• Extract, rename, move, invert dependencies — one cohesive idea per step.
• Keep diffs reviewable; avoid rewriting unrelated files.

1. Execute with a safety net

• After each step, run the narrowest relevant tests.
• Stop if behavior drifts; revert the step or add a failing characterization test.

1. Verify

• Same public contracts, same user-visible behavior.
• Note any intentional API renames and required call-site updates (still behavior-preserving).

1. Wrap up

• Next: test-it if coverage is still thin, document-it if public API moved, pulls create / merge-it to land.

Guardrails

• Behavior change → not this skill (fix-it / feature work).
• Don't mix refactor with large feature commits; split PRs when possible (pulls narrow).
• Performance "refactors" need a measured baseline or they're speculative — say so.

Output

**Target**
- ...

**Behavior locked by**
- tests / manual checks: ...

**Steps taken**
1. ...

**Verification**
- Ran: ...

## Blocked on me

none

## Changed

- ...

## Found

- ...
- Next: test-it / document-it / pulls create

Grounding

This skill's TTPs are grounded in current engineering baselines (DORA, GitHub Docs, Fowler/Beck, Google SRE & SWE book, OpenTelemetry, OWASP LLM / NIST AI RMF, Diátaxis — see handbook sources.md).

Fowler refactoring = behavior-preserving micro-steps under test; Beck: passes tests first. Characterization tests before structural change.

Handbook card: handbook/practices/refactor-it.md.