# Rewrite vs. Incremental Strangler Decision

Use this reference only when the user is genuinely undecided between a full rewrite and an incremental strangler-fig migration. If the user has already committed to one path, do not relitigate it here — go to the relevant execution reference instead.

## What people get wrong

The common bad assumption is:

> "The old code is so bad that a rewrite is obviously faster."

That is almost never true at the scope people imagine. A rewrite discards the accumulated bug fixes, edge-case handling, and business-rule knowledge encoded in the legacy UI — knowledge that usually is not written down anywhere else. Teams that rewrite typically re-discover that knowledge the hard way, in production, after cutover, when rollback is hardest.

The inverse bad assumption is also common:

> "We should never rewrite; incremental is always safer."

That is also false. If the legacy runtime model is fundamentally incompatible with the target (e.g. synchronous global-state jQuery plugins that assume full-page reloads, wired into a codebase with no seams at all), forcing an incremental strangler pattern onto it can cost more than a bounded rewrite of a small, well-scoped surface.

## Decision criteria (score each, do not eyeball it)

Ask these questions and get concrete answers, not vibes:

1. **Are there any existing seams?** Route boundaries, iframe boundaries, distinct page loads, or module boundaries where legacy and new code could coexist without deep coupling. No seams at all is the strongest signal toward a bounded rewrite of that specific surface — not the whole app.
2. **What is the blast radius of the surface in question?** A single internal admin page vs. the primary customer checkout flow have very different risk tolerances for "big bang" replacement.
3. **Is there a shared auth/session model that both stacks must honor simultaneously?** If yes, this is a hard security gate (see SKILL.md operating rules) and it must be solved before any coexistence phase, regardless of which path you choose.
4. **How much business logic is embedded in the view layer with no test coverage?** High untested logic in the view layer favors strangling in small verifiable slices, not a big-bang rewrite, because you can diff behavior slice-by-slice.
5. **What is the team's real capacity to run two stacks in production concurrently?** Strangler patterns are not free — they cost ongoing dual-stack operational overhead (two build pipelines, two deploy paths, two sets of dependencies to patch). If the team cannot sustain that for the migration's duration, say so explicitly; it changes the sequencing, not the recommendation to avoid rewrite.
6. **Is the target framework migration path officially supported for incremental coexistence?** For example, Next.js explicitly documents `app/` and `pages/` directories coexisting and recommends breaking migration into small steps (Context7-verified: `vercel/next.js` docs, `app-router-migration.mdx`). Absence of an official coexistence path for a given framework pair is a signal toward more conservative, smaller-scoped increments — not automatically toward a rewrite.

## Default and its exception

**Default: incremental strangler-fig migration**, scoped by seam (route, module federation boundary, or adapter layer), sequenced business-risk-first (§ see SKILL.md phase sequencing).

**Exception — recommend a bounded rewrite only when:**
- no viable seam exists for the surface in question, AND
- the surface is small/isolated enough that its blast radius is contained, AND
- the team explicitly accepts the rewrite's discovery risk (silent behavior regressions) with a stated verification plan (parity testing, feature-flagged rollout, or shadow traffic comparison).

Never recommend a rewrite for an entire application as a first move. If the user pushes for "just rewrite it all," push back and ask for the seam analysis above first.

## When to push back

Push back if the user says:

- "The old code is a mess, let's just start over" — with no seam analysis and no scoping of blast radius.
- "We'll run both stacks forever, it's fine" — dual-stack maintenance without a decommission time-box is not a migration, it's permanent debt (see `rollback-and-exit-criteria.md`).
- "Auth can stay separate for now, we'll unify it later" — unresolved shared-session risk is a security gate, not a deferred nice-to-have.

Those are not pragmatic shortcuts. They are how migrations become permanent, half-finished liabilities.

# Rollback and Exit Criteria

Use this reference when defining or auditing what makes a migration phase safe to promote, and what makes legacy code eligible for decommission. Every phase in a migration plan produced by this skill must satisfy the rules below — a phase with a date-only gate and no measurable exit criteria is not a real gate.

## What people get wrong

The common bad assumption is:

> "We'll know it's done when it feels stable / when the sprint is over."

That is not an exit criterion, it is a shrug. A migration plan that cannot say, in advance, exactly what evidence promotes a phase and exactly what action reverts it is not a plan — it is hope with a Gantt chart.

## Non-negotiable design rules

### 1. Every phase needs a rollback action completable within one deploy cycle

Not "we could revert the commit eventually." A concrete, rehearsed action: flip a feature flag, revert a route-table entry (see `strangler-boundary-design.md`), or redirect the fallback proxy back to the legacy origin. If the rollback action requires a data migration to reverse, it is not a one-deploy-cycle rollback — flag that phase as higher risk and require an explicit sign-off before it ships, not an assumption that "we probably won't need to roll back."

