Behavior preservation is non-negotiable. Every refactoring must leave all existing tests passing. If a change breaks a test, revert it immediately and try a different approach.

Discover first, prescribe only as fallback. Adapt to whatever language, framework, and conventions the codebase already uses. Align refactored code with these conventions rather than imposing external style preferences.

Small, verifiable steps. Apply one refactoring at a time. Verify compilation/parsing after each change. This makes failures easy to diagnose and revert.

Public API stability. Do not change public function signatures, type names, module exports, or other externally visible interfaces unless explicitly requested. Internal restructuring is the focus.

Preserve all existing test behavior (all tests that passed before must still pass)

Follow the codebase's existing conventions (naming, module layout, error handling, coding style)

Not change the public API of any module, crate, or package

Compile or parse without errors or warnings where possible

Improve code quality in at least one measurable dimension (duplication, complexity, readability, naming, style consistency)

If target files are missing, ask the user or attempt to infer them from the test files or target packages

If the test command is missing, attempt to discover it from the build system (see Step 3)

If test files are provided, note them for later analysis; if not, attempt to find them via naming conventions (e.g., *_test.rs, test_*.py, *.test.ts, *_spec.rb)

If feedback has been provided (from a failed test run, reviewer, or human), read the previously modified files and revise them rather than starting over

Address each feedback point: revert a problematic refactoring, try a different approach, undo a change that broke tests, or provide a reasoned rebuttal for feedback you disagree with

When revising, re-read the current test output carefully — the failures indicate which refactorings were unsafe

Use glob to search for build and configuration files in the relevant packages:

Read the relevant config files to understand the project structure, dependencies, and any linting or formatting tools configured

Use glob and grep to find source files in the target packages

Use read_file to examine 2–3 representative source files (other than the target files) to learn:

Read every target file to understand the current implementation

If test files are available, read them to understand what behavior is being tested — this defines the contract that must be preserved

Note the public API of each target file: exported functions, types, constants, traits, classes, and their signatures

Repeated code blocks that could be extracted into a shared function or method

Similar match arms, branches, or case statements that could be consolidated

Copy-pasted logic with minor variations that could be parameterized

Variables, functions, types, or constants with unclear, misleading, or inconsistent names

Names that do not follow the codebase's naming conventions

Abbreviations that harm readability without saving meaningful space

Boolean variables or functions that do not read as predicates (e.g., flag vs is_enabled)

Functions or methods that are too long (doing too many things)

Deeply nested conditionals or loops that could be flattened with early returns, guard clauses, or extraction

Complex boolean expressions that could be named with a descriptive variable or helper function

Functions with too many parameters that could use a configuration struct or builder

Code that does not follow the codebase's established patterns (e.g., manual loops where the rest of the codebase uses iterator chains)

Inconsistent error handling (e.g., mixing unwrap() with proper Result handling in a Rust codebase that uses ? everywhere else)

Inconsistent formatting or structure relative to sibling files

Unused imports, variables, functions, types, or fields

Commented-out code blocks with no explanatory context

Unreachable branches or match arms

Functions or methods that would be more logically placed in a different module or file

Missing or inconsistent grouping of related functionality

Overly large files that could be split into focused modules

List each refactoring to apply, in order

For each refactoring, note:

Order refactorings from safest to riskiest — if an early refactoring breaks something, the riskier ones never execute

Group related refactorings (e.g., extract a function, then use it in three places)

If a refactoring focus was provided, prioritize changes in that area but still apply other clear improvements

Use edit_file or apply_patch for targeted modifications to existing files

Follow the codebase's conventions discovered in Step 3

Do not change public API signatures, exports, or externally visible behavior

When extracting functions: place them near the call site or in a location consistent with the codebase's module organization; choose a name that clearly describes what the function does

When renaming: update all references within the file and, for non-public items, in other files within the same package

When removing dead code: verify the code is truly unreachable or unused by searching for references with grep before deleting

Compiled languages (Rust, Go, C/C++, Java, C#, Swift, Kotlin, Scala): Run the appropriate check command:

Interpreted languages (Python, Ruby, R, Shell): Run a syntax check:

Transpiled languages (TypeScript): Run the type checker:

Fix the errors immediately if the fix is straightforward

If the fix is not straightforward, revert the change and note it as an unsafe refactoring in the summary

Do not proceed to the next refactoring with broken compilation

If all tests pass, continue

If any test fails:

Rust: cargo fmt -p <crate>, cargo clippy --fix --allow-dirty -p <crate>

Python: check for ruff, black, isort in project config and run them

TypeScript/JavaScript: check for prettier, eslint in project config and run them

Go: gofmt -w <file> or goimports -w <file>

Refactored files — the list of production code files modified

Refactoring summary — for each refactoring applied:

Refactorings not applied — any planned refactorings that were skipped or reverted, with reasons

Verification result — the test command run and its outcome (all tests passing)

Public API impact — confirm that no public API was changed (or list any intentional changes if explicitly requested)

references/example-extract-function-rust.md

references/example-naming-and-style-python.md

references/example-reduce-duplication-typescript.md

references/example-revert-unsafe-refactoring.md

No clear refactoring opportunities: If the target code is already clean, well-named, and follows codebase conventions, report this finding rather than making unnecessary changes. Not every code needs refactoring.

Refactoring would require changing the public API: Do not change public function signatures, type names, module exports, or trait definitions unless the user explicitly requests it. Internal restructuring only. If a public API change would significantly improve quality, note it as a recommendation in the summary.

Refactoring improves one quality dimension but degrades another: Prefer the version that is clearest to read. For example, extracting a tiny two-line function may reduce duplication but add indirection — skip it if the duplication is only in two places and the code is clear.

Test failures after refactoring: Immediately revert the change that caused the failure. Do not attempt to fix the test — the refactoring was unsafe if it changed behavior. Note the reverted change in the summary.

Large files with many issues: Focus on the highest-impact improvements first. Do not try to perfect an entire file in one pass — make the most valuable changes and note remaining opportunities for future passes.

Code that is already partially refactored (revision scenario): When receiving revision feedback, read the current state of the code carefully. Some refactorings from the previous attempt may have been correct — preserve those and only address the feedback points.

Conflicting conventions in the codebase: If different parts of the codebase use different styles (e.g., some files use snake_case and others use camelCase), follow the convention used by the majority of files in the same package or module. Note the inconsistency in the summary.

Dead code that might be used by external consumers: Before removing apparently dead code, use grep to search the entire project for references. If the code is part of a public API or library, it may have consumers outside the current codebase — do not remove it unless you can confirm it is unused.

Refactoring across multiple files: When a refactoring spans multiple files (e.g., extracting a shared type to a common module), make all the changes needed for the refactoring to be complete — do not leave files in an inconsistent state. Verify compilation after the full set of related changes.

Performance-sensitive code: If code has comments indicating performance sensitivity (benchmarks, hot paths, optimization notes), be conservative with refactorings that could affect performance (e.g., adding function call overhead, changing data structures). Note any concerns in the summary.