/refactor

name: refactor
description: >
  Restructure existing code without changing its behavior, through a test-gated refactoring loop: a named target, a
  green suite over that target before any edit, a planned sequence of small named refactorings, and the full suite
  re-run after every step. Use when the user wants to refactor, restructure, clean up, simplify, or improve the design
  of existing code, or to apply refactoring recommendations from a code-review or architectural-analysis report. This
  skill changes code; it does not review code (use code-review), assess architecture (use architectural-analysis), plan
  a multi-module restructure before executing it (use plan-a-change), map domain boundaries before restructuring along
  them (use ddd-analysis), or build new behavior test-first (use tdd). Do not use it on code inside an active tdd loop;
  the refactor step of tdd owns that cleanup. Runs its planned sequence to completion without pausing for review; to review each named
  refactoring as it lands, use pairing.
argument-hint: "[file, module, named smell, or a path to review findings]"
allowed-tools:
  Read, Write, Edit, Glob, Grep, Bash(git *), Bash(find *), Bash(npm *), Bash(npx *), Bash(pnpm *), Bash(yarn *),
  Bash(pytest *), Bash(python3 *), Bash(go *), Bash(cargo *), Bash(make *), Bash(bundle *), Bash(rake *),
  Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

Project Context

• git installed: !`which git 2>/dev/null || echo "not installed"`
• current branch: !`git branch --show-current 2>/dev/null || echo unknown`
• working tree: !`git status --porcelain 2>/dev/null | head -5`
• CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
• project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
• personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
• project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Constraints (read before anything else)

This skill restructures existing production and test code in your working tree. It is an execution skill, not a document generator. These constraints shape every step and override any instinct to move faster. The canon they derive from, with provenance, is in [references/refactoring-discipline.md](./references/refactoring-discipline.md); pull that reference when a step needs the full rule or a step feels off.

• **Behavior preservation is the definition.** A refactoring changes internal structure without changing observable

behavior. A change that alters behavior is not a refactoring done badly; it is not a refactoring at all. When a planned step turns out to require a behavior change, it leaves this skill's scope: defer it with a note naming the behavior change it needs.

• **Tests are the license to refactor.** No edit until the full suite has been run, observed green, and the target's

behavior is covered. If coverage of the target cannot be established, stop and offer the characterization path in the reference; never refactor blind.

• **Small named steps, green to green.** Each step is one named refactoring with a bounded mechanic (extract function,

rename, move, inline, and so on), and the suite runs after every step. A red suite after a step means revert the step, not patch forward.

• **The declared scope is a contract.** The target named in Step 1 bounds every edit. When a step starts pulling in

files outside that scope, stop, report the spread, and let the user re-scope. Spreading edits are how a refactoring silently becomes a rewrite.

• **Never alongside an active tdd loop.** If the working tree shows a red-green cycle in flight (failing tests, a

half-implemented behavior), do not run: the refactor step of `/tdd` owns cleanup inside the loop, and restructuring while a test is red violates the two-hats rule both skills share.

• **Refactor-only changes.** No behavior fixes, no features, no drive-by bug fixes, even when you spot one. Record what

you found and leave it. If the user asks for commits, each commit contains refactoring only.

• **YAGNI governs the plan.** Apply [../../references/yagni-rule.md](../../references/yagni-rule.md): every refactoring

in the plan needs evidence the code has a reason to change (a review finding, named duplication, a confusing read documented by the user, upcoming work in that area). Removing duplication is the job; adding speculative abstraction, configuration, or indirection is not. Defer evidence-free items with a reopen trigger.

Refactor

Step 1: Bind the Target and Resolve Project Config

**Bind the target.** Resolve the request to a named target: specific files or directories, a named code smell in a named place, or the refactoring findings in a provided document (a `/code-review` report, an `/architectural-analysis` report, or equivalent). When a findings document is given, extract only the refactoring-shaped findings (structural suggestions, duplication, naming, coupling) and record each finding's ID so the summary can trace back to it. If the request is open-ended ("clean up the codebase", "improve quality") with no named target, ask the user for one before doing anything: open-ended refactoring runs are the documented failure mode this skill exists to avoid, and a wrong guess here burns the whole run.

**Resolve commands.** Read CLAUDE.md's `## Project Discovery` section for the test command (under `### Commands and Tests`), the lint command, the build command, language, and