### 2. Every phase needs a measurable exit metric, not a date

Acceptable exit metrics (pick what's relevant to the phase, be specific, not generic):

- **Correctness parity**: error rate / exception rate on the migrated surface within an agreed delta of the legacy baseline over a stated observation window (e.g. 7 days of production traffic, not "looked fine in staging").
- **Performance budget**: a named Core Web Vitals or custom timing metric within budget on real user traffic (field data), not lab-only Lighthouse runs. State the budget number and the percentile (e.g. p75 LCP) before the phase starts, not after.
- **Accessibility parity**: no WCAG 2.2 AA regressions introduced on the migrated surface versus the legacy baseline — verified, not assumed, because visual parity does not imply a11y parity (a modern component can look identical and still break keyboard nav or screen-reader semantics).
- **Functional coverage**: percentage of legacy behavior with an automated test (unit/E2E) proving parity before the legacy path is removed for that surface. "It looks right when I clicked around" is not functional coverage.

A phase gate that only says "ship by end of quarter" with no metric above attached is incomplete — say so explicitly rather than accepting a date-only gate.

### 3. Rollback and forward-progress must not both depend on the same broken assumption

If the rollback path assumes the legacy stack is still fully deployable and the forward path assumes the legacy stack can be safely decommissioned, decide explicitly which is true at each point in time. Common failure: teams decommission legacy build infrastructure or dependencies "since we're mostly migrated" while the rollback plan still assumes that infrastructure exists. State exactly when the legacy stack becomes non-reinstatable, and do not cross that line until the exit criteria for full decommission (below) are met.

### 4. The legacy-decommission step is mandatory and time-boxed

A migration plan that ends at "new code is live in production alongside the old code, indefinitely" is not finished — it has produced a permanent second stack to maintain, patch for security, and onboard new engineers into. Every plan produced by this skill must include an explicit decommission phase with:

- a stated time-box (a date or a trigger condition — e.g. "30 days after the correctness-parity metric holds"),
- the specific artifacts being removed (routes, build config, dependencies, feature flags, dual-stack CI jobs),
- a final rollback-of-last-resort note: once legacy code/dependencies are actually deleted (not just unrouted), rollback is no longer a redeploy — it is a restore from version control and a re-provisioning effort. State this transition point explicitly so nobody assumes rollback stays cheap forever.

### 5. Security/auth coexistence gates are checkpoints, not footnotes

If any phase requires legacy and modern stacks to share auth/session state (see `strangler-boundary-design.md`, route-table seam), that phase's exit criteria must include an explicit security review sign-off as a blocking gate — not a "should be fine" assumption. Do not let a convenience shortcut ("just share the cookie") skip this gate.

## Minimal safe phase-gate template

For each phase, state:

1. **Entry criteria** — what must be true before this phase starts (e.g. prior phase's exit metric held for N days).
2. **Rollback action** — the specific, one-deploy-cycle-or-less action, and who/what triggers it (automatic alert threshold vs. manual call).
3. **Exit metric(s)** — the specific measurable target(s) from the categories above, with number, percentile/window, and data source (field vs. lab, explicitly labeled).
4. **Decommission artifacts** (only for the final phase(s)) — exactly what gets deleted and the time-box/trigger for deletion.

## Adversarial checklist

Before finalizing a phase gate, answer these:

- If this phase fails its exit metric, what is the exact command/flag/route change that reverts it, and has anyone rehearsed it?
- What happens to in-flight user sessions or in-progress transactions at the moment of rollback?
- Is the exit metric based on field data (real user traffic) or only lab data (synthetic runs)? If only lab, say so — it does not prove field parity.
- Does any exit metric assume a sample size / observation window long enough to be statistically meaningful, or is it "looked fine after a day"?
- Who has authority to declare the decommission time-box met, and what happens if the trigger condition never fires (permanent stall)?

If you cannot answer these for a given phase, the phase gate is not ready to ship — say so rather than presenting an incomplete gate as final.

## When to push back

Push back if the user proposes:

- "We'll decide the rollback plan if we need it" — rollback design is not optional and not deferrable to incident time.
- "Let's skip the decommission step, we can clean up later" — "later" is how dual-stack maintenance becomes permanent.
- "The exit criteria is just 'ship it and see'" — that is not a gate, it is an unmonitored rollout.

Those are not pragmatic shortcuts. They are how a bounded migration plan turns into indefinite dual-stack technical debt.

# Strangler Boundary Design

Use this reference only when the user needs the actual technical seam between legacy and modern code — a proxy/route table, a module federation boundary, or an in-page adapter layer — not for a high-level phase summary (that belongs in the main SKILL.md response).

## What people get wrong

The naive story is:

> "We'll put the new framework next to the old one and slowly move pages over."

That undersells the seam design problem. The seam is where almost all migration risk concentrates: shared routing, shared auth/session, shared global CSS/JS, and shared build tooling all leak across the boundary unless it is designed deliberately. A vague "next to" is not a seam; it is an accident waiting to surface in production.

Officially grounded seam patterns (Context7-verified where cited):

## 1. Route-table / reverse-proxy seam (cross-stack, coarse-grained)

The legacy app and the new app live at the same origin (or behind a shared edge proxy), and routing decides which stack serves which path. This is the seam Next.js documents directly: a `rewrites().fallback` config that proxies every unmatched route to the existing legacy site, so you migrate route-by-route while the legacy app keeps serving everything not yet migrated (Context7-verified: `vercel/next.js` docs, `rewrites.mdx`).

Design rules for this seam:
- Decide route ownership explicitly per URL prefix; do not let both stacks claim the same path under different conditions (e.g. query-param-based routing to two different apps at the same path is a maintenance trap).
- Shared navigation chrome (header/footer/nav) rendered by two different stacks will drift visually and behaviorally. Either keep it duplicated with a visual-regression gate on both, or extract it into a served fragment neither app owns independently.
- Session/auth cookies must be readable by both origins/apps identically, or you have silently created a security gate (see SKILL.md — this needs an explicit review, not an assumption that "cookies just work").

## 2. Directory/module coexistence seam (same-framework major upgrades, or App Router migrations)

Some frameworks explicitly support two routing/rendering models coexisting in the same codebase during migration — for example, Next.js `app/` and `pages/` directories running side by side, with official guidance to migrate in small incremental steps rather than all at once (Context7-verified: `vercel/next.js` docs, `app-router-migration.mdx`).

Design rules for this seam:
- Confirm the specific framework version actually supports this coexistence mode before planning around it — do not assume parity across major versions without checking current docs for that version.
- Treat each migrated unit (page, route segment, module) as independently revertible: moving a route from the old model to the new one should be revertible by moving it back, not by reverting a large multi-file commit.
- Watch for cross-cutting concerns that do not respect the module boundary: global CSS resets, shared state stores, and app-wide providers/interceptors often need to be dual-registered or bridged, and that bridging code is itself migration debt that must be tracked and later removed.

## 3. Adapter/wrapper seam (embedding new components inside legacy views, or vice versa)

A common fine-grained seam: mount a modern component (e.g. React) inside a specific DOM node that the legacy stack (e.g. jQuery/Backbone) still controls, via an explicit mount/unmount adapter. This is the right seam when there is no clean route-level boundary — e.g. a single complex widget inside an otherwise-legacy page.

Design rules for this seam:
- The adapter must own an explicit lifecycle contract: who calls mount, who calls unmount, and what happens on the legacy view's re-render (does it destroy and remount the modern component, or does it leave it alone?). An undefined lifecycle contract causes memory leaks or duplicate event listeners — this is the most common actual incident in this pattern.
- Do not share mutable state between the two stacks by direct object reference across the boundary. Pass data in, read data out via an explicit, versioned contract (props in, callback/event out), so either side can evolve independently.
- CSS leakage across the boundary (legacy global styles cascading into the modern component's markup, or vice versa) needs a stated containment strategy (scoped classes, shadow DOM, or a documented "no shared class names" rule) before this seam ships to production, not after a visual bug report.

## 4. Module federation / micro-frontend seam (large-scale, multi-team boundary)

When multiple teams own different areas of the surface, a build-time or runtime module federation boundary lets each area upgrade independently. This is a heavier seam — it introduces shared-dependency version negotiation (React/framework version skew between federated modules) as a first-class operational concern.

Design rules for this seam:
- Explicitly decide and document which shared dependencies (framework, design-system, state library) are singleton-shared vs. independently versioned per module. Undecided version skew is the top failure mode of federation-based strangling.
- Define a contract for cross-module navigation and shared auth/session state before any module ships, not as each new module is added ad hoc.

## Verification targets

- For any Next.js-specific claim above (rewrites/fallback config, app/pages coexistence), re-verify the exact config shape against the installed Next.js version's current docs before writing production config — minor/major versions have changed this surface across releases.
- For any other framework/bundler pairing not covered above, resolve the library via Context7 and query current docs for an "incremental adoption" or "migration guide" page before proposing a specific seam mechanism; do not assume feature parity with the Next.js/React examples above.

## When to push back

Push back if the user asks for:

- a seam with no explicit route/module ownership decision ("we'll figure out which app handles what dynamically")
- shared mutable state passed by direct reference across the legacy/modern boundary "to keep it simple"
- a module federation boundary with no shared-dependency version policy

Those are not simplifications. They are the exact places migrations go from "in progress" to "permanently half-broken."