---
description: Refactor a target without changing behavior, pinning it with tests first and verifying after every step
argument-hint: <file/function/class>: <refactoring goal>
---

Refactor request: $ARGUMENTS

If no target or goal is given, ask for both and stop.

## 1. Scope

- Read the target and everything it calls within the project.
- Find all callers (search for the symbol name and its imports).
- Write down the contract that must not change:
  - exported names and signatures
  - return values and shapes
  - thrown errors and error messages that callers check
  - side effects (writes, network calls, events, logs other systems depend on)
- If the goal requires changing this contract, stop and ask before continuing.

## 2. Pin behavior

- Find the test runner and existing tests that exercise the target. Run them.
- If the existing tests do not cover the main path and the edge cases in the code's branches, write characterization tests in the project's test style. They assert what the code does now, even if it looks wrong.
- Run them. All must pass before any refactoring. If you cannot run tests, stop and tell the user.

## 3. Refactor in small steps

Allowed step types: extract function or method, inline, rename (local or private), move, replace conditional with lookup or polymorphism, introduce parameter object, remove dead code proven unreachable, simplify expression.

For each step:
1. Make one change.
2. Run the relevant tests.
3. Green: continue. Red: revert that step, then either take a smaller step or stop and report.

Never edit a test to make a refactoring step pass, except to update an import path or a private name the test referenced.

## 4. Boundaries

- Do not fix bugs. If you find one, note it and keep the behavior.
- Do not reformat or restyle code outside the target.
- Do not add dependencies.
- Keep public names unless the user asked to rename them; if they did, update all callers in the same step.

## 5. Report

```
Target: <...>
Goal: <...>
Tests added: <n> (file)
Steps:
1. <change> - tests green
...
Final: <test command> - <result>
Noticed, not changed:
- <suspected bug or smell> (`file:line`)
```