refactor

Refactor Workflow

When to use

• Restructuring code that violates the Constructor Pattern (file >200 LOC, function >30 LOC, multiple responsibilities, duplicated code).
• Safe refactoring that must preserve existing behaviour — checkpoint, tests baseline, extract, verify.
• When wave-audit or /dev-guard flags a structural issue that requires decomposition.

Step 1: Understand Current State

• Read target file(s) completely
• Identify existing tests for the target
• Run existing tests — baseline must pass
• Document current behavior (inputs → outputs)

Step 2: Plan Refactoring

• Identify what violates Constructor Pattern:
  • File >200 lines → decompose
  • Function >30 lines → extract
  • Multiple responsibilities → split
  • Duplicated code → single source
  • Overlay/patches → root formula
• List concrete changes BEFORE making them

Step 3: Checkpoint

• checkpoint: before refactor $target

Step 4: Refactor (Incremental)

• ONE structural change at a time
• After each change: run tests
• If test breaks → fix immediately or revert
• Preserve all public interfaces unless explicitly changing them

Step 5: Audit

• Check: does refactored code follow Constructor Pattern?
• Check: no overlay, no dead code, no orphaned imports
• Check: SSOT — no duplicated logic
• Check: file sizes within limits

Step 6: Final Verification

• Run full test suite — all pass
• Diff review: no accidental behavior changes
• No new dependencies added without reason

Step 7: Commit

• refactor: <what was restructured and why>