Legacy Refactoring Strategy

You cannot refactor what you cannot characterize. Legacy code is code without a behavioral spec; the first job is to discover the spec, not improve the code.

Establish ground truth before touching anything

1. Characterization tests: pin current behavior (including bugs) with tests at the highest stable seam available. These are a regression net, not correctness assertions.
2. Seam map: find the points where you can intercept behavior (interfaces, function boundaries, network calls) without editing tangled internals.
3. Blast radius: trace what depends on the target. Static refs lie under reflection, config-driven dispatch, and serialization — grep is necessary but not sufficient.

Sequencing: make the change easy, then make the easy change

• Never refactor and change behavior in the same commit. Separate "structure-only, behavior-identical" steps from "behavior change" steps so review and git bisect stay meaningful.
• Prefer strangler fig: route a slice of traffic/calls through the new path, expand coverage, delete the old path last.
• Use branch by abstraction for in-process dependencies you can't replace atomically: introduce an abstraction, build the new impl behind it, flip, remove.

Adversarial validation

• What behavior do callers depend on that isn't in the spec — undocumented ordering, timing, error text, log lines parsed downstream, side effects on shared state?
• What happens at the cutover boundary when old and new code run concurrently on the same data?
• Does the "dead" code path actually run? Add telemetry before deleting; "obviously unused" code often has a quarterly cron caller.
• Can you roll back instantly if the new path misbehaves in production, or is the migration one-way?

Non-obvious risks

• The bug-for-bug behavior may be load-bearing: downstream systems may rely on the legacy quirk. Preserve it explicitly or migrate consumers first.
• Improving error handling can change which errors surface, breaking callers that swallowed specific failures.
• Performance characteristics are part of the contract; a "cleaner" abstraction that adds allocations or N+1 queries is a regression.

Output structure

Deliver: a dependency/seam map, the characterization-test plan, an ordered sequence of behavior-preserving steps each independently shippable and reversible, the cutover/rollback mechanism, and the telemetry that proves old paths are dead before deletion.