Strangler-Fig Migration

Prerequisite

Do not start without: code-archaeology findings for the target module, and characterization tests pinning its current behavior (consult those skills first if either is missing — this skill assumes both exist).

Facade-first setup

1. Introduce a facade at the module's existing public boundary (same signature, same call sites) that currently just delegates 100% of calls to the legacy implementation. Ship this alone first, with the characterization tests passing against it unchanged — proves the facade is transparent before any real migration work starts.
2. Slice the module into independently-migratable vertical slices (by feature/endpoint/route, not by file) — each slice should be revertible on its own.

Per-slice checklist (repeat for every slice, in order — do not skip steps)

1. Characterization tests for this slice specifically, if not already covered by the module-level suite.
2. Build new: implement the slice's replacement behind the facade, untouched by the old code path yet — old and new coexist.
3. Equivalence (use /equiv-plan): validate new matches old on this slice's exercised input space. Do not proceed on DIVERGENT findings without resolving them or making an explicit, logged decision to accept the behavior change.
4. Flip flag: route this slice's traffic to the new implementation behind a feature flag (consult feature-flag-change skill), old path stays intact and reachable.
5. Observe: state what "safe to retire old path" means for this slice (error rate threshold, time window, or explicit sign-off) before retiring anything — never retire on the same change that flips the flag.
6. Retire old path for this slice only, once the observation criterion is met. Remove the flag once retirement is confirmed stable.

Rollback (per slice, not just at the end)

Each slice's flag flip must be revertible independently: flipping back to old must not require reverting other slices' migrations. State the exact revert command/flag-toggle for each slice when you flip it, not after.

Anti-patterns

• Never migrate a slice without an equivalence check first — "looks equivalent" is not a substitute for /equiv-plan's exercised-input-space comparison.
• Never retire the old path in the same step as the flag flip — that collapses the safety margin the whole pattern exists to provide.
• Never treat the facade step as optional "since we're being careful anyway" — the facade is what makes each slice revertible without touching call sites again.