9.2 Choosing a model for complex refactors

The goal for complex refactors

Complex refactors are where you most need correctness, coherence, and risk awareness. The goal is not “rewrite the code.” The goal is:

• preserve existing behavior,
• improve structure or change internals safely,
• keep diffs reviewable,
• keep verification tight (tests, checks, ship points).

Why refactors are harder than greenfield

Refactors have hidden constraints:

• existing users (even if “users” are other modules),
• implicit contracts not written down,
• edge cases encoded in weird code paths,
• tests that reflect reality (and will catch regressions).

Greenfield code can be “plausible.” Refactors must be compatible.

Signals you need a “smarter” model

Use a stronger reasoning model when:

• the change spans multiple modules and you need a coherent plan,
• you must preserve complex behavior and avoid subtle regressions,
• the code is messy and you need accurate explanation first,
• you need tradeoff analysis (multiple viable architectures).

Even then, don’t ask it to “do the whole refactor” in one shot. Use it to produce a plan you can trust.

A safe refactor workflow (plan → diff → tests)

1. Explain first: force a correct understanding of current behavior.
2. Plan: 3–8 steps, each with explicit verification.
3. Diff-only step 1: implement the smallest safe step.
4. Run tests: after each step.
5. Commit at ship points: keep it reversible.

This is model-agnostic. The model choice affects how trustworthy the plan is, not whether you should skip the workflow.

Split-brain strategy: smart for design, fast for implementation

One of the best patterns for teams:

• Smart model: produce plan, risk list, invariants, test strategy.
• Fast model: implement step 1, step 2, step 3 as small diffs.
• You: review diffs, run tests, correct assumptions.

This gets you the reasoning benefits without paying the “smart model tax” for every mechanical edit.

Guardrails that prevent disasters

• Diff-only changes (see Part III 7.5).
• File scope (“only touch these files”).
• Line budget (“stop if diff exceeds N lines”).
• Tests-first for behavior changes or bug fixes.
• One step at a time with verification after each step.

Where to go next

• 9.3 When to switch models mid-project
• Reference: explain then rewrite