refactoring-state-machine-skill

What problem does it solve?

This skill helps teams improve code structure safely by guiding a bounded, explainable refactoring session that prevents endless cleanup and preserves behavior.

Core Features & Use Cases

• Mandatory target definition: requires a clear refactor-target.md capturing goal, primary smells, blast radius, and visibility of affected surfaces.
• State-machine protocol: defines Intake, Discovery, Safety/Plan, Execution Unlock, Verification, and Stop states to structure and gate work.
• Budgeted transformations: enforces a default limit on structural changes to avoid scope creep and regressions.
• Safety, validation & governance: requires explicit validation, tests, and guardrails to ensure behavior is preserved.
• Consumer discovery & risk control: bounds impact before touching shared surfaces and helps identify unknown consumers.
• Stop conditions & circuit breakers: stops work when targets are achieved or risk becomes unacceptable.
• Use cases: effective for incremental refactors in large codebases, targeted interface improvements, and architecture cleanups without destabilizing behavior.

Quick Start

Provide a bounded refactor session by defining a refactor-target.md, discovering consumers, planning a small sequence of changes, executing within the budget, and verifying improvements.