Refactor Safely

Changes the structure of code without changing its behaviour, one smell at a time, under a green test. The smell vocabulary and Boy-Scout rule are here; readability rules are in write-readable-code.

1. Audit (change nothing)

cat .claude/stack-profile.md 2>/dev/null | head -20
git status --short 2>/dev/null
ls tests 2>/dev/null || find . -name "*_test.*" -o -name "*.test.*" 2>/dev/null | head

Confirm two preconditions before touching anything: the tree is clean (or changes are committed) and a test covers the code you will move. If neither holds, stop and say so — refactoring without a safety net is editing, not refactoring.

2. Name the smell

3. Refactor in discipline

• One smell at a time, and run the tests after each move — never a batch that changes many things at once.
• Separate refactoring from behaviour change: refactor and feature land in different PRs.
• Prefer mechanical, reversible moves (extract, rename, inline, move) over clever rewrites.
• Leave the Boy-Scout rule as the default: make the touched code cleaner than you found it, but do not expand the blast radius to unrelated files.

Verify

The tests pass unchanged (you did not edit them except to add one), the public behaviour is identical, and the diff reads as moves and renames. State the smell found and the refactor applied in the note.

When to deviate

• No tests and no easy way to add one: make the smallest mechanical move and label it unverified.
• The smell is actually load-bearing performance: measure before changing (see engineering-principles.md — measure before optimizing).