---
name: refactor-safely
description: Remove dead code, consolidate duplication, or restructure internals while preserving behavior and producing verification evidence.
---

# Refactor Safely

Treat behavior preservation as the contract. Do not combine a broad cleanup with unrelated feature changes.

## Establish evidence

Map entry points, callers, imports, generated-code boundaries, reflection or plugin loading, configuration references, public exports, and tests before deleting or moving code. Static-analysis results are leads, not proof: dynamic references, templates, build scripts, and external consumers may not be visible.

Create or identify characterization tests when important behavior lacks coverage. For duplicate implementations, choose the version whose contract matches current callers and document any intentional behavior change separately.

## Change in reversible steps

Keep each edit small enough to review. Update callers before removing an interface. Preserve compatibility shims when external consumers cannot migrate atomically. Avoid dependency upgrades unless they are necessary for the refactor.

After each meaningful step, run a targeted check. At the end, run the repository's required broader validation and inspect the diff for accidental churn. Measure a claimed performance improvement with a relevant benchmark; do not infer it from fewer lines of code.

## Deletion safety

Do not delete files or dependencies based on a single search result. Require corroborating evidence from references, build output, tests, and runtime conventions. Do not remove migrations, public APIs, feature flags, operational scripts, or compatibility code without explicit scope and ownership evidence.

Report what was consolidated or removed, why it was safe, checks run, and any uncertain consumer left untouched.