Refactoring

Scope and workflow

Apply only when the user explicitly invokes this skill. Work on the module, file, class, functions, or whole codebase they select; inspect callers and dependencies as needed to preserve contracts. If no target can be inferred, ask for it before editing.

Inspect the target, repository instructions, callers, tests, and verification commands. Identify observable behavior, side effects, error semantics, and compatibility constraints.
Identify concrete structural friction and select the smallest useful transformations. For a whole-codebase request, inventory the major areas, prioritize by impact and risk, and work through coherent slices. Track completed, deferred, and uninspected areas so one improved file is not reported as a completed codebase refactor.
Establish a baseline with relevant checks. Add characterization coverage before risky changes when behavior is unclear; record pre-existing failures and verification gaps.
Apply one coherent transformation at a time and verify affected behavior after each meaningful step. Continue through the requested scope while improvements remain justified. Implement feature or bug-fix behavior only when separately requested.
Review the diff for unintended behavior changes and unrelated churn. Report what improved, checks run and their results, and any remaining work or uncertainty.

Detailed reference

Read only the relevant sections of refactoring.md when the current transformation needs more detail: