# Refactoring

## Purpose

Improve code structure, readability, maintainability, or modularity without intentionally changing externally observable behavior.

## When to use

- Simplifying complex logic
- Extracting clearer abstractions
- Reducing duplication or coupling
- Preparing code for future work while preserving behavior

## Inputs to gather

- Current behavior and tests that define expected outcomes
- Structural pain points in the relevant modules
- Constraints around public APIs, compatibility, or performance
- Existing patterns for abstraction and module boundaries

## How to work

- Preserve behavior intentionally and define what must remain unchanged before editing.
- Favor small, reviewable moves over sweeping rewrites unless the code is already unsafe to work in incrementally.
- Keep interface changes minimal and justified.
- Add or strengthen tests when behavior preservation is important and current coverage is weak.
- Separate cleanup that supports the refactor from unrelated aesthetic changes.

## Output expectations

- Cleaner code with behavior preserved
- Clear explanation of the structural improvement
- Verification evidence that the refactor did not break expected behavior

## Quality checklist

- Intended behavior is unchanged unless explicitly documented otherwise.
- The resulting structure is easier to understand or extend.
- Interface changes are minimal, justified, and documented.
- Added complexity is avoided unless it buys meaningful maintainability.

## Handoff notes

- Call out any areas where behavior preservation is inferred rather than strongly verified.
- Note future cleanup opportunities only if they naturally follow from the refactor.