wicked-garden-engineering-large-scale-migration

Large-scale mechanical change — leverage, not grind

A change touching dozens-to-thousands of sites is NOT N problems. It is a small number of repeated PATTERNS. Reaching for "fan out 1000 agents to edit each site", "hand-edit every file", or "sed the repo" is the paper bag. Reduce the work to MAP → TRANSFORM → GATE instead.

The core pattern

1. MAP — the source of truth that already exists or can be deterministically extracted: an inventory of the affected sites, an ownership/registry table, a call graph, a schema. Build it with an AST tool (ts-morph, libcst, jscodeshift, tree-sitter, Roslyn…) or semgrep — never a regex string-grep (quote/escaping/comment blind spots), and never "an agent grepped and thinks it found them all." An exhaustive, reproducible map is the foundation; an approximate one ships a partial migration.
2. TRANSFORM — a deterministic operation over the map: a codemod (AST rewrite), codegen (emit from the map), or regenerate (edit a single source-of-truth + re-run a generator that produces the derived artifacts). NOT per-site LLM editing. The transform should preserve semantics by construction — rewrite the call shape while keeping the literal; move a block intact; change the binding not the logic — so correctness is structural, not hoped-for.
3. GATE — a verifiable equivalence/green check: differential execution (run old vs new on identical seeded inputs, assert identical outputs), the full test suite, or a lint count driven to 0. The change is trusted because it is proven equivalent, not because someone reviewed N diffs.

The bulk goes through the transform. The transform self-flags what it can't handle (the exceptions). Humans/agents touch only the residue — never the bulk.

The TRANSFORM techniques menu (ranked: deterministic → AI)

The TRANSFORM step is not one tool — it is a ranked ladder. Prefer the lowest-numbered technique that fully covers the task. Determinism is cheaper to trust than generation: a recipe or codemod preserves semantics by construction and is re-runnable; an AI wave must be eval-gated every time. Mixing rungs 80/20 across one migration is fine (most go through rung 1–2, the awkward residue through 4–5). Never reach for rung 4/5 for what a rung-1 recipe already does — that trades a proven transform for a hoped-for one. Record which rung you chose per wave, so "should I use AI here?" is a defensible, auditable decision, not an implicit one.