By description: Batch behavior-preserving refactors for multi-file, repeated-pattern, large-file, rename, move, extract, split, or restructure work. Use for "refactor across files", "batch rename", "update pattern everywhere", large files (500+ lines), or 5+ coordinated edits in one file. NOT for single targeted edits, behavior changes or bug fixes (use fixing-code), test-only refactors (use improving-tests), code review (use reviewing-code), or architecture redesign (use architecture-design/review). name: refactoring-code
Refactoring Code
Refactor in small, verified batches. If behavior changes, it is not a refactor; it is a feature wearing a fake mustache.
Preconditions
- Understand the current behavior and test coverage.
- Identify the smallest safe batch.
- Run or add tests before broad edits when risk is non-trivial.
- Confirm before large mechanical changes across many files.
Workflow
- Define the refactor goal and non-goals.
- Map all affected sites before editing with available file/text search tools.
- Read representative files and tests.
- Add characterization tests when behavior is under-specified.
- Apply one coherent batch with
editorwrite. - Run narrow tests.
- Run broader lint/type/test checks before the next batch.
- Delete dead code introduced or exposed by the refactor.
Safe Batches
Good batches:
- rename one public symbol and all callers
- move one function/module with tests unchanged
- remove one duplicate implementation after tests prove equivalence
- update one repeated pattern across files
Bad batches:
- rename everything while changing logic
- reorganize modules and change APIs in one pass
- add abstractions for imagined future callers
- edit generated files by hand
Output Contract
## Refactor Result
### Changed
- `path` — what changed
### Behavior
- preserved by <tests/checks>
### Verification
- `<command>` — pass/fail
### Follow-up
- remaining safe batches, if any