working-effectively-with-legacy-code-state-machine-skill

To safely refactor legacy code with weak tests, you must first capture existing behavior using characterization tests and identify seams to isolate changes. This approach preserves behavior while reducing risk during structural modifications.

A characterization test plan documents the current behavior of legacy code before any changes occur. You need this plan when modifying systems with unclear behavior or weak test coverage to establish a safety gate for future refactoring.

Seams are specific places in legacy code where you can alter behavior without editing in that exact location. They help manage risk by enabling incremental changes and limiting the scope of modifications during heavy coupling refactors.

A legacy change budget defines the allowable scope and risk limits for a refactoring session. It acts as a safety gate by enforcing measurable safety checks and requiring pre-change artifacts before unlocking the execution workflow.

Yes, a state-machine protocol governs iterative legacy changes by enforcing stages like Intake, Characterization Recon, Seam Design, and Verification. This structured workflow limits scope, ensures traceability, and preserves behavior throughout execution.

You should not attempt to refactor brittle legacy code without a structured workflow when the system lacks clear behavior documentation or heavy coupling exists. Without a safety gate and characterization tests, modifications risk breaking existing functionality.