Legacy Module Strangler Migration

Multi-step agent workflow. Replaces a legacy module incrementally: pin current behavior with tests, route calls through a facade, migrate one capability at a time with shadow comparison, retire on evidence.

License: CC0-1.0 · By waxmark · v1 · 2026-11-02

Share on X

Add a trust badge to your README

[![Waxmark](https://waxmark.app/api/badge/legacy-module-strangler-migration)](https://waxmark.app/items/legacy-module-strangler-migration/scan)
Report
# Legacy Module Strangler Migration

Replace `{{LEGACY_MODULE}}` incrementally. Goal of the replacement: {{REPLACEMENT_GOAL}}. Known callers: {{CALLERS}}. Verification: `{{TEST_COMMAND}}`. Shadow comparison sample rate during migration: {{SHADOW_SAMPLE_RATE}} (default 100% in non-production, 5% in production).

The old module keeps working until the last step. Every phase leaves the system deployable, and every phase can be reverted by flipping a flag or reverting one commit. If a step cannot meet that bar, the step is too big; split it.

## Phase 1: Characterize

1. Read `{{LEGACY_MODULE}}` in full. List its public surface: every function, class, endpoint, or message handler that anything outside the module uses. Confirm the list against `{{CALLERS}}` by searching the codebase; add callers the list missed.
2. For each public entry point, write down its observable behavior as you find it, including the odd parts: special-cased inputs, error types, side effects (writes, emails, metrics), ordering guarantees. The replacement must honor these unless {{REPLACEMENT_GOAL}} says otherwise; mark the ones it intentionally changes.
3. Write characterization tests that pin current behavior: call each entry point with representative and edge inputs and assert on what it does today, even where today's behavior is wrong (mark those `# legacy behavior, see <issue>`). Run `{{TEST_COMMAND}}`. **Check:** all green against the legacy module.
4. Measure the baseline: request volume per entry point, latency percentiles, error rate, if observability exists. If it does not, add minimal instrumentation to the legacy module now; you cannot compare what you cannot measure.
5. **STOP POINT.** Present the public surface, the behavior inventory with intentional changes marked, the characterization test count, and the baseline numbers. Wait for agreement on what "behaves the same" means for this migration.

**Artifact:** `STRANGLER-{{LEGACY_MODULE}}.md` with surface, behaviors, intentional deviations, baseline.

## Phase 2: Seam

6. Introduce a facade with the same public surface that initially delegates every call to the legacy module unchanged. Repoint `{{CALLERS}}` to the facade, one caller per commit. Run `{{TEST_COMMAND}}` after each.
7. Add a per-entry-point routing switch (feature flag or config) to the facade with three positions: `legacy`, `shadow` (call both, return legacy, compare), `new`. Default `legacy`.
8. Add the comparison hook for `shadow`: record mismatches with the inputs (redacted as needed), both outputs, and the entry point. Sample at {{SHADOW_SAMPLE_RATE}}.
9. **Check:** behavior unchanged (characterization tests green; baseline metrics unchanged after deploy). The system is now ready for replacement work with zero behavior change so far.

**Artifact:** facade, flags, comparison hook; a short diagram of call flow in the artifact file.

## Phase 3: Migrate, one capability at a time

10. Choose the next entry point. Prefer, in order: lowest risk with highest learning (simple, well-tested, moderate traffic), then the ones {{REPLACEMENT_GOAL}} values most. Record the order and reasoning.
11. Implement the replacement for that entry point only, in the new module, meeting the behavior inventory from step 2. Point the characterization tests at the new implementation as well; they must pass for both.
12. Flip the entry point to `shadow` in non-production, then production. Run for long enough to cover the input distribution (at least one full business cycle for anything periodic). **Check:** mismatch rate at or below the agreed threshold; every mismatch class is either a legacy bug being fixed intentionally (documented) or a defect in the new code (fixed).
13. Flip to `new`. Watch error rate and latency against the baseline for a defined soak period. **Check:** within tolerance. If not, flip back to `legacy` (one config change) and investigate; do not fix forward under load.
14. **STOP POINT** after each entry point reaches `new` and completes soak: report mismatch findings, legacy bugs discovered, and metrics. Confirm before starting the next entry point.
15. Repeat until every entry point is on `new`.

**Artifact:** per-entry-point record in the artifact file: dates flipped, mismatch summary, soak result.

## Phase 4: Retire

16. **Check:** every entry point has been on `new` for the full soak period, no flag has been flipped back in that time, and no caller references the legacy module directly (search again).
17. Remove the `legacy` and `shadow` paths from the facade, then the comparison hook, then the legacy module itself, in separate commits so each is independently revertable for one release cycle.
18. Update the characterization tests: drop the `legacy behavior` markers where behavior intentionally changed; keep the tests as the new module's regression suite.
19. Update documentation and ownership. Close the migration in the artifact file with final metrics vs baseline and lessons for the next strangler.

**Final artifact:** `STRANGLER-{{LEGACY_MODULE}}.md` complete; legacy code removed; tests green.

## Rules throughout

- Never migrate two entry points in one flip.
- Never change a behavior the inventory marks as preserved without going back to the Phase 1 stop point.
- Treat every mismatch as information, not noise. If the comparison is too noisy to read, fix the comparison before continuing.
Legacy Module Strangler Migration · Waxmark