Safe Refactor
Treat behavior preservation as a claim that requires a baseline and repeated evidence.
Define Observable Behavior
Include public APIs and types, serialized and database representations, errors, logs and events, generated output, filesystem effects, performance budgets, deployment compatibility, and user-visible behavior that callers rely on.
Refactor Loop
- Inspect repository instructions, worktree status, callers, tests, and generated-code boundaries. Preserve unrelated work.
- Establish a green focused baseline. If coverage is thin, add characterization tests that capture current behavior before changing structure.
- Make one mechanical step: rename, extract, move, or deduplicate.
- Update direct callers and search for dynamic references in configuration, reflection, templates, serialization, migrations, documentation, and build tooling.
- Run the smallest relevant checks after each step and expand to the full affected suite at stable checkpoints.
- Keep behavior fixes and compatibility migrations outside the refactor. Pause and reclassify the task when a behavior change becomes necessary.
- Use logical working-tree checkpoints. Do not create branches or commits unless the user explicitly requests them.
Completion Evidence
- Show that focused and relevant suites remain green against the baseline.
- Confirm snapshots, golden files, generated output, and public contracts did not change unless explicitly approved.
- Search for obsolete names and paths after moves or renames.
- Review the final diff for a clear structural improvement and no hidden behavior change.
1---2name: safe-refactor3description: Change internal code structure while preserving observable behavior through small verified steps. Use for renames, extractions, moves, decomposition, and duplication removal when behavior must remain stable. Do not use for bug fixes, public contract changes, dependency or framework migrations, schema migrations, or other work expected to change compatibility or runtime behavior.4---56# Safe Refactor78Treat behavior preservation as a claim that requires a baseline and repeated evidence.910## Define Observable Behavior1112Include public APIs and types, serialized and database representations, errors, logs and events, generated output, filesystem effects, performance budgets, deployment compatibility, and user-visible behavior that callers rely on.1314## Refactor Loop15161. Inspect repository instructions, worktree status, callers, tests, and generated-code boundaries. Preserve unrelated work.172. Establish a green focused baseline. If coverage is thin, add characterization tests that capture current behavior before changing structure.183. Make one mechanical step: rename, extract, move, or deduplicate.194. Update direct callers and search for dynamic references in configuration, reflection, templates, serialization, migrations, documentation, and build tooling.205. Run the smallest relevant checks after each step and expand to the full affected suite at stable checkpoints.216. Keep behavior fixes and compatibility migrations outside the refactor. Pause and reclassify the task when a behavior change becomes necessary.227. Use logical working-tree checkpoints. Do not create branches or commits unless the user explicitly requests them.2324## Completion Evidence2526- Show that focused and relevant suites remain green against the baseline.27- Confirm snapshots, golden files, generated output, and public contracts did not change unless explicitly approved.28- Search for obsolete names and paths after moves or renames.29- Review the final diff for a clear structural improvement and no hidden behavior change.
adityaarakeri