> ## Documentation Index
> Fetch the complete documentation index at: https://recurr.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pilots and waves

> Why migration runs in waves, what the pilot wave is doing, and how each wave gates the next.

Migration is a multi-touch campaign run on a live subscriber base — emails, web checkouts, billing transitions, support flows. Like any campaign at that scale it carries risks. The Controlled Migration Framework keeps those in check by running the migration in **waves**, with each wave gated on the prior wave's results.

## The shape

A typical engagement runs like this:

<Steps>
  <Step title="Pilot — small, gated waves">
    Each pilot wave runs a small stratified sample — every cohort represented. Pilots run in parallel against a matched store-billing holdout so churn impact is measurable.
  </Step>

  <Step title="Migrate — sequenced cohort waves">
    The program runs as 10 weekly waves, each moving roughly 10% of the addressable base. Every cohort starts in week one at a small allocation, stratified across the eligible base — volume ramps wherever that cohort's benchmarks clear.
  </Step>

  <Step title="Compound — ongoing">
    Web acquisition layered onto the migrated base. New subscribers convert to web before install. The book shifts from store-rail dependence to web-rail compound year over year, with retention safeguards measured continuously.
  </Step>
</Steps>

## Why waves, not bulk

A single bulk migration would be operationally simpler — one email blast, one cutover. It's the wrong move at scale because:

* **Churn impact is unknowable until you've measured.** Bulk migration makes the pilot question ("does this hurt retention?") moot — you've already migrated everyone before you know the answer.
* **Cohort response varies.** Annual subscribers respond differently from monthly. Year-1 cohorts respond differently from long-tenure ones. Bulk treats them all identically.
* **Rollback isn't free.** If a cohort responds poorly to the migration offer, you want to pause + adjust, not unwind a completed cutover.

Waves make all three problems tractable. Each wave is small enough that a bad result is recoverable; the cohort axes are visible enough that you learn which next-wave to ship.

## Wave gating

Every wave has explicit gating criteria agreed before kickoff. The defaults:

* **Migration rate** within ±10 percentage points of pilot baseline
* **Holdout-relative churn delta** within ±2 percentage points
* **Web-side billing health** — failed payments, refund rate, dispute rate within Stripe norms
* **Support volume** — no abnormal spike in tickets tagged to the migration touchpoints

If a wave fails any gate, the next wave **does not ship** until the cause is understood and the cohort spec adjusted.

The point of gating isn't to avoid all risk; it's to make the risk **bounded and observable**. A bad wave is small; a bad bulk migration is permanent.

[Matched store-billing holdouts →](/framework/matched-store-billing-holdouts)