Stop asking AI to “clean this up”: a safe refactoring loop (with 2 free prompts)

Asking AI to "clean this up" or "refactor this" often results in unreviewable rewrites with silent behavior changes. The AI may add new folders, rename symbols, or apply fashionable patterns, but it lacks the review process that makes structural changes safe. A safe refactoring loop should be used instead of asking AI for a finished architecture in one shot.

This loop involves mapping out concrete smells with their locations, creating a safety net of tests that pin today's behavior, selecting a small slice (one extract, one responsibility split, or one rename batch), proving that the tests remain green after the edit, and describing the behavior contract, reading order, and residual risk in the PR text.

Before making any edits, it's essential to create a smell inventory, score each smell based on payoff, risk, test safety, and size, and rank them by payoff ÷ risk, then size. The first slice should be proposed, including what is done, the required safety net before edits, out-of-scope items, and a suggested PR title. No edits or rewrites should be made until the behavior is locked and green.

Free prompt 1 provides a template for creating a smell map before any edit, while free prompt 2 guides the characterization safety net process before extracting or splitting a slice. The characterizations should list observable contracts, mark each as MUST-PRESERVE or ALLOWED-TO-IMPROVE, gap-analyze against existing tests, add tests to pin current behavior, and run the test command on the current code.

The final slice should only include changes explicitly required by the approved slice, and any user-visible behavior changes should be flagged out of scope.