Refactor (Behavior-Preserving)

Goal

Improve internal structure without changing observable behavior.

Observable behavior includes outputs, side effects, performance envelopes, error shapes, logging/metrics contracts, and public API compatibility.

Guardrails

• Preserve semantics first; readability second.

• Keep changes small and mechanical; verify after each step.

• Do not mix refactors with feature changes in the same diff.

• Prefer compiler/typechecker + tests as the safety net.

If the code has no tests, start by adding characterization tests around the current behavior (including edge cases and error paths).

Workflow

Establish a baseline.

• Run existing tests and record what passes/fails.

• Capture key behaviors with a quick harness if tests are missing.

• Make a checkpoint commit before refactoring.

Pick a single refactor target.

• Choose the smallest change that reduces future risk.

• State the intent in one sentence (example: "Extract parsing from IO to enable unit tests").

Refactor in tight loops.

• Apply one operation (rename, extract, inline, move).

• Re-run the relevant tests or checks.

• Repeat until the target improvement is achieved.

Confirm "no behavior change".

• All tests pass.

• No unintended public API changes.

• No new side effects or missing side effects.

Clean up.

• Remove dead code introduced by the move.

• Update comments that describe outdated structure.

• Leave a small, reviewable diff.

Common Moves

• Rename for intent (types, functions, variables).

• Extract function/method to reduce nesting and isolate responsibilities.

• Inline trivial wrappers that add indirection without value.

• Introduce parameter object when argument lists grow.

• Replace nested conditionals with guard clauses.

• Extract shared logic to eliminate duplication.

• Split large modules by responsibility and boundary.

References (Load As Needed)

• refactor/references/checklists.md : safe workflow, review checklist, and "no tests" strategy.

• refactor/references/recipes.md : code smells mapped to refactor recipes with small examples.

• refactor/references/operations.md : quick list of common refactoring operations.

• refactor/references/patterns.md : type-safety refactors and when to use design patterns during a refactor.