```yaml --- title: Code Migration Playbook subtitle: Using AI to Plan, Execute, and Verify Large-Scale Framework and Language Migrations author: David Kelly Price version: "1.0" date: 2026-04-20 status: draft type: ebook target_audience: Senior engineers and tech leads leading major migrations — framework upgrades, language changes, architectural shifts — in production codebases with real users estimated_pages: 80 chapters: - "1. Why Migrations Fail" - "2. Scoping the Migration with Semantic Search" - "3. Dependency and Impact Mapping" - "4. Designing the Migration Strategy" - "5. Tooling: What to Build vs. Buy" - "6. Incremental Execution Without Big Bang" - "7. Testing During Migration" - "8. Rollback and Recovery Planning" - "9. Stakeholder Communication and Coordination" tags: - pyckle - ebook - migration - refactoring - ai-tools - planning - large-codebases --- ``` --- # Code Migration Playbook ## Using AI to Plan, Execute, and Verify Large-Scale Framework and Language Migrations **By David Kelly Price** Version 1.0 — April 2026 --- ## Table of Contents 1. [Why Migrations Fail](#why-migrations-fail) 2. [Scoping the Migration with Semantic Search](#scoping-the-migration-with-semantic-search) 3. [Dependency and Impact Mapping](#dependency-and-impact-mapping) 4. [Designing the Migration Strategy](#designing-the-migration-strategy) 5. [Tooling: What to Build vs. Buy](#tooling-what-to-build-vs-buy) 6. [Incremental Execution Without Big Bang](#incremental-execution-without-big-bang) 7. [Testing During Migration](#testing-during-migration) 8. [Rollback and Recovery Planning](#rollback-and-recovery-planning) 9. [Stakeholder Communication and Coordination](#stakeholder-communication-and-coordination) --- ## About This Guide Large-scale migrations fail at a predictable rate and for predictable reasons. Not because the engineers involved are inexperienced — usually the opposite is true. They fail because the scoping was wrong, the dependencies were underestimated, or the organization treated a multi-month execution as a project with a defined end date rather than a sustained operational posture. The problem isn't technical difficulty. It's the gap between what the codebase actually contains and what the team believes it contains before work begins. This guide is about closing that gap — systematically, before the first line changes. What follows is a practical framework for planning and executing migrations at production scale. It covers the full arc: how to scope what you're actually dealing with using semantic and graph-based code analysis, how to design a strategy that accounts for the real dependency structure of your system, how to sequence work so you're shipping incrementally rather than betting on a single cutover, and how to build the organizational scaffolding — testing, rollback, communication — that keeps migrations from becoming crises. AI tooling appears throughout, not as a novelty but as infrastructure for the parts of migration work that are genuinely hard to do by hand at scale: discovery, impact analysis, test generation, and progress tracking across a large codebase. The intended reader is a senior engineer or tech lead who has been handed a migration with real stakes — a framework that's end-of-life, a language upgrade with breaking changes, an architectural shift the business is counting on. Someone who can write the code but needs a repeatable process for managing the full scope of what that work actually involves. After reading this, you will have a concrete methodology for scoping migrations accurately, a set of execution patterns that reduce risk without stalling progress, and a clear picture of where AI tools earn their place in the workflow versus where they introduce more noise than signal. --- --- ## Chapter 1: Why Migrations Fail ### Chapter Overview Most migrations don't fail because the technology was wrong or the team wasn't skilled enough. They fail because of decisions made in the first two weeks — often before a single line of code is changed. This chapter examines the structural, organizational, and technical patterns that kill migrations, so you can recognize them in your own codebase before you're six months in and explaining to stakeholders why you need another six. --- ### The Optimism Bias Is Built In Every migration starts with someone who has done the math in their head. They've counted the files, estimated the conversion rate, maybe written a proof-of-concept that took a weekend. It looked clean. It probably was clean — proofs of concept always are, because they don't carry twenty-three monkey-patches written under deadline pressure in 2019. The gap between a working prototype and a working production system is almost never about the happy path. It's about the exceptions: the module that imports from a deprecated internal package that was never documented, the configuration file that behaves differently in staging versus production, the third-party SDK that assumes behavior your new framework doesn't provide. None of these show up in a proof of concept because proofs of concept don't run in your environment — they run in an optimized, sanitized version of it. Optimism bias compounds when the person doing the estimate is also the one who proposed the migration. The proposal needs to be credible, so the estimate gets optimistic. The estimate becomes the plan. The plan becomes the commitment. And then reality shows up. The fix isn't pessimism — it's measurement. Before you estimate anything, instrument the actual codebase. Count the callsites. Identify the integration points. Find the files that import the thing you're replacing. You want data, not intuition, because the codebase has been in production longer than you've been thinking about this migration. --- ### Scope Creep Doesn't Announce Itself It starts innocuously. You're migrating from Express to Fastify, and someone notices the authentication middleware is doing something odd. It's not related to the migration, but it's in the same file, and the PR is already open, so it gets "cleaned up." Then the tests are refactored. Then a utility function that was only loosely connected to the migration gets rewritten because it was "already touched." Three months in, the migration branch contains meaningful changes to forty percent of the codebase, and half of those changes have nothing to do with the original goal. Reviewers can't tell what's migration work and what's opportunistic cleanup. Bugs surface in production and nobody can say with confidence whether the migration caused them. Scope creep is insidious because each individual decision seems reasonable. Of course you should fix the bug while you're in the file. Of course you should update the test coverage. The problem isn't any single decision — it's the cumulative effect on reviewability, testability, and rollback safety. > **Warning:** A migration branch that touches files unrelated to the migration is a branch that can't be safely rolled back. Every unrelated change you add is a change you can't undo independently if something goes wrong. The discipline required here is counterintuitive: you have to be willing to leave known problems in place while the migration is in flight. File them. Fix them later. The migration's job is to migrate, not to improve the codebase generally. Improvement is a separate workstream. --- ### The Strangler Fig Gets Strangled The strangler fig pattern is the canonical approach to incremental migration: run old and new systems in parallel, route traffic gradually to the new system, retire the old system when the new one has proven itself. It's sound in theory. In practice, the seam between old and new becomes a maintenance burden that teams underestimate by an order of magnitude. Consider a concrete example. You're migrating from a monolithic ORM to a service-oriented data layer. The strangler pattern says you run both, routing some queries to the new layer and some to the old. But both layers write to the same database. Consistency becomes your problem. Then the old layer gets a bug fix that also needs to apply to the new layer. Then a feature ships against the old layer because that's where the team has confidence. The "temporary" seam is now load-bearing. ```python # What the strangler seam looks like after six months def get_user(user_id: int) -> User: if feature_flags.use_new_data_layer(user_id): return new_data_layer.fetch_user(user_id) else: # TODO: remove after migration complete (added 8 months ago) return legacy_orm.User.objects.get(pk=user_id) ``` The comment says "TODO: remove after migration complete." The migration is never complete because the seam became load-bearing. This is a failure mode, not a feature. The strangler pattern works when there's a clean interface between old and new. When that interface is porous — when both systems share state, share dependencies, or share responsibility for the same outcomes — the pattern doesn't strangle the old system, it sustains it. --- ### Testing Debt Becomes Migration Debt A codebase with poor test coverage doesn't become easier to migrate — it becomes harder. Tests are the only way to verify that a migrated component behaves identically to its predecessor. Without them, you're relying on manual QA, production monitoring, and optimism. All three fail in different ways. Manual QA doesn't cover edge cases. Production monitoring catches failures after users experience them. And optimism, as covered above, is structurally miscalibrated. > **Key Insight:** Test coverage isn't just a quality metric — it's a migration asset. A component with 90% coverage can be migrated with confidence. A component with 20% coverage requires you to either write tests before migrating (adding time) or migrate blind (adding risk). There's no third option. The teams that handle this well audit test coverage before they plan the migration, not during. They identify the low-coverage components, estimate the test-writing cost, and fold that into the migration schedule. The teams that don't end up writing tests under pressure during the migration, which means the tests get written to pass rather than to verify. There's a subtler issue as well. Existing tests are often coupled to implementation details of the old system. A test that asserts a specific SQL query was executed won't survive a migration to a different data layer. Before migrating a component, it's worth auditing whether its tests are verifying behavior or verifying implementation. Tests that verify behavior survive migrations. Tests that verify implementation don't. --- ### Organizational Debt Kills Timelines Technical migrations have a technical component and an organizational component. The organizational component is usually larger. When a migration spans multiple teams, every decision that requires cross-team coordination is a potential delay. Which team owns the shared library that both sides depend on? Who signs off on the API contract change? What happens when Team A is ready to migrate but Team B has a product deadline and can't afford the instability? These questions don't have clean technical answers. They're organizational problems, and they require organizational solutions: clear ownership, escalation paths, and executive air cover. Migrations that lack any one of these reliably stall. The most common failure mode is a migration that's technically sound but organizationally unsponsored. An individual engineer or a small team drives it on their own initiative. Progress is fast at first, because they're working in their own domain. Then they hit a dependency they don't own, and the work stops while they try to convince another team to prioritize something that benefits everyone but is urgent for no one. If your migration depends on components owned by teams who haven't committed resources to the effort, that's not a risk — it's a certainty. Plan for it or descope it. --- ### The Rollback Plan That Doesn't Work Ask any team mid-migration what their rollback plan is. Most will describe something that sounds reasonable: revert the deployment, flip the feature flag, restore from backup. Then ask them when they last tested it. Rollback plans that aren't tested aren't plans — they're intentions. A rollback procedure that's never been exercised in a production-equivalent environment will fail under pressure, when everyone is watching and time is short. That's not cynicism. That's history. The problem compounds when migrations are done in large batches. A rollback from a deployment that touched three hundred files across twelve services requires every one of those changes to be reversible independently and in combination. That's a coordination problem that can't be solved in the moment. ```bash # A rollback plan that looks fine until you actually need it git revert HEAD~47 # "just revert the migration commits" # Problem: 23 of those commits also included unrelated fixes # Problem: the database schema was migrated forward; the ORM expects the new schema # Problem: three services are already running the new code in production ``` The migration strategy should be designed around rollback from the start, not appended to it at the end. That means feature flags for traffic routing, database migrations that are forward-compatible with both old and new application code, and deployment strategies that allow partial rollback by component rather than all-at-nothing. --- ### Key Takeaways - Proof-of-concept estimates don't account for production complexity. Before committing to a timeline, instrument the actual codebase and count the real scope. - Scope creep is additive and invisible. Every unrelated change added to a migration branch reduces rollback safety and increases review complexity. - The strangler fig pattern requires a clean interface between old and new systems. When that interface is porous or state is shared, the pattern sustains the old system rather than replacing it. - Test coverage is a migration prerequisite, not a migration byproduct. Components without behavioral test coverage must either be tested before migration or migrated at higher risk. - Rollback plans that haven't been tested haven't been validated. The only rollback plan worth having is one that's been exercised in a production-equivalent environment before the migration goes live. --- ### Try This Pull up the codebase you're planning to migrate. Run a quick audit before you do anything else: 1. Find every file that imports the primary thing you're replacing (a framework, a library, a module). Count them. This is your raw scope. 2. For each of those files, check the test file coverage percentage. If your language tooling supports it, run `coverage report` or equivalent and filter to just those files. 3. Flag any file where the coverage is below 60%. Those are your high-risk components. 4. Check git blame on the five largest files in your migration scope. When were they last touched, and by whom? If key files haven't been touched in two years and the author has left the company, that's a signal worth taking seriously before you start moving things. The point isn't to produce a perfect risk matrix. It's to replace intuition with information before the first planning meeting, so the estimates you make are grounded in what's actually there. --- ## Chapter 2: Scoping the Migration with Semantic Search ### Chapter Overview Most migrations go wrong before a single line of code changes — in the scoping phase, when teams underestimate what they're actually touching. The instinct is to search by filename or grep for obvious imports, declare the scope "known," and start planning. That instinct is wrong. Modern codebases accumulate meaning in ways that keyword search cannot surface: implicit conventions, scattered usages, behavioral dependencies that only show up at runtime. Semantic search — treating code as a corpus of meaning rather than a collection of strings — changes what's discoverable before you commit to a plan. This chapter covers how to scope a migration using semantic search techniques, what to look for, and how to turn fuzzy code understanding into a defensible, bounded migration plan. --- ### Why Grep Isn't Enough Grep finds what you already know to look for. That's its job, and it does it well. But migrations fail on the things you didn't know to look for. Consider a framework upgrade where you're moving from one ORM to another. You search for `import OldORM` and find 40 files. That's your scope. Except: three other files use a base class that wraps ORM calls in a way that isn't named anything obvious. Two utility modules build query objects using a pattern the old ORM encouraged that the new one doesn't support. One migration script from 2019 is still being called in a nightly job, and it imports the old ORM directly. None of these show up in your initial grep. You find them when things break. The underlying problem is that code carries semantic weight beyond its syntax. A function named `get_user_context` might be doing database calls, caching, or session management — you can't know from the name. A class named `BaseHandler` might be the single most important thing to touch in your migration, or it might be irrelevant. String matching doesn't tell you. Semantic search addresses this by representing code as meaning — embedding functions, classes, and modules into a vector space where proximity reflects conceptual similarity, not textual overlap. When you search for "database query construction" against a semantically indexed codebase, you get results based on what code *does*, not what it's called. This isn't magic. It's applied retrieval. The same technique that makes document search useful applies here, and the practical result is that you surface the long tail of usages that keyword search misses. --- ### Building a Semantic Index Before You Start Before scoping a migration, index the codebase. This sounds obvious when stated plainly, but most teams skip it — they use IDE search, they grep, they rely on whoever's been on the team longest. That's institutional knowledge masquerading as process, and it has a half-life. A semantic index gives you a queryable representation of the entire codebase that doesn't depend on anyone's memory. Tools like `pyckle-mcp` (or similar code-search infrastructure) chunk your codebase into logical units — functions, classes, modules — embed them, and let you query in natural language. The indexing step itself is worth doing carefully: ```bash # Index the codebase once — chunking happens automatically index_codebase("/path/to/your/project") # Verify coverage index_stats() # → {"chunks": 6847, "files": 412, "last_indexed": "2026-04-20T09:14:22"} ``` Once indexed, you can run migration-scoping queries that would be impossible with grep: ```bash search_code("authentication token validation") search_code("database session management") search_code("request serialization and deserialization") ``` Each query returns ranked results with file paths, line numbers, and relevance scores. The goal isn't to find one canonical answer — it's to build a map of everywhere a concept lives in the codebase. Run 10-15 targeted queries around the core concerns of your migration. Log every result. You're not making decisions yet; you're building a picture. > **Key Insight** > > Semantic search works best for discovery, not confirmation. Use it to find what you didn't know existed. Once you have candidates, read the code manually to confirm what's actually there. The index surfaces candidates; your judgment closes the loop. --- ### Translating Queries into a Scope Document Discovery without structure is just exploration. The goal is to turn semantic search results into a bounded, reviewable scope document that the team can challenge, refine, and commit to. Structure the scope document around *concerns*, not files. A concern is a behavioral or structural area of the codebase: "authentication," "data access layer," "API serialization." For each concern relevant to your migration, list the files, modules, and entry points that surface across your queries. A rough template: ``` Concern: Database Query Construction Files directly involved: - src/db/query_builder.py - src/models/base.py - src/api/filters.py Peripheral files (indirect usage): - src/reports/aggregation.py - legacy/scripts/nightly_sync.py Unknown/needs review: - src/utils/cache.py (references db patterns but unclear scope) ``` The "unknown" category is important. Don't pressure yourself to classify everything immediately. Surface the ambiguity explicitly rather than defaulting to optimism. Unknown files get reviewed before the migration starts, not during. This document becomes the artifact that answers "what are we changing?" It's reviewable in a way that a mental model isn't, and it's updatable as you learn more. Semantic search gives you the first draft; code review and dependency tracing give you the final version. --- ### Handling Legacy Code and Dead Paths Every production codebase of meaningful age has code that runs and code that merely exists. Legacy modules that predate the current architecture. Feature flags set permanently to `False`. Migration scripts that ran once in 2021 and never again. Import chains that look live but terminate in a function nobody calls. Scoping requires distinguishing these. Including dead code in your migration scope wastes time and introduces risk from touching things with no test coverage and no recent memory. Excluding live code because it looked dormant is worse. Semantic search helps here because dead code clusters semantically. Old patterns, deprecated APIs, obsolete abstractions — these tend to share vocabulary. A cluster of results that all reference an old authentication scheme you deprecated two years ago is a signal worth investigating. Combine semantic results with concrete signals: ```bash # Find files not touched in 2+ years git log --since="2024-01-01" --name-only --format="" | sort -u > recent_files.txt grep -vF -f recent_files.txt all_scoped_files.txt > stale_candidates.txt ``` Files that appear in your semantic scope but haven't been touched in two years are candidates for deletion or quarantine, not migration. Verify with call-graph analysis (covered in the next chapter) before removing anything — but surface the question now. > **Warning** > > Don't skip legacy code review on the assumption that it's not running. "It hasn't been touched in years" and "it runs in production" are not mutually exclusive. Scheduled jobs, data pipeline scripts, and batch processors often sit untouched for years precisely *because* they work. Semantic scoping surfaces them; manual review tells you whether they're live. --- ### Calibrating Scope: Too Big vs. Too Small There's a tension in migration scoping between two failure modes. Scope too narrowly and you hit surprises mid-migration when a previously unknown dependency breaks. Scope too broadly and the migration becomes a multi-quarter commitment that loses momentum, accumulates conflicts with parallel feature work, and eventually gets abandoned or rushed. Semantic search helps calibrate this because it gives you a view of the *actual* conceptual footprint of what you're changing, not just the syntactic footprint. A change with a small syntactic scope (ten files importing one module) might have a large conceptual scope if that module implements a pattern used implicitly throughout the codebase. Semantic queries reveal that pattern. Use the following signals to pressure-test your scope: - **Diminishing relevance returns**: Run variations of your core queries. If results start coming back with scores below 0.4, you've likely hit the edge of genuine relevance. Beyond that is noise. - **Cross-cutting concerns**: If semantic search for "X" keeps surfacing files in six different modules, that's a sign the concern is architectural, not local. That changes your migration strategy. - **Cluster size**: A scoped concern that touches 5 files is different from one that touches 50. Neither is automatically wrong, but they require different planning approaches. The output of good scoping is a scope document that a skeptical senior engineer can read and say "yes, I think that's right" or "you're missing X." The goal is confidence through visibility, not false certainty through exclusion. > **Try This** > > Pick the highest-risk concern in your current or upcoming migration and run five semantic queries against your codebase. Write down every file that surfaces. Then search git history for the last time each of those files was modified. Cross-reference the two lists. What's in scope that you didn't expect? What's in scope but effectively dead? Start your scope document from that list. --- ### Key Takeaways - Grep-based scoping finds what you know to look for. Semantic search finds the conceptual footprint of a change — the usages, patterns, and implicit dependencies that string matching misses. - Index the codebase before scoping begins. Running 10-15 targeted queries around migration concerns produces a discovery map that's faster and more complete than manual exploration. - Structure scope around concerns, not files. A concern-oriented scope document is reviewable, challengeable, and updatable — it forces explicit acknowledgment of unknowns rather than optimistic omission. - Legacy and dormant code requires explicit handling. Semantic clustering plus git history can identify stale candidates, but each one needs manual verification before being excluded. - Scope calibration is about confidence, not completeness. The goal is a scope that a knowledgeable peer can review and agree with — not a guarantee that nothing was missed, but a defensible position based on systematic discovery. --- ### Try This Before your next migration planning session, take 30 minutes to run a semantic scoping exercise. Index your codebase if it isn't already. Write down the three biggest behavioral concerns your migration touches — not the files, the *behaviors*. Translate each into two or three natural language queries and run them. Take every result with a relevance score above 0.5 and sort them into: *clearly in scope*, *possibly in scope*, and *unknown*. That three-column list is your starting scope document. Bring it to the planning meeting instead of a file list. The conversation it generates will tell you more about migration risk than any amount of upfront design. --- ## Chapter 3: Dependency and Impact Mapping ### Chapter Overview Once the scope of a migration is established, the next trap waiting for teams is the assumption that they already know what touches what. They don't — not completely, and not in the ways that matter. Dependency and impact mapping is the work of building an accurate model of your codebase's relationships before you start changing things, so that when something breaks during the migration, you understand why, and when something looks safe to change, you've actually checked. This chapter covers the tools and methods for building that model: static analysis, runtime tracing, call graph construction, and the human layer that automated tools consistently miss. --- ### Why Dependency Graphs Lie (and How to Read Them Anyway) Every modern language ecosystem has tools that claim to show you dependency graphs. Webpack bundle analyzers, Python's `pydeps`, Go's `go mod graph`, Java's dependency trees via Maven or Gradle. These are useful, but they answer a narrow question: what does this code import? They don't answer the question you actually need answered during a migration: what behavior depends on this code, and what assumptions does that behavior encode? The gap between those two questions is where migrations go wrong. A module might be imported by twenty files, but only three of those files actually exercise the code path that's changing. Or a critical dependency might not appear in any import graph because it's loaded dynamically — via a plugin system, a registry, a factory, a config file. Import graphs don't capture duck typing. They don't capture string-based lookups. They don't capture the runtime behavior that only manifests under specific load. So use the import graph to orient yourself, not to make decisions. Treat it as the skeleton — you still need the muscle. The practical move is to build two graphs side by side: the static dependency graph from tooling, and a dynamic call graph from runtime traces. Where they differ, pay attention. ```bash # Python: generate a static call graph with pycallgraph2 pip install pycallgraph2 pycallgraph graphviz -- python your_entrypoint.py # Or with Python's built-in profiler for a quick runtime view python -m cProfile -o output.prof your_entrypoint.py snakeviz output.prof # visualize in browser ``` For interpreted languages especially, static analysis is a starting point. It cannot see through `importlib.import_module()`, `getattr()` chaining, or metaprogramming. The runtime trace fills those gaps. --- ### Building the Impact Blast Radius For any module or interface you're migrating, you need to answer one question: if this changes, what else has to change or could break? The answer to that question is the blast radius. Start with direct consumers — files that import the module. Then trace their consumers. You're building a reverse-dependency tree, not a forward one. Most dependency tooling works forward (what does A depend on?). For migrations, you need the reverse (who depends on A?). **Key Insight:** The blast radius of a change is almost always larger than it first appears. Teams routinely underestimate by 30-50% because they trace direct dependencies but miss transitive ones. Count two levels deep at minimum before forming any estimate. In large codebases, doing this manually is impractical. Build a script. ```python import ast import os from collections import defaultdict def build_reverse_dep_map(root_dir: str) -> dict[str, set[str]]: """Map each module to the set of files that import it.""" reverse_deps = defaultdict(set) for dirpath, _, filenames in os.walk(root_dir): for filename in filenames: if not filename.endswith(".py"): continue filepath = os.path.join(dirpath, filename) try: with open(filepath) as f: tree = ast.parse(f.read(), filename=filepath) except SyntaxError: continue for node in ast.walk(tree): if isinstance(node, (ast.Import, ast.ImportFrom)): module = ( node.module if isinstance(node, ast.ImportFrom) else None ) if module: reverse_deps[module].add(filepath) return reverse_deps reverse_map = build_reverse_dep_map("/path/to/project") blast_radius = reverse_map.get("your.target.module", set()) print(f"Direct consumers: {len(blast_radius)}") ``` This gives you the direct layer. For transitive impact, recurse. Most teams stop at two or three levels; beyond that, a change is effectively global, and the migration strategy has to account for that upfront. --- ### Interface Contracts vs. Implementation Details Not all dependencies are equal. When a file imports a module, it might depend on the module's public interface, or it might depend on implementation details that were never meant to be stable. During a migration, these two classes of dependency require completely different handling. Interface dependencies are the ones declared by the API: function signatures, class methods, return types, raised exceptions. These are the things a caller has a right to expect. If the migration changes these, every caller needs to be updated, tested, and released in coordination. Implementation dependencies are the dangerous ones. They're not supposed to exist, but they do, because codebases grow organically and someone always finds a shortcut. A caller that reaches into `module._internal_cache` or monkey-patches `module.config` at import time is coupled to implementation details. Static analysis often won't catch these. Code review history and test suite behavior are better signals. **Warning:** The most dangerous dependencies in any codebase are the ones nobody knows are dependencies. Runtime patching, global state mutation, and test fixtures that reach into private internals create silent coupling that only surfaces under specific conditions — often in production, rarely in CI. Before migrating any module with mutable global state, grep for every reference to that state, not just the module itself. ```bash # Find everything touching a specific internal attribute grep -rn "_internal_cache\|module\.config\b" ./src --include="*.py" ``` Catalog the interface violations you find. They're technical debt that the migration is now inheriting. The call on how to handle them — clean them up as part of the migration or document and defer — is a scope decision, but you need to know they exist before you make it. --- ### Runtime Tracing for Hidden Dependencies Static analysis has a hard ceiling. For anything above that ceiling, you need runtime data. This means running your application — ideally against a production-representative workload — with instrumentation enabled, and then analyzing what actually executed. The goal is to find the code paths that your static graph missed: dynamic imports, conditional feature flags, environment-specific branches, plugins loaded at runtime. These are the dependencies that bite you in production after a migration that looked complete in staging. OpenTelemetry is the standard instrument here for production-grade tracing. For migration-specific analysis, a simpler approach often works: use your existing test suite with coverage measurement, then compare covered code paths to your dependency graph. Any code path in the graph that coverage never exercises is either dead code (good news) or code that only runs under conditions your tests don't replicate (bad news — figure out which). ```bash # Python: run tests with branch coverage and generate a report pip install pytest-cov pytest --cov=your_package --cov-branch --cov-report=html ./tests/ # Open htmlcov/index.html — focus on branches, not just line coverage ``` Branch coverage is more useful than line coverage for migration impact analysis. A line being covered tells you the code ran. A branch being covered tells you the logic path was exercised. For dependency mapping, you care about paths, not lines. --- ### The Human Layer: What Tooling Cannot Find Automated tools will take you 70% of the way. The remaining 30% requires talking to people. Every non-trivial codebase has undocumented dependencies — decisions made three years ago by someone who has since left, workarounds for a bug that was fixed in a library version two upgrades back, integrations with external systems that aren't represented anywhere in the repo. This knowledge lives in heads, not code. The approach is targeted: identify the modules with the highest blast radius scores from your automated analysis, then go find the people who last touched them. Not a broad team survey — that produces noise. A short, specific conversation: "We're migrating X. Before we do, I want to understand if there's anything about how this module works that wouldn't be obvious from reading the code." That question, asked of the right person, surfaces the 30% that would otherwise turn into a production incident. Document what you learn. A simple migration notes file with a section per high-risk module captures tribal knowledge before it's needed. It also creates accountability — if someone says "there's an external system that depends on this response format," you have a record of that constraint, and you can plan around it. --- ### Prioritizing What Actually Matters After the analysis is complete, you'll have a dependency map that's larger than you wanted and more complex than expected. That's normal. The map is not the plan — it's the input to the plan. The prioritization question is: which dependencies, if mishandled, cause the worst outcomes? Not the most dependencies, the most consequential ones. A module with forty consumers that all use a stable interface is less risky than a module with three consumers, one of which is in the payment flow. Score your dependencies on two axes: blast radius (how many things are affected) and consequence severity (how bad is it if something breaks). High blast radius and high severity — those are the dependencies that drive your migration sequencing. Everything else is execution. --- ### Key Takeaways - Static import graphs show structure, not behavior. Runtime traces fill the gap. Use both before making impact estimates. - Blast radius calculation requires going at least two levels deep in the reverse-dependency tree. Direct consumers are only the first layer. - Interface dependencies and implementation dependencies require different handling. Find the implementation dependencies before the migration starts, not during. - Branch coverage over your test suite reveals code paths that automated dependency graphs can't. Uncovered branches in high-impact modules are migration risk. - The tribal knowledge layer — undocumented dependencies, external integrations, workarounds — only surfaces through targeted conversations with the engineers who built the system. Make time for it. --- ### Try This Pick the module in your codebase you're most uncertain about migrating. Run a reverse-dependency scan to count its direct consumers. Then manually trace one level deeper: for each direct consumer, count how many things depend on *it*. Compare the total second-level count to your first-level count. If the second-level count is more than three times the first-level count, you've found a module that behaves like infrastructure — it's a load-bearing piece regardless of how it's categorized. That changes how you sequence it in the migration plan. Now go find the person who last committed to it and ask them one question: "Is there anything about this module that wouldn't be obvious from reading the code?" Write down what they tell you. --- ## Chapter 4: Designing the Migration Strategy ### Chapter Overview With the dependency map in hand, the next task is translating that analysis into a coherent plan of attack. This chapter covers how to structure a migration strategy that accounts for real production constraints — existing users, parallel team workstreams, and the irreducible complexity of systems that don't pause while you work on them. The goal isn't a perfect plan. It's a plan that survives contact with reality and gives the team enough structure to make decisions independently. --- ### Choosing the Right Migration Pattern There are three fundamental approaches to a major migration, and picking the wrong one is one of the most common and costly early mistakes. **Big bang**: you cut over all at once. One deployment, everything new. This is almost always wrong for systems with real users. It concentrates all the risk into a single moment, and when something fails — and something will fail — rollback is expensive or impossible. **Strangler fig**: you build the new system incrementally alongside the old one, routing traffic to the new implementation piece by piece, until the old system has nothing left to serve and you remove it. This is the default choice for most production migrations. It distributes risk across time, lets you validate behavior continuously, and keeps the old system as a fallback at every stage. **Branch by abstraction**: you introduce an abstraction layer over the part of the system being replaced, write both old and new implementations behind that interface, and flip the switch at the abstraction boundary. This works well when the migration target is a component that many callers depend on — a data access layer, a client library, an internal service interface. Most non-trivial migrations end up being some combination of the second and third. Strangler fig at the top level, branch by abstraction internally where the coupling is tight. The pattern choice should follow directly from the dependency map. If the module being migrated has 40 callers, branch by abstraction is almost mandatory. If it's a standalone service with a clean API boundary, strangler fig alone may be sufficient. --- ### Sequencing the Work Sequence is the most underappreciated part of migration design. Teams often sequence by what's easiest or most interesting. The right answer is to sequence by what's safest and most informative. Start at the edges. Leaf nodes in the dependency graph — modules nothing depends on — are the right first targets. You can migrate them, validate them in production, and build confidence in your tooling and process before touching anything load-bearing. Work inward. Once the leaves are done, the modules that depended on them are now edges. Repeat the process. By the time you reach the core of the system, you have a working migration pipeline, a validated test strategy, and real production data about what breaks. > **Key Insight**: The sequence that minimizes risk is often the reverse of the sequence that minimizes effort. Low-risk modules are rarely the ones with the most legacy debt. Migrate in risk order, not effort order. This sequencing principle also applies at a finer granularity. Within a single module, migrate the read paths before the write paths. A broken read returns bad data; a broken write corrupts state. Those are not equivalent failure modes. --- ### Defining What "Done" Means A migration without a clear definition of completion will drift indefinitely. Teams ship the new system, stop routing traffic to the old one, and then spend the next 18 months maintaining both because someone couldn't confirm the old system was fully retired. Define done at three levels: **Feature parity**: the new system handles every case the old one did. This sounds obvious, but "every case" includes the undocumented edge cases you'll only discover by reading old code carefully or by running both systems in parallel and diffing the outputs. **Operational parity**: the new system has equivalent observability, alerting, and runbooks. A migrated service that nobody knows how to debug is not done. **Retirement**: the old code is deleted. Not disabled, not commented out, not flagged off. Deleted. Anything short of deletion leaves the old system as a cognitive burden and an eventual maintenance trap. Put all three levels in the migration plan before work starts. The team should know from day one what the finish line looks like. > **Warning**: "We'll clean it up later" is where migrations go to die. The moment traffic moves to the new system, organizational pressure to maintain the old one drops to zero — but the work to remove it remains. If deletion isn't a first-class milestone with an owner and a deadline, it won't happen. --- ### Managing the Parallel State Problem One of the hardest problems in migration design is the period when two versions of the same system are running simultaneously. Data written by the old system needs to be readable by the new one. Behavior changes in one need to be handled by both. Every week that parallel state exists is a week of additional complexity. The goal is to minimize that window — and to make it explicit rather than accidental. This means making deliberate decisions about data compatibility upfront. If the migration changes a data model, decide whether you're going to: 1. Write a migration that converts existing data before cutover 2. Support both the old and new formats during the transition period 3. Use a compatibility shim that translates on read Option 1 is cleanest but requires downtime or a careful live migration. Option 2 is the most common but requires the new system to carry dead weight during transition. Option 3 is the most complex and usually a mistake unless the data volumes make the others impractical. ```python # Example: compatibility shim on read def load_user_preferences(user_id: str) -> UserPreferences: raw = db.get(f"prefs:{user_id}") if raw is None: return UserPreferences.defaults() # Old format: flat JSON blob # New format: versioned struct with explicit fields if "schema_version" not in raw: return UserPreferences.from_legacy(raw) return UserPreferences.from_dict(raw) ``` The shim approach works fine as a short-term bridge. The risk is treating it as permanent. Shims need expiration dates — a date after which the old format is no longer supported and the compatibility code can be deleted. --- ### Pacing the Migration Without Losing Momentum Long migrations lose momentum. Teams get pulled onto other priorities. Engineers who understood the legacy system leave. The half-migrated state becomes the new normal, and eventually nobody remembers why the migration was started. The antidote is pace control through milestones that deliver observable value, not just internal cleanup. Every milestone should have something a stakeholder outside the team can see: a performance improvement, a reduced failure rate, a deprecated dependency removed, a cost reduction. This isn't about playing politics. It's about creating checkpoints that force honest assessment of whether the migration is still worth the investment. Set a cadence. Weekly migration progress reviews, even if brief, maintain visibility and surface blockers before they compound. Assign an owner for the migration overall — someone whose responsibility it is to track the plan, update sequencing when dependencies shift, and escalate when the team is stuck. > **Try This**: Before the migration starts, write a one-page brief that answers three questions: What does done look like? What's the rollback plan at each stage? Who is accountable for completion? Circulate it to the team leads and ask for pushback. The gaps in the answers are the gaps in the strategy. --- ### Key Takeaways - Migration pattern selection — big bang, strangler fig, or branch by abstraction — should follow directly from the structure of the dependency graph, not from convention or preference. - Sequencing by risk rather than effort concentrates your uncertainty at the start, where you have the most time to recover. - A migration is not complete until the old code is deleted. Retirement must be a named milestone with an owner and a deadline. - The parallel state window — when two versions coexist — should be explicitly designed and bounded, not allowed to drift. - Momentum is a resource. Structure milestones to deliver visible outcomes, not just internal progress, to sustain the investment over time. --- ### Try This Take the dependency map from the previous chapter and apply three labels to every module: **leaf** (nothing depends on it), **intermediate** (depends on others, others depend on it), or **core** (central to multiple critical paths). Now write out the migration sequence in leaf → intermediate → core order. For each module in the sequence, write one sentence answering: "What is the rollback plan if this module's migration fails in production?" If you can't write that sentence, that module isn't ready to migrate. Fix the rollback plan before touching the code. --- ## Chapter 5: Tooling: What to Build vs. Buy ### Chapter Overview Every migration surfaces a tooling question within the first week: do you reach for an existing tool, build something custom, or patch together a hybrid? The wrong answer here doesn't just waste sprint capacity — it can lock a team into maintenance overhead that outlasts the migration itself. This chapter works through the decision framework for migration tooling: how to evaluate what exists, when custom tooling pays off, and how to avoid the common trap of over-engineering infrastructure for a one-time job. --- ### The Cost Nobody Budgets For Custom tooling always looks cheaper than it is. The initial build is straightforward — a few days of focused work, a script that does exactly what you need. The hidden costs come later: edge cases that surface in week three, the engineer who built it leaving for another team, the docs that were never written because everyone "knew how it worked." Before building anything, do an honest inventory of what already exists. The migration tooling ecosystem has matured significantly. Tools like `jscodeshift` for JavaScript AST transformations, `sed`/`awk` pipelines for text-level rewrites, `OpenRewrite` for Java and Kotlin refactoring, and `ast-grep` for multi-language structural search cover a wide range of common patterns. If your migration involves renaming, signature changes, or import restructuring, there's a reasonable chance someone has already built most of it. The question isn't "can we build something better?" You probably can. The question is whether the delta between what exists and what you need is worth the ongoing cost of owning it. > **Key Insight:** Build custom tooling when the transformation logic is specific to your codebase — your naming conventions, your internal abstractions, your domain patterns. Buy (or use open source) when the transformation is generic — syntax changes, API renames, structural refactors that follow published upgrade guides. --- ### When Custom Tooling Is Worth It Some migrations are genuinely unique to your codebase. If you're migrating from an internal framework that no one outside your company has ever used, no off-the-shelf tool will understand your conventions. Same goes for migrating data pipelines that encode business logic in configuration files, or transforming an API layer with patterns that have evolved over a decade of internal decisions. In these cases, custom tooling pays off — but only if you scope it correctly. The failure mode is building a general-purpose migration framework when you needed a specific-purpose script. A Python script that reads files, applies a transformation, and writes output is easier to reason about than a plugin system with hooks and configuration schemas. Here's what a focused custom migration script actually looks like: ```python import ast import sys from pathlib import Path def migrate_logger_calls(source: str) -> str: """Replace logger.warn() with logger.warning() throughout.""" tree = ast.parse(source) transformer = LoggerCallTransformer() new_tree = transformer.visit(tree) return ast.unparse(new_tree) class LoggerCallTransformer(ast.NodeTransformer): def visit_Call(self, node): self.generic_visit(node) if ( isinstance(node.func, ast.Attribute) and node.func.attr == "warn" and isinstance(node.func.value, ast.Name) and node.func.value.id == "logger" ): node.func.attr = "warning" return node if __name__ == "__main__": for path in Path(sys.argv[1]).rglob("*.py"): original = path.read_text() migrated = migrate_logger_calls(original) if migrated != original: path.write_text(migrated) print(f"Migrated: {path}") ``` This is 35 lines. It does one thing, it's auditable, and a new team member can understand it in five minutes. That's the target. Not a framework — a tool. --- ### Tracking Progress Without Drowning in Dashboards Migration state tracking is where teams over-invest in tooling more than anywhere else. There's a natural impulse to build a dashboard: a database tracking which files have been migrated, which are in progress, which have been validated. A web UI. Filtering. Export to CSV. Resist it. For most migrations, a flat file or a simple SQLite database is enough. ```bash # Generate migration status report grep -r "legacy_api" src/ --include="*.py" -l | wc -l # Outputs: 47 # Track completion over time with a simple log echo "$(date -I): $(grep -r 'legacy_api' src/ -l | wc -l) files remaining" >> migration_progress.log ``` This approach — a cron job and a log file — gives you trend data, daily snapshots, and zero infrastructure to maintain. If you need to share progress with stakeholders, pipe that log into a Google Sheet. The goal is signal, not polish. > **Warning:** A migration dashboard that takes two weeks to build is a migration that's already behind schedule. Every hour spent on tracking infrastructure is an hour not spent on the migration itself. Track progress at the granularity that informs decisions — not the granularity that looks impressive in a review meeting. --- ### Static Analysis as a Migration Gate One of the highest-leverage things you can build is a lightweight static analysis check that fails CI when old patterns are detected. This turns migration progress into a ratchet — you can move forward but not backward. The implementation is simpler than it sounds: ```yaml # .github/workflows/migration-check.yml - name: Check for legacy API usage run: | count=$(grep -r "from legacy_module import" src/ --include="*.py" | wc -l) echo "Legacy imports remaining: $count" if [ "$count" -gt "$ALLOWED_LEGACY_COUNT" ]; then echo "Migration regression detected. Expected <= $ALLOWED_LEGACY_COUNT, found $count" exit 1 fi ``` The `ALLOWED_LEGACY_COUNT` env var starts at your current count and decreases as migration progresses. New code can't introduce legacy patterns, and existing patterns must be cleaned up before that count can drop. This is more valuable than any dashboard. It makes migration progress a property of the codebase itself — not a metric someone has to manually update. --- ### Evaluating Third-Party Migration Tools When evaluating an existing tool, there are three things that actually matter: transformation fidelity, handling of edge cases, and what it does when it can't complete a transformation. Transformation fidelity is whether the tool produces semantically equivalent code. Run it against a representative sample of your codebase — not toy examples, but actual production files with real complexity. Compare input and output manually for a dozen files before trusting it on thousands. Edge case handling is the one most teams skip. Feed the tool your weirdest files first. The metaprogramming, the dynamically constructed strings, the files that have been modified by six different engineers over four years. These will break tools that work fine on clean code. Better to discover breakage in evaluation than in a migration commit that touches 400 files. The most important question is what happens when the tool encounters something it can't transform. Does it fail loudly? Leave a comment in the code? Skip silently? Silent skipping is the worst outcome — it creates a false sense of completion and leaves technical debt that's invisible until something breaks in production. > **Try This:** Before committing to any migration tool, run it against your codebase in dry-run or diff mode. Count how many files it touches, how many it skips, and manually inspect 10 random outputs. If the tool doesn't have a dry-run mode, that's already a signal worth noting. --- ### Key Takeaways - Custom tooling is justified when the transformation logic is specific to your internal abstractions — not when you want more control over generic refactors. - Scope custom scripts to do one thing well. Prefer 40 lines that are readable over 400 lines that are configurable. - A CI gate that rejects legacy patterns is more durable than any tracking dashboard — it makes progress self-enforcing. - Evaluate third-party tools against your actual codebase before committing, with special attention to edge cases and failure behavior on untransformable code. - Tracking progress doesn't require infrastructure. A log file and a grep count captures everything you need to make decisions. --- ### Try This Pick one pattern in your codebase that needs to change as part of your migration — an import path, a deprecated method call, an old configuration key. Write a 20-line script that finds all instances and either transforms them automatically or outputs a list of files that need manual attention. Run it against the full codebase. Compare the count it reports against what you expected. If the number surprises you — higher or lower — investigate why before the migration reaches that area. What you learn in that investigation will shape every tooling decision that follows. --- ## Chapter 6: Incremental Execution Without Big Bang ### Chapter Overview Every migration that has ever gone catastrophically wrong had one thing in common: someone, at some point, decided to do it all at once. The big bang approach — freeze the old system, rebuild in the new one, cut over on a fixed date — is intuitively appealing and practically disastrous. This chapter is about the alternative: a disciplined incremental approach that keeps production healthy throughout the migration, lets you course-correct when assumptions fail, and makes the work shippable in pieces rather than a single terrifying release. --- ### Why Big Bang Fails (And Why People Keep Trying It) The appeal is real. One codebase to maintain. No dual-path logic. A clean break from the thing you're replacing. On a whiteboard, it looks efficient. In practice, the time estimates are always wrong. The scope is always larger than modeled. The old system has behavior that nobody documented because nobody thought it needed documenting. The new system has gaps that only reveal themselves under production load, with real users doing things the test suite never imagined. The cruelest part is that big bang migrations don't fail dramatically — they fail slowly. The team works for three months, the codebase diverges from main, and then the integration phase arrives and everything that was "basically done" turns out to be incompatible with the pieces everyone else built in parallel. Two more months. Scope cuts. Morale drops. Eventually it ships or it gets abandoned, but either way, the codebase is worse than when you started. Incremental execution avoids this by keeping the system continuously integrated and continuously deployable throughout the migration. You're not building in a branch — you're shipping in production, piece by piece, every week. --- ### The Strangler Fig Pattern in Practice The strangler fig is the foundational pattern for incremental migration. The name comes from the fig tree that grows around a host tree, eventually replacing it entirely while the host is still standing. In software: you build the new system around the old one, routing traffic to it incrementally, until the old system handles nothing and can be removed. The mechanism is a routing layer — often called a façade or proxy. Requests come in, the router decides whether to send them to the old path or the new one, and the response goes back to the caller. Neither side knows about the other. ```python # Simplified routing façade def handle_request(request): if feature_flag("use_new_auth", user=request.user_id): return new_auth_service.handle(request) return legacy_auth_service.handle(request) ``` This is simpler than it looks in a real system, but the principle holds. The façade gives you three things: gradual traffic shift, per-request observability, and instant rollback. If the new path breaks, you flip the flag. No incident, no rollback ceremony. The critical discipline is that the façade must never contain business logic. It routes. It does not decide. The moment you start encoding rules about what requests get which treatment based on anything other than configuration, you've created a third system that needs its own migration eventually. > **Key Insight:** The strangler fig works because it separates the migration from the cutover. The work of building the new system happens incrementally over months. The cutover itself — flipping traffic from old to new — becomes an operational decision you can make at any time once confidence is high enough. --- ### Seams: Finding Where to Cut The strangler fig tells you the *mechanism* of incremental migration. Seam analysis tells you *where to start*. A seam is a natural boundary in the system where behavior can be swapped without affecting the surrounding code. Not every line of code has clean seams nearby. Legacy systems in particular tend to have logic embedded in places where it has no business being — database queries in view templates, business rules hardcoded in API handlers, validation spread across four different layers. Before you start migrating anything, map the seams. Look for places where the system already has a clear input/output contract: an interface, an API boundary, a well-named function that other code calls without caring about the internals. These are your migration entry points. When seams don't exist, you have to create them first. That is real work, and it needs to be planned as part of the migration timeline — not assumed away. ```python # Before: logic embedded in handler, no seam @app.route("/checkout") def checkout(): cart = db.query("SELECT * FROM carts WHERE user_id = ?", session["user_id"]) total = sum(item["price"] * item["qty"] for item in cart) if total > 500: discount = total * 0.10 # ... 80 more lines ``` ```python # After: seam created, logic extractable @app.route("/checkout") def checkout(): cart = cart_service.get_cart(user_id=session["user_id"]) order = order_service.calculate_order(cart) return render_checkout(order) ``` The second version can be migrated incrementally. The first cannot. Before the migration can start, the refactor has to happen — and that refactor is lower risk than the migration itself because you can verify behavior equivalence before changing any underlying logic. > **Warning:** Seam creation and migration are separate work streams that must be planned separately. Conflating them causes the "we're almost done but blocked on this one thing" problem that stretches every migration timeline. --- ### Branch by Abstraction For situations where the strangler fig doesn't apply cleanly — internal subsystems, shared libraries, database access layers — branch by abstraction is the right pattern. The steps are mechanical: 1. Create an abstraction (interface or abstract class) over the component you're replacing. 2. Make the existing implementation satisfy that abstraction. 3. Build the new implementation behind the same abstraction. 4. Migrate call sites to use the abstraction rather than the concrete type. 5. Switch implementations — gradually, with feature flags if needed. 6. Delete the old implementation. What makes this pattern reliable is that you can stop after any step and ship. Step 1-2 is a safe refactor. Step 3 is new code that nobody calls yet. Step 4 is mechanical and reviewable in small chunks. The actual behavior change only happens at step 5, by which point you have high confidence in the new implementation because it's been running in test and staging environments for weeks. ```python # Step 1-2: Abstraction + existing implementation class SearchBackend(ABC): @abstractmethod def search(self, query: str, limit: int) -> list[Result]: pass class ElasticsearchBackend(SearchBackend): def search(self, query, limit): # existing implementation ... # Step 3: New implementation class VectorSearchBackend(SearchBackend): def search(self, query, limit): # new implementation ... # Step 5: Switch via config backend = VectorSearchBackend() if settings.USE_VECTOR_SEARCH else ElasticsearchBackend() ``` The pattern is not clever. That is the point. Clever migration strategies are the ones that fail in ways you didn't anticipate. --- ### Pacing: How Fast Is Incremental? There's a failure mode on the other side of big bang: the migration that's been "in progress" for two years and nobody knows what percentage is done. Incremental does not mean indefinite. Every migration needs a cadence — a regular rhythm at which units of migration ship to production. Weekly is usually right. Fast enough to maintain momentum, slow enough to observe behavior before moving on. More importantly, every migration needs a metric that defines completion for each unit. Not "the new payment service is built" but "100% of payment requests are routed through the new service with p99 latency under 200ms and error rate under 0.1%." Observable, binary outcomes for each step. The way to stay on pace is ruthless scope management. At the start of each migration unit, define exactly what "done" means and refuse to expand it mid-cycle. Discovered complexity goes into the backlog for the next unit, not into the current one. This is harder than it sounds when you're in the middle of the code and you can see exactly what needs to be fixed next. > **Try This:** Define a migration unit right now. Pick one seam in your system — one service, one module, one API endpoint. Write a two-sentence definition of "done" for migrating that unit, including at least one observable production metric. If you can't write that definition without research, that's the next thing to do. --- ### Managing the In-Between State One unavoidable cost of incremental migration is that the system is in a hybrid state for an extended period. Old and new code run simultaneously. Two implementations of the same behavior exist. Data may live in two places at once. This state is manageable if you design for it explicitly. Two principles matter most. First: the old code must not degrade during the migration. Teams sometimes allow the legacy system to accumulate debt during migration because "it's going away anyway." This is a mistake. If the legacy system breaks, users are impacted. Keep it maintained. Second: the boundary between old and new must be observable. You need metrics that distinguish traffic handled by each path — latency, error rates, throughput. Without this, you're flying blind during the most consequential part of the migration: the traffic shift. Dual writes — writing to both old and new systems during transition — require extra care around consistency. If the old write succeeds and the new write fails, which one is authoritative? Answer this question in your design before you start writing code, not after you encounter the first incident. --- ### Key Takeaways - The strangler fig pattern works because it separates the long migration work from the brief cutover decision — never conflate the two. - Seam creation is distinct from migration work and often must happen first; plan time for it explicitly. - Branch by abstraction gives you a safe, stepwise path for internal components that don't have external routing facades. - Every migration unit needs an observable, binary definition of done that includes a production metric — not just code-complete. - Hybrid state is normal and manageable; the discipline is to keep the legacy system maintained and the boundary between old and new fully instrumented. --- ### Try This Pick one component in your current system that will need to migrate. Map it: What are its inputs and outputs? Does a clean abstraction already exist, or does one need to be created first? Write out steps 1–6 of the branch-by-abstraction pattern applied to that specific component, naming the actual classes or interfaces you'd create. Estimate the time to complete each step independently — not the migration as a whole. If the estimates feel vague, that's a signal that the seam isn't well-understood yet, and understanding it is the first unit of work. --- ## Chapter 7: Testing During Migration ### Chapter Overview Migration testing isn't unit testing with a new coat of paint. The problems are different — you're not just verifying that code does what it's supposed to do, you're verifying that two systems that look different produce equivalent results under real conditions. That's a harder problem, and the standard testing playbook doesn't cover it. This chapter breaks down the specific strategies that work: how to establish behavioral parity between old and new systems, how to run both in production without doubling your incident rate, and how to know — with actual confidence — when the new system is ready to own the load. --- ### The Parity Problem The goal during migration isn't coverage. It's equivalence. Those are related but not the same. Coverage tells you your new code handles its specified cases. Equivalence tells you your new code produces the same outputs as the old code across the full range of inputs that have ever reached it — including the weird ones, the edge cases no one documented, the inputs that exist because a third-party client has been sending malformed data for three years and both sides quietly adapted. That last category is where migrations fail. Not in the happy path. In the accumulated behavioral drift between what the spec says and what the old system actually does. The way to surface that drift is to record production traffic and replay it against both systems. This isn't a new idea, but most teams underinvest in it. A proper shadow replay setup captures real request/response pairs from the old system, replays those requests against the new system, and diffs the responses. Any divergence is a finding — not necessarily a bug, but something that needs a decision. ```python # Minimal shadow replay comparison def compare_responses(old_response, new_response, request_id): diffs = DeepDiff( old_response, new_response, ignore_order=True, exclude_paths=["root['timestamp']", "root['request_id']"] ) if diffs: log_divergence(request_id, diffs) return len(diffs) == 0 ``` The excluded fields matter. Timestamps, trace IDs, nonces — these will always differ and they're not behavioral. The diff logic needs to be smart enough to ignore them or you'll drown in noise. Run shadow replay on a sample of production traffic before you switch anything. Run it again after each migration increment. Treat divergence rate as a metric you track over time, not a one-time check. --- ### Contract Testing Across the Seam At every point where the old and new systems interact — or where the new system takes over a surface the old system owned — there's a contract. That contract is usually implicit. Contract testing makes it explicit. The value isn't in the test itself. It's in the artifact. A written contract for an API or interface becomes the thing both sides can negotiate against when they diverge. Without it, a disagreement between teams becomes a debate about intent. With it, it's a factual question. For internal interfaces, tools like Pact work well. For database schemas, the contract is the schema migration itself, and the tests should verify that the new code handles both the old schema shape (during transition) and the new one. Don't assume that because the migration ran cleanly the application handles both shapes correctly — test that assumption explicitly. > **Key Insight**: Contract tests are most valuable when written before the migration starts, not after. Writing them retroactively surfaces the contract you already have. Writing them prospectively forces a conversation about the contract you want — and that conversation often catches design problems early. The other thing contract testing does is protect you when the dependency direction isn't clean. If the old system calls the new one, or vice versa, at any point during the transition, the contract test defines the handshake. It's the thing you fall back on when something breaks at 2am and you need to know quickly whether the problem is in the caller or the callee. --- ### Running Shadow Mode Without Breaking Production Shadow mode — routing production traffic to both systems but only honoring responses from the old one — is the closest thing to a cheat code in migration testing. It gives you real load, real inputs, and real timing data, with no user impact from failures in the new system. The implementation is less complex than it sounds. At the routing layer, fork the request: send it to both systems asynchronously, return the old system's response immediately, and log the new system's response for comparison. The new system's errors don't matter to the user. They matter to you. ```python async def shadow_route(request): old_task = asyncio.create_task(old_handler(request)) new_task = asyncio.create_task(new_handler(request)) old_response = await old_task try: new_response = await asyncio.wait_for(new_task, timeout=2.0) record_shadow_result(request, old_response, new_response) except Exception as e: record_shadow_error(request, str(e)) return old_response ``` The timeout is important. Shadow requests cannot be allowed to slow down production responses. If the new system is slower — which it often is early in migration — that's information you want, but it can't cost users anything. > **Warning**: Shadow mode creates double the load on your infrastructure. If the old system is already running near capacity, shadow mode will push it over. Either increase capacity before enabling shadow mode, or sample — send 10% or 20% of traffic to the shadow, not all of it. A representative sample is usually enough to catch behavioral divergences. Monitor latency percentiles on the new system separately from the old one during shadow mode. If p99 on the new system is 3x the old, that's a problem to fix before you flip traffic — not after. --- ### Mutation and Characterization Testing Some parts of a legacy system have no tests and no documentation. The behavior is the spec. That's not ideal, but it's common, and pretending otherwise wastes time. Characterization tests capture what the system currently does — not what it should do. The process is mechanical: run the old system against a wide range of inputs, record the outputs, write assertions against those outputs. You're not verifying correctness. You're creating a baseline. ```python # Characterize existing behavior before touching it def characterize_pricing_logic(): test_cases = load_historical_orders() # real data sample results = {} for order in test_cases: results[order.id] = legacy_calculate_price(order) save_characterization_baseline("pricing_v1", results) ``` When the new system is built, run it against the same inputs and compare. Any difference from the baseline is a divergence — again, not necessarily wrong, but requiring a decision. Did the old system have a bug here? Is this new behavior intentional? Who signs off? Characterization tests make these conversations concrete. Without them, the conversation is abstract and slow. With them, you can point at specific inputs and outputs. Mutation testing — where you deliberately introduce bugs into your new code to verify your tests catch them — is useful here too, specifically for the high-risk paths. If your tests don't catch a simple off-by-one in the pricing calculation, your tests aren't protecting you. --- ### Graduated Load Testing and Performance Parity Behavioral parity isn't the only dimension. A new system that produces correct outputs but at twice the latency isn't done. Load testing during migration is different from standard load testing in one key way: the baseline changes as the migration progresses. As traffic shifts from old to new, the load profile on each system changes. A load test run when the new system handles 10% of traffic doesn't tell you how it behaves at 100%. Test at the target load before you get there. Run the new system against projected full traffic in a staging environment that mirrors production infrastructure — not your local machine, not an undersized test cluster. The numbers need to be meaningful. Track these metrics specifically: - P50, P95, P99 latency under target load - Error rate at saturation (what happens when you push past target) - Memory growth over time (leaks that don't show at low volume show here) - Database connection pool behavior under concurrent load > **Try This**: Run a 30-minute sustained load test against the new system at 120% of expected peak traffic. Not to prove it survives — to see where it degrades. Graceful degradation under overload is a feature. Sudden collapse is a reliability incident waiting to happen. Know which one you have before users find out. If the new system degrades differently than the old one — say, the old system throttles cleanly while the new one drops connections — that's a behavior change users will notice. Match the degradation pattern or document why you're changing it. --- ### Key Takeaways - Shadow replay against recorded production traffic surfaces behavioral divergences that no amount of spec-based testing will catch — run it early and continuously, not as a final check. - Contract tests written before migration starts force alignment on interface expectations and give you a fast debugging anchor when things break at the seam. - Shadow mode gives you production-grade validation with zero user impact, but it doubles infrastructure load — sample if necessary, and timeout shadow requests aggressively. - Characterization tests aren't about correctness — they're about capturing what the old system actually does so you can verify the new system matches it, including the undocumented parts. - Performance parity requires testing at target load before you flip traffic. Latency and degradation behavior under load are behavioral properties that matter as much as functional correctness. --- ### Try This Pick one high-traffic endpoint or code path in your current system. Set up a minimal shadow comparison: route 5% of live traffic to the new implementation, capture both responses, and log divergences. Don't fix anything yet. Just run it for 48 hours and look at the divergence report. Categorize each divergence as: (a) expected and intentional, (b) a bug in the new system, or (c) undocumented behavior in the old system that the new system doesn't replicate. The distribution across those three categories will tell you more about your migration risk than any test plan you could write from scratch. --- ## Chapter 8: Rollback and Recovery Planning ### Chapter Overview Every migration plan is, in part, a bet. You're betting the new system works, the migration logic is correct, and nothing unexpected surfaces in production. Sometimes you're right. Sometimes you're not. Rollback and recovery planning isn't pessimism — it's the engineering discipline that lets you take calculated risks instead of reckless ones. The teams that execute migrations cleanly aren't the ones who never need to roll back; they're the ones who've already thought through exactly how they would. --- ### Rollback Is a Feature, Not a Fallback The worst time to design your rollback strategy is after something goes wrong. At that point, you're making decisions under pressure, with partial information, while production is degraded. That's a reliable path to compounding the original problem. Rollback needs to be designed alongside the migration itself. Specifically, every migration step should have a corresponding undo path that's been tested before the migration goes live. Not documented — tested. This means treating rollback as a first-class deliverable. If you're migrating a service from REST to gRPC, the rollback plan isn't "revert the deploy." It's a concrete sequence: which traffic gets rerouted, which clients need reconfiguration, what happens to in-flight requests, and how long that takes. If the answer is "we're not sure," the migration isn't ready. One practical way to enforce this: require a rollback runbook as a merge prerequisite for any migration PR. The runbook doesn't need to be long, but it needs to be specific. Vague rollback plans ("revert if needed") fail at the moment they're needed most. **Key Insight:** The confidence to migrate aggressively comes from knowing exactly how to undo it. Teams that skip rollback planning don't move faster — they move more anxiously, which usually means they move slower. --- ### Database Migrations and the Backward Compatibility Window Database schema changes are the hardest part of rollback planning because they often can't be undone cleanly once data has been written. If you run a migration that drops a column and the new code writes to the schema for 20 minutes before you detect a problem, rolling back the application code doesn't recover what's gone. The standard solution is the expand-contract pattern, executed with explicit backward compatibility windows. **Expand phase:** Add new columns, tables, or indexes without removing anything old. Both old and new application versions can run against this schema simultaneously. **Contract phase:** Once you're confident the new code is stable and no old application version is still running, remove the deprecated structures. ```sql -- Expand: add new column alongside old one ALTER TABLE users ADD COLUMN email_verified_at TIMESTAMPTZ; -- Application writes to both during transition period UPDATE users SET email_verified_at = NOW() WHERE email_verified = true; -- Contract: only after all app versions use new column ALTER TABLE users DROP COLUMN email_verified; ``` The window between expand and contract is your rollback window. Make it explicit. A 48-hour window means both schema versions are live for 48 hours, old application code could be redeployed safely during that period, and the contract migration doesn't run until that window closes. **Warning:** Many teams skip the explicit window and run expand-contract as a single deployment. This eliminates the rollback window entirely. One bad deploy and you're choosing between data loss and staying on broken code. --- ### Feature Flags as Rollback Infrastructure Feature flags are often described as a release tool. They're also the most practical rollback mechanism available for application-level changes. When migration behavior is behind a flag, rollback becomes a configuration change instead of a deploy. That matters because deploy pipelines have latency — sometimes minutes, sometimes longer depending on your infrastructure. A flag flip can take effect in seconds. The pattern works at multiple granularities. At the coarsest level, a single flag controls whether new or old behavior is active for all users. At finer granularity, flags can target specific user cohorts, specific request types, or specific geographic regions. ```python def resolve_user(user_id: str) -> User: if feature_flags.enabled("new_user_resolver", user_id=user_id): return new_resolver.resolve(user_id) return legacy_resolver.resolve(user_id) ``` This pattern lets you migrate incrementally — 1% of traffic, then 10%, then 50% — with the ability to halt or reverse at any percentage. It also gives you real production signal before full cutover, which is genuinely different from what staging environments provide. The discipline required: flags need cleanup timelines. A migration that completed six months ago shouldn't still be behind a flag. Dead flags accumulate, become load-bearing without anyone realizing it, and create exactly the kind of hidden complexity migrations are supposed to remove. --- ### Defining Recovery Time and Recovery Point Objectives RTO (Recovery Time Objective) and RPO (Recovery Point Objective) are usually discussed in the context of disaster recovery. They belong in migration planning too, and making them explicit changes how you design the rollback path. RTO answers: if this migration fails, how long can we tolerate being in a degraded or broken state? For a background data pipeline, maybe four hours is acceptable. For a payment processing service, maybe four minutes. RPO answers: how much data loss is acceptable if we have to restore from a backup? For most transactional systems, the answer is zero, which means rollback strategies that rely on restoring from backup are actually not rollback strategies — they're recovery strategies with data loss baked in. Getting concrete about these numbers forces honest conversations. If your RTO is 10 minutes but your rollback procedure takes 25 minutes to execute (accounting for detection, decision, and execution), you have a gap. Either the RTO needs to change, the rollback procedure needs to get faster, or the migration needs more safeguards. Document these for each migration phase. Not the system-level RTO from your SLA — the migration-specific RTO, which may be tighter during the window when both old and new systems are in play. --- ### Observability as the Early Warning System Rollback decisions are only as good as the signals that trigger them. Teams that catch problems early, when rollback is still clean, share one characteristic: they know exactly what "normal" looks like before they start changing things. Baseline your key metrics before any migration work begins. P50, P95, P99 latency. Error rates by endpoint. Queue depths. Cache hit rates. Downstream service call volumes. Whatever is load-bearing for your system, measure it at rest before you touch anything. During migration, define explicit thresholds that trigger a rollback conversation. Not an automatic rollback — a conversation, because context matters. A 15% latency increase during peak traffic might be a rollback trigger. The same increase at 2am with low traffic might be noise. ```yaml # Example: migration phase alert thresholds alerts: error_rate: baseline: 0.2% warning: 0.5% rollback_trigger: 1.0% p99_latency_ms: baseline: 180 warning: 250 rollback_trigger: 400 ``` Pre-defining these thresholds removes the ambiguity at the worst moment. When something is trending wrong at 11pm, "is this a rollback situation?" should already be answered. The on-call engineer shouldn't be making that call from scratch under pressure. **Try This:** Before your next migration phase goes live, write down three specific metric thresholds that would trigger an immediate rollback. Show them to your team and get agreement. If you can't get agreement in advance, you definitely won't get it during an incident. --- ### Communicating a Rollback Without Losing Credibility Technical leaders avoid rollbacks not just because they're operationally painful, but because they're worried about how it looks. This is worth addressing directly: a clean rollback executed quickly is a success, not a failure. The failure mode is staying on broken code longer than you should because someone is reluctant to admit the migration isn't working. That compounds the problem and erodes trust in a way that a swift, professional rollback doesn't. When a rollback happens, communicate it factually and promptly. What changed, when it changed, what signal triggered the rollback, what the current state is, and what the next step looks like. Skip the apologetic framing. Skip the excessive detail about why things went wrong — that's for the post-mortem, not the incident update. A team that ships a rollback with confidence and then runs a clean post-mortem is a team that stakeholders trust with hard migrations. That reputation is worth protecting. --- ### Key Takeaways - Rollback plans must be tested, not just documented. An untested rollback procedure is speculation about what you'll do under pressure. - The expand-contract pattern for schema migrations only works if the backward compatibility window is explicit and enforced. Collapsing it into a single deploy removes the safety. - Feature flags behind migration behavior reduce rollback time from minutes to seconds. They also provide real production signal before full cutover. - RTO and RPO aren't just disaster recovery concepts — applying them to migration phases surfaces gaps between how fast you need to recover and how fast you actually can. - Pre-agreed rollback thresholds eliminate ambiguity during incidents. The decision criteria should be settled before anything goes wrong. --- ### Try This Pick an active or upcoming migration. Write the rollback runbook before the migration code is merged. Specifically: list every step required to return to the pre-migration state, estimate how long each step takes, identify any steps that are irreversible, and calculate total rollback time. If the total rollback time exceeds your RTO, redesign the migration approach until it doesn't. Share the runbook with the team before the migration goes live and get a second set of eyes on the irreversible steps. --- ## Chapter 9: Stakeholder Communication and Coordination ### Chapter Overview Technical migrations fail for non-technical reasons more often than engineers expect. The code can be solid, the rollback plan airtight, the feature flags perfectly wired — and the project still dies because a VP heard about downtime from a customer before hearing it from you, or because the product team committed to a launch date that nobody told the migration team about. This chapter is about closing that gap: how to communicate migration progress, risk, and status to people who don't read diffs, in ways that actually inform decisions rather than just cover your bases. --- ### Why Migrations Are Communication Problems A migration is, structurally, a period of elevated uncertainty that extends beyond the engineering team. Business decisions get made during that window — roadmap prioritization, customer commitments, hiring plans — and those decisions interact with the migration whether you coordinate on them or not. The mistake most teams make is treating stakeholder communication as a reporting obligation: send an update, check the box, get back to work. That framing misses the function. Communication during a migration is a coordination mechanism. Its job is to synchronize decision-making across people with different information, different risk tolerances, and different time horizons. When that synchronization breaks down, you get misalignment that looks like conflict. The product manager who scheduled a major feature launch mid-migration isn't malicious — they just didn't have the information they needed to make a different call. The executive who escalates a customer complaint about instability to your CTO didn't do it to undermine you — they were surprised and responding to what they knew. Surprises are the enemy. Not bad news. Surprises. --- ### Building the Stakeholder Map Before you send a single status update, spend thirty minutes mapping who actually needs to know what, and when. This is not the same as the org chart. Four categories of stakeholders matter for migrations: **Decision-makers** hold budget, timeline authority, or can change the scope. They need summary-level information: are we on track, what are the live risks, and do they need to make any decisions right now. Over-communicating technical detail to this group creates noise that trains them to ignore you. **Blockers** are people whose work gates yours. Legal review, security sign-off, database admins, platform teams — anyone whose approval or availability is on the critical path. These people need early, specific, time-bounded asks. "We'll need your review around week four" is actionable. A generic heads-up is not. **Impacted teams** have workflows, integrations, or user-facing features that the migration touches. They need enough lead time to prepare and enough specificity to actually do it. The API team needs to know what's changing and when. Customer support needs to know what errors might surface so they're not inventing explanations on the fly. **Observers** are stakeholders who aren't directly affected but have legitimate interest — senior leadership, adjacent business units, major customers. They need periodic, low-noise updates that confirm things are moving as expected. The map changes over the course of a migration. At cutover, observers may temporarily become decision-makers. Revisit the map at each major phase transition. --- ### Designing Updates That Get Read Status updates fail in two ways: too much detail, or not enough. Both produce the same outcome — people stop reading them. The format that works is inverted: lead with status, then risk, then what you need. Engineers write updates in the order they think about the work (here's what we did, here's what we learned, here's where we're going). Stakeholders read in the order they need information (is anything on fire, should I be worried, do I need to do anything). A useful template: ``` Subject: Migration Update — Week 6 of 10 Status: On track. Phase 2 (data layer) complete. Phase 3 (API layer) starts Monday. Active risks: - Redis cluster upgrade scheduled for Wednesday creates a 4-hour dependency window. Mitigation: maintenance window 2–6 AM ET, customer traffic rerouted. Decisions needed from you: None this week. Next update: Friday. ``` That's it. No background. No technical detail that nobody asked for. If someone wants the technical detail, they'll ask, and that conversation is worth having on its own terms. > **Key Insight**: The person who reads your update in fifteen seconds and correctly understands the project's status got a better update than the person who read your four-page report and came away uncertain about whether to be concerned. Brevity earns attention. Attention earns trust. Cadence matters. Weekly updates during active phases, biweekly during stable stretches, daily during cutover. The cadence signals the risk level without you having to say it explicitly. --- ### Handling Escalations Without Losing Control When something goes wrong during a migration, the stakeholder communication problem compounds the technical one. You're dealing with an incident and with the information dynamics that come with it simultaneously. The failure mode is silence followed by over-correction. Engineers go quiet while they're firefighting — understandable, but it creates an information vacuum that fills with speculation. By the time they surface with an update, stakeholders have already heard something from somewhere, often distorted, and have formed opinions. The correct move is a fast, minimal initial communication as soon as you know something is wrong: ``` Time: 2:47 AM ET Status: We've identified an issue with the payment service following the migration deployment at 2:15 AM. Approximately 12% of checkout attempts are failing. We've reverted the migration and expect full recovery in under 30 minutes. We'll send an update at 3:30 AM or sooner if anything changes. ``` Notice what that message does not include: cause, blame, detailed technical context, or promises about prevention. All of that comes later, in the post-mortem. The immediate communication's only job is to confirm that you know, that you're working it, and that you'll follow up. > **Warning**: Stakeholders who discover a production incident through a customer complaint, a social media post, or a colleague in another department before hearing from you will measure the entire migration against that moment. Even if everything else went well, the communication failure becomes the story. First notification has to come from you. After recovery, the post-mortem communication matters as much as the incident response. Write it for a non-technical audience, lead with what customers experienced, explain what failed in plain terms, and be specific about what changes as a result. Vague commitments to "improve our processes" are worse than no commitment at all. --- ### Coordinating Across Teams Without a Single Chain of Command Enterprise migrations that cross team boundaries introduce a coordination problem that technical approaches don't solve. The database team, the platform team, the application teams, and the product teams all have different managers, different OKRs, and different incentives. Nobody is managing the migration as a whole except you. The only durable coordination mechanism in this structure is shared visibility. Everyone needs to see the same status, the same blockers, and the same timeline. Not summaries filtered through managers — the actual state. A shared migration board with clear phase definitions and current status per workstream does most of this work. It doesn't need to be elaborate. A Confluence page with a table updated three times a week will outlast any complex project management setup that nobody updates. > **Try This**: Before your next cross-team coordination meeting, ask each workstream lead to answer three questions in writing: (1) What did we complete since the last meeting? (2) What's blocking us? (3) What do we need from another team in the next two weeks? Read those answers before the meeting, not during it. The meeting becomes a decision session instead of a status session, and it takes half the time. One person needs to own cross-team escalations — not manage all the work, but own the process of surfacing blockers that span teams and getting them resolved. That role is usually the tech lead or engineering manager on the migration. If it's not explicitly assigned, it implicitly belongs to whoever cares most, which is an unstable arrangement. --- ### The Final Communication: Closing the Loop Migrations end, but they often don't close. The team moves on, the monitoring levels drop, and six months later nobody remembers what changed or why. That's a missed opportunity. A formal migration close-out serves two functions. For stakeholders, it signals that the elevated risk period is over and normal operations have resumed — which matters more than it sounds, because some stakeholders will remain in low-grade alert mode until you explicitly tell them it's done. For the organization, it captures what was learned before the team disperses and memory fades. The close-out communication doesn't need to be long. A one-page summary: what we set out to do, what we actually delivered, what it cost in time and resources against estimate, what three things we'd do differently. That document is worth ten times its weight in future migrations, and it gives whoever sponsored the work something to show for it. --- ### Key Takeaways - Stakeholder communication is a coordination mechanism, not a reporting obligation. Its job is to synchronize decisions across people with different information. - Map your stakeholders by role before the migration starts: decision-makers, blockers, impacted teams, and observers each need different information at different cadences. - Lead status updates with status, risk, and action items — in that order. Engineers write in the order they think; stakeholders read in the order they need. - When something breaks, communicate first and explain later. An immediate minimal notification beats a delayed comprehensive one every time. - Close migrations formally. The team needs to move on, stakeholders need to know the elevated-risk period is over, and the organization deserves the institutional knowledge before it evaporates. --- ### Try This Take the most recent significant engineering initiative you've led or participated in and write the stakeholder map from memory: who were the decision-makers, the blockers, the impacted teams, and the observers? Then look at the actual communication that happened during the project. For each category, answer: did they get updates at the right cadence, at the right level of detail, and fast enough when things changed? The gaps in that audit are your personal communication anti-patterns — the places where your instincts about what to communicate don't match what different stakeholders actually needed. Run that audit before your next migration starts, not after. --- ## Conclusion Migrations fail when they're treated as technical problems. They succeed when they're treated as organizational ones with technical execution. That shift in framing — understanding that scope creep, stakeholder drift, and test coverage gaps kill more migrations than bad architecture decisions ever will — is the foundation everything else rests on. By now, you have the tools to scope work with precision, map dependencies before they surprise you, design incremental paths through even the most tangled codebases, and communicate progress in terms that keep leadership aligned instead of anxious. What comes next is execution, and execution is where theory meets friction. The first real migration you run with these methods will surface things no playbook anticipates — a service with undocumented consumers, a test suite that passes in CI and lies about production behavior, a stakeholder who agreed to the timeline and then quietly started planning around it. None of that invalidates the approach. It refines it. Keep the rollback criteria explicit, keep the blast radius small, and keep the migration moving. Momentum is protection. Long pauses invite scope renegotiation. The deeper skill this playbook builds isn't migration-specific. Understanding how to decompose a system, reason about impact, instrument for observability, and coordinate change across people and time — that transfers to every hard technical problem. Migrations are just the context where all those skills get tested simultaneously, under pressure, with real consequences. Do a few of them well, and the muscle memory carries forward to everything else. --- ## Appendix A: Glossary **Big Bang Migration** A migration strategy in which all components are switched over simultaneously in a single deployment event. High risk, no intermediate state, and difficult to roll back. Generally avoided in production systems with real traffic. **Blast Radius** The scope of systems, services, and behaviors that would be affected if a given component fails or changes unexpectedly. Used in impact analysis to prioritize risk during incremental rollouts. **Branch by Abstraction** A technique for making large-scale changes incrementally without long-lived feature branches. An abstraction layer is introduced over the existing implementation, new code is written against that abstraction, and the underlying implementation is swapped when ready. **Canary Deployment** A release pattern in which a new version is deployed to a small subset of production traffic before full rollout. Allows comparison of new and old behavior under real load before committing. **Codemods** Automated scripts that perform syntactic or structural transformations on source code. Used to apply repetitive changes across large codebases consistently and at speed. **Dark Launch** Running new code in parallel with existing code without exposing its output to users. Used to validate behavior against production traffic without user-facing risk. **Dead Code** Code that exists in the codebase but is never executed in any reachable path. Distinct from deprecated code that may still be called. Must be confirmed dead through runtime tracing, not static analysis alone. **Dependency Graph** A directed graph representation of how modules, services, or packages depend on one another. Edges represent import or call relationships. Cycles in the graph indicate tight coupling that complicates migration ordering. **Feature Flag** A configuration mechanism that enables or disables code paths at runtime without deployment. In migrations, used to gate new implementations behind toggles that can be enabled per environment, user segment, or traffic percentage. **Impact Analysis** The process of determining which parts of a system are affected by a proposed change. Involves traversing the dependency graph outward from the change point to identify downstream consumers. **Incremental Migration** A migration strategy that moves components one at a time or in small batches, with each step independently deployable and testable. The opposite of a big bang approach. **Migration Debt** The accumulated complexity and risk introduced by partial migrations that remain in an intermediate state. Similar to technical debt but specifically caused by incomplete transitions between implementations. **Parallel Run** Executing both the old and new implementations against the same inputs and comparing outputs. Used to validate correctness of the new implementation before cutover. **Rollback Criteria** Pre-defined, measurable conditions that trigger reverting to a previous state. Must be specified before migration begins, not during an incident. Examples include error rate thresholds, latency percentiles, and business metric deviations. **Semantic Search** Search that operates on meaning rather than exact string matching. In the context of codebase analysis, uses vector embeddings to retrieve code by conceptual description rather than by function name or file path. **Strangler Fig Pattern** An architectural migration pattern where new functionality gradually replaces old functionality by routing traffic to new implementations piece by piece, until the original system can be retired entirely. **Traffic Shadowing** Duplicating live production requests to a new implementation without using its responses. Used to observe behavior and collect metrics from the new system under real load conditions without user impact. --- ## Appendix B: Tools & Resources ### Semantic Code Search & Analysis **Pyckle / pyckle-mcp** Semantic code search and session context engine. Indexes codebases into vector embeddings and supports natural language queries, dependency graph traversal, and impact analysis. **Sourcegraph** Enterprise code search platform with cross-repository navigation, symbol search, and code intelligence. Useful for large organizations with many services. **ast-grep** Structural code search and rewriting tool using AST patterns. More precise than regex for finding code constructs across large codebases. ### Codemods & Automated Transformation **jscodeshift** Facebook's JavaScript/TypeScript codemod toolkit. Provides an API for writing AST-based transformations that can be applied across entire repositories. **LibCST** Python library for parsing, inspecting, and modifying Python source code while preserving whitespace and formatting. Used for writing Python codemods. **Grit** Multi-language codemod platform with a pattern language for defining and applying structural transformations. Supports JavaScript, TypeScript, Python, Go, and others. **OpenRewrite** Automated refactoring framework for Java and other JVM languages. Has an extensive library of pre-built recipes for framework upgrades and migration patterns. ### Dependency Analysis **Graphviz** Graph visualization software. Useful for rendering dependency graphs generated by analysis tools into readable diagrams. **Dependabot** GitHub's automated dependency update tool. Monitors dependency versions and opens pull requests for updates. Useful for understanding current dependency state before migration. **OWASP Dependency-Check** Identifies known vulnerabilities in project dependencies. Relevant when migration involves dependency consolidation or version upgrades. **Snyk** Dependency vulnerability scanning with fix recommendations. Integrates into CI pipelines. ### Feature Flags & Traffic Management **LaunchDarkly** Feature flag management platform with targeting rules, percentage rollouts, and audit logs. Widely used for production migration traffic control. **Flagsmith** Open-source feature flag platform. Self-hostable alternative to LaunchDarkly. **Unleash** Open-source feature toggle system with a strong SDK ecosystem and self-hosting options. ### Observability & Monitoring **Grafana + Prometheus** Standard open-source stack for metrics collection and visualization. Essential for defining and monitoring rollback criteria during migration. **Datadog** Commercial observability platform with APM, log management, and dashboards. Useful for tracking migration health metrics across services. **OpenTelemetry** Vendor-neutral instrumentation framework for distributed tracing, metrics, and logs. Provides consistent observability instrumentation that survives migrations. **Sentry** Error tracking and performance monitoring. Particularly useful for catching regression errors in new implementations before they affect users broadly. ### Testing **Pytest** Python testing framework. Supports parameterized tests, fixtures, and plugins that support parallel execution and coverage reporting. **Pact** Contract testing framework for consumer-driven contracts between services. Validates that service interfaces remain compatible after changes. **k6** Load testing tool written in Go with a JavaScript scripting interface. Useful for validating performance characteristics of migrated services under simulated traffic. --- ## Appendix C: Further Reading **"Working Effectively with Legacy Code" — Michael Feathers** The definitive guide to modifying code without tests. The seam model and characterization testing concepts are foundational for any migration that starts in an undertested codebase. **"Accelerate: The Science of Lean Software and DevOps" — Forsgren, Humble, Kim** Research-backed analysis of what separates high-performing software organizations. The four key metrics (deployment frequency, lead time, MTTR, change failure rate) are the right framework for measuring migration health. **"Site Reliability Engineering" — Beyer, Jones, Petoff, Murphy (Google)** Google's SRE book covers error budgets, SLOs, and incident management. The error budget model is directly applicable to defining acceptable migration failure thresholds. **"Building Microservices" — Sam Newman** Covers decomposition patterns, service boundaries, and migration strategies for moving toward microservice architectures. The strangler fig chapter is essential reading. **"A Pattern Language for Micro-Frontend Architectures" — Luca Mezzalira** Detailed treatment of incremental frontend migration patterns. Applicable beyond micro-frontends to any frontend architecture migration. **"Continuous Delivery" — Jez Humble, David Farley** Core reference for deployment pipelines, trunk-based development, and feature flagging. The theoretical grounding for why incremental migration is safer than big bang. **"Designing Data-Intensive Applications" — Martin Kleppmann** Deep treatment of data systems, consistency models, and migration challenges specific to databases and data pipelines. Essential for any migration that touches storage layers. **"The Art of Capacity Planning" — John Allspaw** Covers measurement, modeling, and forecasting for production systems. Relevant for predicting load on new implementations during traffic migration phases. **"Large Language Models and Code" — Chen et al. (Codex paper, arXiv 2021)** Original research paper behind GitHub Copilot. Useful background for understanding the capabilities and limitations of LLM-assisted code transformation and generation tools. **"Evolutionary Database Design" — Martin Fowler & Pramod Sadalage (martinfowler.com)** Fowler's treatment of incremental, backward-compatible database schema change. The expand/contract pattern described here is the correct approach for migrating databases without downtime. **"Strangler Fig Application" — Martin Fowler (martinfowler.com)** The original description of the strangler fig pattern. Short, precise, and still the clearest articulation of the core idea. **"How Complex Systems Fail" — Richard I. Cook** A short paper on failure in complex systems that reframes how to think about rollback, incident response, and the nature of system resilience. Read it once a year. --- *Code Migration Playbook — Version 1.0 — April 2026* *By David Kelly Price | pyckle.co* --- *© 2026 Pyckle. All rights reserved. This guide may be shared freely for personal and educational use. Commercial reproduction or redistribution requires written permission. Contact kellyprice@pyckle.co.* --- ## Related Blog Posts - [Why Naive Retrieval Breaks at Scale](https://pyckle.co/blog/why-naive-retrieval-breaks-at-scale-and-what-we-built-instead.html) - [When Everything Is Flat, Everything Gets Lost](https://pyckle.co/blog/when-everything-is-flat-everything-gets-lost.html) - [Your Codebase Has Its Own Language](https://pyckle.co/blog/your-codebase-has-its-own-languageand-your-ai-doesnt-speak-it.html) --- *[Browse all free guides →](https://pyckle.co/books.html)*