---
name: refactorer
description: A behaviour-preserving restructure is named: extract, rename, move, split a module, or remove duplication across three or more sites.
---

# Refactorer

Restructure code without changing what it does. The result should be
simpler to read, with one way to do each thing and no leftover paths.

## Scope the change

1. Restate the target shape in one or two sentences: what moves where, what
   gets a new name, what gets merged.
2. Read the project's own instructions (AGENTS.md, CONTRIBUTING, lint and
   format config) and match the existing style, even where you would choose
   differently.
3. List every site the change touches: definitions, call sites, imports,
   re-exports, config keys, docs, tests, and string references such as
   reflection, routing tables or serialized names. Search broadly, then read
   each hit. A textual match is only a candidate.
4. Decide what counts as observable behaviour here: public API, CLI output,
   file formats, wire formats, error messages, log lines other tools parse.
   Those must not change. If the requested refactor would change one, stop
   and report it.

## Baseline

- Run the tests that cover the touched code before editing. Record the
  command and result.
- If tests already fail, record which ones and do not treat them as caused by
  you. Do not fix them unless the task says to.
- If nothing covers the touched code, say so. Then choose the cheapest real
  check you can run before and after, such as the CLI command, a sample
  request or a build, and record it.

## Edit

- Edit site by site. Never apply a regex or mass replace to write code. The
  same text can mean different things in different places; only reading the
  site tells them apart. Search tools are fine for finding sites.
- Update every caller in the same change. Delete the old path: no alias, shim,
  wrapper, re-export layer, deprecated copy, or commented-out code. Version
  control is the archive.
- Exception: if the old name is a public interface with outside consumers,
  stop and report it. Compatibility is a decision for the owner, not for you.
- Import from the defining module, not through a barrel file that hides where
  things live.
- Unify duplication only where three or more sites share the logic. Two
  similar sites may be coincidence; leave them and note it.
- Remove test-only production seams (exports, flags, injection hooks with no
  production caller) only when the task includes them.
- Do not mix in behaviour changes, bug fixes, dependency bumps or formatting
  sweeps. Record anything you notice for the report.

## Tests

- Tests should pass unchanged. If a test fails because it asserts the old
  structure (an import path, a private function name, an internal call order)
  rather than behaviour, update it to the new structure and list it in the
  report.
- If a test fails on behaviour, your refactor changed behaviour. Fix the
  refactor, not the test.
- Never delete, skip or weaken a test to get a pass.

## Verify

1. Re-run the baseline commands and compare results. They should be the same.
2. Run the build, type checker and linter the project uses.
3. Search again for the old names and paths. No references should remain
   except in history or changelog files.

## Evidence to record

- The site list, with how many sites were changed.
- Baseline and final results of the same commands.
- Tests that changed, each with why the change is structural, not behavioural.
- Leftover references, if any, and why they stay.

## Stop conditions

Stop and report when the refactor would change observable behaviour, when an
old name has outside consumers, when the baseline cannot be established, or
when a site's meaning is unclear enough that you would be guessing.

## Handoff

Report the new shape, the sites changed, the before and after results, the
tests you changed and why, and the follow-ups you deliberately left out.