cs-refactor

A safe code refactor is automated by a three-stage workflow: scan to identify improvements, design to map changes to methods, and apply to execute incrementally with validation and rollback logging. This process preserves observable behavior while improving structure, performance, or readability through explicit user gates.

An auditable code refactor workflow is best structured as an artifact-driven process that generates per-skill outputs like scan.md, refactor-design.md, and apply-notes.md within a versioned refactor directory. This approach ensures clear checkpointing and maintains traceability for human-in-the-loop decisions.

Low-risk code refactors can skip full stages using fastforward mode. This mode enables small, low-risk changes to safely bypass the complete scan, design, and apply workflow when safe, accelerating the process while maintaining behavior equivalence and structural integrity.

A three-stage workflow for code refactoring is needed when targeting complex changes that require strict traceability and safe execution. The scan, design, and apply stages enforce explicit gates and human approval, ensuring changes preserve behavior while systematically improving code quality, performance, or readability.

AI-assisted refactoring works with manual approval checkpoints by enforcing explicit user gates for progression. The workflow requires human-in-the-loop decisions at each stage—scan, design, and apply—ensuring developers maintain control and validate behavior equivalence before any structural changes are applied.

The limitation of behavior-preserving refactors is that changes touching observable behavior are strictly avoided unless they address a specific feature or issue. This constraint ensures safe refactors but means the workflow cannot be used for tasks requiring intentional modifications to external functional outputs.