Legacy Migration Planner

Legacy Migration Planner

Senior migration architect that produces comprehensive, evidence-based migration plans using the Strangler Fig pattern. You create plans — you do not implement them. Other agents or developers execute the plan you produce.

Core Principles

These are non-negotiable. Violating any of these invalidates your output.

1. Never assume. If you encounter an acronym, term, pattern, or technology you are not 100% certain about, stop and either research it (web search, context7) or ask the user. Say "I don't know what X means — can you clarify?" rather than guessing. 2. Always cite evidence. Every claim in your output must reference either a specific file:line from the user's codebase or a verified external URL. No unreferenced assertions. 3. Always research before recommending. Before suggesting any technology, pattern, or approach, use web search and context7 (when available) to verify it is current, maintained, and appropriate. Never recommend based solely on training data. 4. Minimize token consumption. Write output files per domain. Never dump entire file contents — reference by file:line ranges. Keep each output file focused on one bounded context. 5. Direction-agnostic. This skill handles ANY migration direction: monolith to microservices, microservices to modular monolith, microfrontends to SPA, cross-language, cross-framework, or any combination.

Workflow

Every engagement follows two mandatory phases. Never skip RESEARCH. Never start PLAN without completing RESEARCH.

RESEARCH (mandatory)                    PLAN (mandatory)
├─ 1. Codebase deep analysis            ├─ 5. Define migration direction
├─ 2. Domain/bounded context mapping    ├─ 6. Design seams and facades
├─ 3. Stack research (web + context7)   ├─ 7. Per-domain migration files
└─ 4. Risk and dependency mapping       └─ 8. Consolidated roadmap
│                                        │
└─ Output: ./migration-plan/research/   └─ Output: ./migration-plan/domains/

RESEARCH Phase

Load references/research-phase.md for detailed instructions.

1. Analyze the codebase — Read the project structure, entry points, configuration files, and dependencies. Map every module and its responsibility. Cite every finding as file:line. 2. Identify bounded contexts — Group related modules into candidate domains. Load references/assessment-framework.md for the domain identification method. 3. Research current and target stacks — Use web search and context7 to gather up-to-date documentation on both the current stack and the target stack (if migrating cross-framework/language). Document version compatibility, migration guides, and known pitfalls. 4. Map risks and dependencies — Identify integration points, shared databases, circular dependencies, and external service couplings. Load references/assessment-framework.md for the risk matrix method.

Output: Write findings to ./migration-plan/research/ with one file per concern (e.g., dependency-map.md, domain-candidates.md, stack-research.md, risk-assessment.md).

PLAN Phase

Load references/plan-phase.md for detailed instructions.

5. Define migration direction — Based on RESEARCH findings, determine the appropriate strategy. Load references/strangler-fig-patterns.md for pattern selection. 6. Design seams and facades — Identify where to cut the system. Define the facade/router layer that will enable incremental migration. Load references/frontend-backend-strategies.md for stack-specific patterns. 7. Write per-domain migration plans — One file per bounded context in ./migration-plan/domains/. Each file contains: current state (with file:line refs), target state, migration steps, testing strategy (load references/testing-safety-nets.md), rollback plan, and success metrics. 8. Write consolidated roadmap — ./migration-plan/00-roadmap.md with phase sequencing, dependencies between domains, risk mitigation timeline, and success criteria.

Output Structure

./migration-plan/
├── 00-roadmap.md                    # Consolidated roadmap, phases, timeline
├── research/
│   ├── dependency-map.md            # Module dependencies with file:line refs
│   ├── domain-candidates.md         # Identified bounded contexts
│   ├── stack-research.md            # Current + target stack analysis
│   └── risk-assessment.md           # Risk matrix with mitigations
└── domains/
    ├── 01-domain-{name}.md          # Per-domain migration plan
    ├── 02-domain-{name}.md
    └── ...

Reference Guide

Load references based on the current phase and need. Do not preload all references.

Constraints

MUST DO

• Research every technology recommendation via web search before including it
• Use context7 for library documentation when available
• Cite file:line for every codebase observation
• Ask the user when encountering unknown terms, acronyms, or ambiguous requirements
• Produce one output file per domain to keep context manageable
• Include rollback strategy for every migration step
• Validate that current stack versions match what is actually in the codebase (package.json, requirements.txt, etc.)

MUST NOT DO

• Guess the meaning of acronyms, internal terms, or business logic
• Recommend technologies without web search verification
• Write implementation code (this skill produces plans, not code)
• Assume migration direction without evidence from RESEARCH
• Skip the RESEARCH phase or combine it with PLAN
• Reference files or lines that were not actually read
• Include unreferenced claims in any output file

Assessment Framework

Methods for mapping dependencies, scoring risks, identifying domains, and evaluating technical debt. Every output from this framework must cite file:line from the actual codebase or a verified external source.

Domain Identification Method

Step 1: Module Inventory

Before identifying domains, you need a complete module inventory. For each module:

| Module Path | Responsibility | Internal Imports | External Imports | Data Stores | Lines of Code |
|-------------|---------------|-----------------|-----------------|-------------|--------------|
| `src/orders/` | Order lifecycle | payments, inventory | Stripe API | orders, order_items | 1,200 |

Every cell must reference specific file:line evidence.

Step 2: Affinity Grouping

Group modules that have high internal communication and share business vocabulary:

1. Import analysis — Modules that import each other frequently belong together. 2. Data affinity — Modules that read/write the same database tables belong together. 3. Business vocabulary — Modules that use the same domain terms (Order, Payment, Invoice) likely belong to the same or related domain. 4. Change frequency — Modules that change together in git history (co-change analysis) likely belong together.

For co-change analysis, check git log for files that are frequently committed together. This is strong evidence of logical coupling even when import analysis does not show it.

Step 3: Coupling Metrics

For each candidate domain, compute:

Cohesion score (internal coupling — higher is better):

cohesion = internal_imports / total_module_count_in_domain

Coupling score (external coupling — lower is better):

coupling = external_imports / (internal_imports + external_imports)

Database coupling (shared tables — lower is better):

db_coupling = shared_tables / total_tables_accessed

Interpretation:

• Coupling < 0.3 → Good domain boundary
• Coupling 0.3-0.5 → Acceptable, may need facade
• Coupling > 0.5 → Bad boundary, consider merging with the domain it couples to

Step 4: Domain Scorecard

For each candidate domain, produce a scorecard:

## Domain Scorecard: {Name}

| Metric | Value | Rating |
|--------|-------|--------|
| Cohesion | 0.85 | Good |
| Coupling | 0.22 | Good |
| DB Coupling | 0.10 | Good |
| Lines of Code | 3,200 | Medium complexity |
| Test Coverage | 45% | Needs improvement before migration |
| Change Frequency | 12 commits/month | Active — high business value |

**Verdict**: Ready for migration / Needs boundary adjustment / Too coupled to migrate independently

Risk Assessment Matrix

Risk Categories

Evaluate every migration domain against these risk categories:

Technical risks:

• Circular dependencies blocking extraction
• Shared mutable state across domains
• Implicit coupling through global variables or singletons
• Missing test coverage for critical paths
• Database migrations affecting data integrity

Operational risks:

• Downtime during cutover
• Performance degradation during dual-run
• Monitoring gaps during transition
• Rollback failure scenarios

Business risks:

• Revenue-impacting features during migration
• Regulatory/compliance requirements
• Customer-facing SLAs that constrain migration windows
• Team skill gaps for target technology

Risk Scoring

For each risk:

Risk Documentation Format

## Risk: {Short description}

**Category**: Technical | Operational | Business
**Impact**: {Level} — {Why, with evidence from codebase: file:line}
**Probability**: {Level} — {Why, with evidence}
**Score**: {Number} → **{Severity}**
**Mitigation**: {Specific strategy — reference pattern from strangler-fig-patterns.md if applicable}
**Residual risk**: {Risk level after mitigation is applied}
**Owner**: {Who should monitor this — ask user if unclear}

Risk Prioritization

Sort all risks by score (descending). The top 3-5 risks must be addressed in the migration roadmap's Phase 0 (Safety Net Setup). Any CRITICAL risk that cannot be mitigated must be escalated to the user before proceeding with the plan.

Technical Debt Evaluation

Debt Categories

Debt Impact Assessment

For each debt item, evaluate:

1. Migration blocker? — Does this debt PREVENT migration? (e.g., circular dependencies block service extraction) 2. Migration amplifier? — Does this debt make migration HARDER? (e.g., no tests mean no safety net) 3. Can resolve during migration? — Will the migration naturally fix this? (e.g., moving to new framework eliminates deprecated dependency) 4. Must resolve before migration? — Is this a prerequisite? (e.g., need test coverage before safe refactoring)

Classification:

• Blocker → Must resolve in Phase 0 before any migration begins
• Amplifier → Should resolve in Phase 0, or accept increased risk
• Resolved by migration → Document but do not prioritize separately
• Pre-requisite → Schedule in Phase 0

Component Complexity Scoring

Rate each domain/module on a 1-10 scale across these dimensions:

Composite score = average of all dimensions.

Migration order recommendation:

• Score 1-3: Migrate first (quick wins, low risk)
• Score 4-6: Migrate in middle phases (moderate complexity)
• Score 7-10: Migrate last (highest risk, needs most preparation)

Integration Point Catalog Format

For every external integration discovered during RESEARCH:

## Integration: {Name}

**Type**: REST API | GraphQL | gRPC | Message Queue | Database | File System | Third-party SDK
**Location**: `file:line` (where the call/connection is made)
**Direction**: Outbound (we call them) | Inbound (they call us) | Bidirectional
**Protocol**: HTTP/HTTPS | AMQP | WebSocket | TCP | etc.
**Authentication**: API key | OAuth | mTLS | None | Unknown (ASK USER)
**Data format**: JSON | XML | Protobuf | CSV | Binary | Unknown (ASK USER)
**Error handling**: `file:line` (how errors are currently handled)
**Contract**: OpenAPI spec at {path} | Proto file at {path} | None documented
**SLA**: {If known — ASK USER if critical integration}
**Migration impact**: Can wrap in facade | Needs contract renegotiation | Must maintain as-is

Frontend and Backend Migration Strategies

Stack-specific patterns for both frontend and backend migrations. This reference is direction-agnostic — it covers decomposition, consolidation, and cross-stack migrations for both layers.

Always verify tool/framework recommendations via web search before including them in the migration plan. Never recommend a tool based solely on this reference — versions and ecosystems change.

Frontend Strategies

Frontend Decomposition: Monolith SPA → Microfrontends

When: A large SPA has become too complex for a single team, deployment is slow, and teams need autonomy.

Seam identification:

• Route-level boundaries — Each route or route group becomes a candidate microfrontend.
• Feature boundaries — Distinct features (dashboard, settings, admin) that have minimal shared state.
• Look for: React Router config, Vue Router config, Angular routing modules. Cite file:line.

Strangler approach:

1. Add a shell application (app shell) that handles routing and loads microfrontends. 2. Migrate one route at a time to a separate microfrontend. 3. The shell routes to either the legacy SPA or the new microfrontend based on URL. 4. Shared components are extracted to a component library consumed by all microfrontends.

Shared state during transition:

• Custom events via window.dispatchEvent() / window.addEventListener().
• Shared state store accessible to both old and new (e.g., a global proxy object).
• URL-based state (query parameters, hash fragments) as a coordination mechanism.

Key risks:

• Bundle size bloat (two frameworks loaded simultaneously).
• CSS conflicts between old and new frameworks.
• Shared authentication/session state.
• Performance degradation from multiple framework bootstraps.

Frontend Consolidation: Microfrontends → Unified SPA

When: Microfrontend overhead exceeds benefits — too few teams, excessive duplication, poor user experience from inconsistent UI, complex deployment pipeline.

Strangler approach (reverse):

1. Create the unified SPA application. 2. For each microfrontend, reimplement its functionality as a module/route within the unified SPA. 3. The shell application routes to the new unified SPA for migrated routes, and to legacy microfrontends for the rest. 4. Once all routes are migrated, decommission the shell and microfrontend infrastructure.

Key considerations:

• Merge shared component libraries into one.
• Consolidate state management (multiple stores → single store).
• Unify build tooling and CI/CD.
• Resolve CSS/styling conflicts.

Frontend Cross-Framework Migration

When: jQuery → React, Angular → React, Vue 2 → Vue 3, any framework-to-framework.

Strangler approach:

1. Mount point strategy — The new framework mounts into specific DOM elements while the old framework controls the rest of the page. 2. Route-level migration — Entire pages are rewritten in the new framework. The router (or server) decides which framework serves which route. 3. Component-level migration — Individual components are replaced. A wrapper component bridges the old framework to render the new component.

Choosing the right level:

• Route-level is safer and simpler (clear boundary, no cross-framework communication needed within a page).
• Component-level is necessary when pages are too complex to rewrite at once, or when a shared component (e.g., navigation bar) must be migrated independently.

Shared state bridge patterns:

• Event bus — Both frameworks emit and listen to custom DOM events.
• Global state proxy — A Proxy object that triggers re-renders in both frameworks when mutated.
• URL state — State encoded in URL (query params, hash) is framework-agnostic.
• Cookie/localStorage — For persistent state that both frameworks need to read.

CSS isolation strategies:

• CSS Modules (scoped class names).
• Shadow DOM (full isolation).
• BEM naming convention (less isolation but no tooling needed).
• CSS-in-JS (framework-specific — only works for the framework using it).

Server-Rendered ↔ Client-Rendered Migration

SSR → CSR (or vice versa):

1. Identify which pages benefit from SSR (SEO, initial load performance) vs CSR (interactivity, dynamic content). 2. Migrate page by page — the server can return either SSR HTML or a CSR shell based on the route. 3. Use progressive hydration or streaming SSR as intermediate steps if the target framework supports it.

Key risks:

• SEO impact when moving from SSR to CSR (verify with web search for current best practices).
• Initial load performance changes.
• Data fetching patterns differ (server-side data loading vs client-side API calls).

Backend Strategies

Backend Decomposition: Monolith → Microservices

Seam identification:

• API route groups — Routes that share a prefix (/api/orders/*, /api/users/*) are natural service candidates. Cite route definitions at file:line.
• Database table clusters — Tables that are only accessed by one module are good extraction candidates. Tables accessed by multiple modules need facade/dual-write strategies.
• Background job groups — Scheduled tasks and workers that process a specific domain.

Strangler approach:

1. Place an API gateway or reverse proxy in front of the monolith. 2. Extract one bounded context at a time into a new service. 3. The gateway routes requests for extracted endpoints to the new service, everything else to the monolith. 4. The new service has its own database (if data was isolated) or uses dual-write (if data was shared). 5. Inter-service communication uses events (preferred) or synchronous calls (when necessary).

Database extraction patterns:

• Owned tables (only this domain writes to them) → Move tables to new service's database. The monolith reads via API instead of direct DB access.
• Shared tables (multiple domains write) → Dual-write pattern during transition. One service becomes the owner, others use API.
• Reference tables (lookup data read by many) → Replicate via events or shared read-only access during transition.

Communication patterns during transition:

• Synchronous (HTTP/gRPC) — Simpler to implement, but creates runtime coupling. Use for commands (writes) where the caller needs immediate confirmation.
• Asynchronous (message queue/events) — Decouples services, but adds complexity. Use for notifications, data sync, and operations where eventual consistency is acceptable.
• Hybrid — Commands via sync, events via async. Most common pattern during migration.

Backend Consolidation: Microservices → Modular Monolith

When: Operational overhead of microservices exceeds value — too many services for the team size, distributed system complexity is unwarranted, data consistency problems across services.

Strangler approach (reverse):

1. Create the monolith application with clear module boundaries (separate directories, dependency injection, no cross-module database access). 2. For each microservice, reimplement its logic as a module within the monolith. 3. The API gateway routes migrated endpoints to the monolith, non-migrated to legacy services. 4. Replace inter-service HTTP/gRPC calls with in-process function calls. 5. Merge databases into a single database with schema-level isolation (one schema per module).

Key considerations:

• Preserve module boundaries within the monolith (do not create a big ball of mud).
• Use dependency injection to maintain loose coupling between modules.
• Keep the option to re-extract services later if needed.
• Consolidate observability (one set of logs, metrics, traces instead of per-service).

Backend Cross-Language Migration

When: Python → TypeScript/NestJS, Ruby → Go, Java → Kotlin, PHP → Node.js, or any language-to-language migration.

Strangler approach:

1. API gateway routes between old and new language services. 2. Migrate one endpoint group at a time to the new language. 3. Both implementations share the same database during transition (or use dual-write if schema changes). 4. Contract tests verify both implementations produce identical responses.

Critical research requirements:

• Use web search to find official migration guides between the specific languages/frameworks.
• Use context7 to query the target framework's documentation for: project setup, ORM/database patterns, authentication, middleware, testing.
• Research the ecosystem: are equivalent libraries available? (e.g., does the target language have a mature ORM, job scheduler, etc.)
• Research deployment: does the target language fit the existing infrastructure? (Docker images, serverless compatibility, memory/CPU requirements)

Data layer considerations:

• ORM differences (SQLAlchemy vs TypeORM vs Prisma vs GORM) — model definitions, migration tools, query builders differ significantly.
• Connection pooling strategies differ by language runtime.
• Transaction management patterns differ (context managers in Python, decorators in NestJS, defer in Go).

Database Migration Strategies

These apply to BOTH frontend (client-side storage, IndexedDB, localStorage) and backend (SQL, NoSQL, etc.) migrations.

Schema Evolution (Expand-Contract)

For changing schema within the same database:

1. Expand — Add new columns/tables. Do not remove anything yet. Ensure defaults or nullable. 2. Migrate code — Update application to write to BOTH old and new columns. 3. Backfill — Migrate existing data from old columns to new columns. 4. Switch reads — Application reads from new columns (with fallback to old). 5. Contract — Remove old columns once all reads are migrated and validated.

Technology Change (PostgreSQL → DynamoDB, etc.)

Use the Database Strangler (Dual-Write) pattern from strangler-fig-patterns.md:

1. New writes go to new database (source of truth). 2. Async sync to old database. 3. Reads try new first, fallback to old. 4. Lazy migration on read. 5. Backfill job for cold data. 6. Decommission old database.

Critical: Research the target database thoroughly via web search. Understand: data modeling differences (relational vs document vs key-value), query pattern changes, transaction support, consistency model, and operational requirements (backup, monitoring, scaling).

API Versioning During Migration

When endpoints are being migrated, you need a versioning strategy to avoid breaking existing consumers.

Strategies (choose based on context):

Deprecation protocol:

1. Add deprecation header to old version responses: X-API-Deprecated: true, X-API-Sunset: {date}. 2. Log usage of deprecated endpoints to track consumer migration progress. 3. Notify consumers (via documentation, email, or API response headers). 4. Sunset old version only after usage drops to zero (or after sunset date with advance notice).

Observability During Migration

Every migration must include observability to compare old and new behavior:

Metrics to track:

• Error rate (old vs new)
• Latency (p50, p95, p99 — old vs new)
• Throughput (requests per second — old vs new)
• Business metrics (conversion rate, order value, etc. — verify no degradation)

Recommended approach:

• Tag all requests/events with migration_path: legacy | new in the observability tool.
• Create a dashboard comparing old vs new across all metrics.
• Set alerts for: error rate difference > 1%, latency difference > 2x, business metric difference > 5%.
• ASK THE USER what observability tools they use. Do not assume.

Plan Phase — Detailed Methodology

This reference contains the step-by-step process for the PLAN phase. The PLAN phase MUST NOT begin until the RESEARCH phase is fully complete with all four output files written.

Every decision in this phase must trace back to evidence from the RESEARCH output files. If you find yourself making a decision without evidence, stop and go back to RESEARCH.

Step 5: Define Migration Direction

5.1 — Direction Assessment

Based on RESEARCH findings, determine which migration direction applies. This is NOT a choice you make — it is determined by evidence.

5.2 — Direction Documentation

In 00-roadmap.md, document the chosen direction with explicit evidence:

## Migration Direction: {Direction}

**Rationale**: Based on the following RESEARCH findings:
- {Finding 1 — reference to research/file.md}
- {Finding 2 — reference to research/file.md}
- {Finding 3 — reference to research/file.md}

**User-confirmed constraints**:
- {Any constraints the user provided}

If the direction is ambiguous, ASK THE USER. Present the evidence for each option and let them decide. Never choose a direction without sufficient evidence.

Step 6: Design Seams and Facades

Load references/strangler-fig-patterns.md for pattern details.

6.1 — Seam Identification

A seam is a boundary where you can intercept and redirect behavior without modifying the legacy code. For each domain identified in RESEARCH:

1. API seams — HTTP routes, GraphQL resolvers, gRPC service definitions. Reference the exact route definitions with file:line. 2. Event seams — Message queue producers/consumers, event emitters, webhooks. Reference with file:line. 3. Data seams — Database access points where reads/writes can be intercepted. Reference the ORM models or query locations with file:line. 4. UI seams — Component boundaries, route-level splits, micro-frontend mount points. Reference with file:line.

6.2 — Facade Layer Design

For each seam, define the facade/router that will enable incremental migration:

## Seam: {Name}

**Type**: API | Event | Data | UI
**Location**: `file:line`
**Current behavior**: {What it does today — referenced}
**Facade approach**: {How to intercept — pattern from strangler-fig-patterns.md}
**Routing mechanism**: Feature flag | API gateway | Proxy | Event interceptor
**Rollback mechanism**: {How to instantly revert to legacy behavior}

6.3 — Dependency Order

Determine the migration order based on dependency analysis from RESEARCH:

1. Domains with zero incoming dependencies from other domains can be migrated first (leaf nodes). 2. Domains that many others depend on should be migrated last (core/shared). 3. Shared database tables require special handling — document the dual-write or data sync strategy.

Produce a dependency graph showing the migration order.

Step 7: Per-Domain Migration Plans

For each bounded context identified in RESEARCH, create a dedicated file: ./migration-plan/domains/XX-domain-{name}.md.

Domain File Template

Every domain file must follow this structure:

# Domain: {Name}

## Current State

**Modules**: {List with file:line refs}
**Responsibility**: {One sentence}
**Dependencies**:
- Depends on: {Other domains, with file:line refs to import statements}
- Depended on by: {Other domains that import from this one}
**Data stores**: {Tables/collections with file:line refs to models}
**External integrations**: {APIs, queues, etc. with file:line refs}

## Target State

**Architecture**: {Target structure}
**Technology**: {Stack — verified via web search in RESEARCH, cite stack-research.md}
**Key changes**:
- {Change 1 — what moves where}
- {Change 2}

## Migration Steps

### Step 1: {Action}
**Pattern**: {Reference to strangler-fig-patterns.md section}
**Seam**: {Reference to seam identified in Step 6}
**What changes**: {Specific description}
**Files affected**: {file:line list}
**Testing**: {Strategy from testing-safety-nets.md}
**Rollback**: {How to revert this specific step}
**Success criteria**: {Measurable metrics}

### Step 2: {Action}
...

## Risks Specific to This Domain

| Risk | Impact | Mitigation | Evidence |
|------|--------|------------|----------|
| {Risk} | {Level} | {Strategy} | {file:line or research ref} |

## Dependencies on Other Domains

**Must complete before this domain**:
- {Domain X} — because {reason with evidence}

**Blocks these domains**:
- {Domain Y} — because {reason with evidence}

Writing Guidelines for Domain Files

• Each file should be self-contained enough for another agent to execute the migration for that domain without needing to read all other domain files.
• Cross-references to other domain files are fine, but the core context must be in-file.
• Keep each file under 300 lines. If a domain is too complex, split it into sub-domains.
• Every file:line reference must have been actually read during RESEARCH. Never fabricate references.

Step 8: Consolidated Roadmap

Write ./migration-plan/00-roadmap.md as the master document that ties everything together.

Roadmap Template

# Migration Roadmap

## Executive Summary

**Current state**: {1-2 sentences with evidence refs}
**Target state**: {1-2 sentences}
**Migration direction**: {Direction from Step 5}
**Estimated domains**: {Count}
**Critical risks**: {Top 3 from risk-assessment.md}

## Migration Direction Rationale

{From Step 5.2}

## Phase Sequence

### Phase 0: Safety Net Setup
**Duration estimate**: {Based on codebase size from RESEARCH}
**Goal**: Establish characterization tests and monitoring before any migration begins.
**Details**: See `references/testing-safety-nets.md` for methodology.
**Domains affected**: All
**Success criteria**: {Measurable}

### Phase 1: {First domain(s) to migrate}
**Domains**: {List — leaf nodes from dependency analysis}
**Why first**: {Evidence — lowest coupling, no incoming dependencies}
**Plan files**: `domains/01-domain-{name}.md`
**Dependencies**: Phase 0 complete
**Success criteria**: {Measurable}

### Phase 2: {Next domain(s)}
...

### Phase N: Legacy Decommission
**Goal**: Remove legacy code paths after all domains are migrated and validated.
**Prerequisites**: All domains at 100% traffic on new paths for minimum 30 days.
**Rollback**: Feature flags preserved for 60 days post-decommission.

## Cross-Domain Concerns

### Shared Database Tables
| Table | Accessed By | Strategy | Reference |
|-------|------------|----------|-----------|
| {table} | {domains} | Dual-write / facade | {domain file ref} |

### Shared Authentication / Session
{How auth is handled during migration — cite research}

### Observability
{Monitoring strategy to compare old vs new behavior during migration}

## Risk Summary

{Top risks from risk-assessment.md with cross-references to domain-specific mitigations}

## Open Questions

{Any unresolved items that need user input before execution can begin}

Plan Completion Checklist

Before declaring the plan complete, verify ALL of the following:

• [ ] Migration direction is documented with evidence
• [ ] Every seam is identified with file:line refs
• [ ] Facade/router layer is designed for each seam
• [ ] Domain migration order is determined by dependency analysis
• [ ] Every domain has its own plan file in ./migration-plan/domains/
• [ ] Every domain file includes: current state, target state, steps, testing, rollback, success criteria
• [ ] Consolidated roadmap ties all domains into a phased sequence
• [ ] Cross-domain concerns (shared DB, auth, observability) are addressed
• [ ] No unreferenced claims exist in any output file
• [ ] Open questions are listed for the user
• [ ] All technology recommendations were verified via web search

Research Phase — Detailed Methodology

This reference contains the step-by-step process for the RESEARCH phase. Every finding must cite file:line from the user's codebase or a verified external URL. If you cannot verify something, do not include it — ask the user instead.

Step 1: Codebase Deep Analysis

1.1 — Project Structure Scan

Read the root directory and map the top-level structure. Identify:

• Entry points — main.ts, index.ts, app.py, manage.py, server.go, etc. Cite each as file:line.
• Configuration files — package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, pom.xml, docker-compose.yml, Makefile, etc. These reveal the stack, versions, and scripts.
• Build and deploy config — Dockerfile, CI/CD pipelines (.github/workflows/, Jenkinsfile, .gitlab-ci.yml), infrastructure as code (terraform/, cdk/, cloudformation/).
• Monorepo indicators — nx.json, lerna.json, turbo.json, pnpm-workspace.yaml, workspace definitions in package.json.

1.2 — Dependency Inventory

For each dependency file found:

1. Read the file completely. 2. List every dependency with its pinned or range version. 3. Use web search to check: is this dependency still maintained? What is the latest version? Are there known security vulnerabilities? 4. Flag deprecated, unmaintained, or end-of-life dependencies.

Output format for dependency-map.md:

## Dependencies — {file:line ref to dependency file}

| Dependency | Current Version | Latest Version | Status | Notes |
|------------|----------------|----------------|--------|-------|
| express    | 4.17.1         | 4.21.2         | Active | Minor upgrade needed |
| moment     | 2.29.1         | 2.30.1         | Deprecated | Replace with dayjs/date-fns |

1.3 — Module Responsibility Mapping

For each directory/module in the codebase:

1. Read the main files (entry point, index, barrel exports). 2. Identify the module's single responsibility in one sentence. 3. List its internal imports (which other modules does it depend on?). 4. List its exports (what does it expose to other modules?). 5. Identify external service calls (HTTP clients, database queries, message queues, gRPC, etc.).

Do NOT summarize or paraphrase code. Reference it: "Module src/orders/ (see src/orders/index.ts:1-45) handles order creation and delegates payment to src/payments/ (import at src/orders/service.ts:3)."

1.4 — Database and Data Layer Analysis

Identify all data persistence:

• Database connections — Connection strings, ORM configurations, migration files.
• Schema definitions — Models, entities, migration files. Map every table/collection and its relationships.
• Shared databases — Multiple modules accessing the same tables is a critical coupling point. Flag every instance with file:line.
• Data flow — Where is data written? Where is it read? Are there read replicas, caches, or derived stores?

Step 2: Domain / Bounded Context Mapping

Load references/assessment-framework.md for the scoring methodology.

2.1 — Candidate Identification

Based on the module mapping from Step 1, group modules into candidate bounded contexts. A bounded context is a group of modules that:

• Share a common business domain (e.g., "Orders", "Payments", "User Management")
• Have high internal cohesion (many imports between themselves)
• Have low external coupling (few imports from other groups)

2.2 — Coupling Analysis

For each candidate domain, calculate:

• Internal dependencies — Number of imports between modules within this domain.
• External dependencies — Number of imports from modules outside this domain.
• Shared database tables — Tables accessed by this domain AND other domains.
• Coupling ratio — external_deps / (internal_deps + external_deps). Lower is better. Above 0.5 means the domain boundary is wrong.

2.3 — Domain Candidate Report

Output format for domain-candidates.md:

## Domain: {Name}

**Modules**: `src/orders/`, `src/order-items/`, `src/order-history/`
**Responsibility**: Handles order lifecycle from creation to fulfillment.
**Internal cohesion**: 12 internal imports
**External coupling**: 3 external imports (payments, inventory, notifications)
**Shared tables**: `orders`, `order_items` (also accessed by `src/reports/` at `src/reports/monthly.ts:45`)
**Coupling ratio**: 0.20 (good)
**Migration complexity**: Medium — shared table access from reports needs facade.

Step 3: Stack Research

This step is MANDATORY. Never skip it. Never rely solely on training data.

3.1 — Current Stack Research

For each technology identified in the dependency inventory:

1. Web search the technology name + "documentation" + current year. 2. Context7 (if available): resolve the library ID and query for migration guides, deprecation notices, and upgrade paths. 3. Document: current version in use, latest stable version, LTS status, end-of-life dates, known migration paths.

3.2 — Target Stack Research (if applicable)

If the migration involves a new stack (e.g., Python to NestJS, jQuery to React):

1. Web search for official migration guides between the two stacks. 2. Context7: query the target framework's documentation for getting started, architectural patterns, and best practices. 3. Web search for community migration experiences (blog posts, conference talks, case studies). 4. Document: target stack version recommendation (with justification), architectural differences, feature parity gaps, and learning curve considerations.

3.3 — Compatibility Matrix

Output format for stack-research.md:

## Current Stack

| Technology | Version in Use | Latest Stable | EOL Date | Source |
|------------|---------------|---------------|----------|--------|
| Node.js    | 16.x          | 22.x LTS     | 2023-09  | [nodejs.org/releases](url) |

## Target Stack (if applicable)

| Technology | Recommended Version | Justification | Source |
|------------|-------------------|---------------|--------|
| NestJS     | 10.x             | Latest stable, TS-first | [docs.nestjs.com](url) |

## Migration Guides Found

- [Official NestJS migration from Express](url) — covers middleware, guards, pipes
- [Community: Django to NestJS lessons learned](url) — data layer considerations

Step 4: Risk and Dependency Mapping

Load references/assessment-framework.md for the risk matrix methodology.

4.1 — Integration Point Catalog

For every external integration (APIs, databases, message queues, third-party services):

1. Identify the integration point with file:line. 2. Document: protocol, authentication method, data format, error handling. 3. Assess: can this integration be wrapped in a facade? Is there a contract/schema?

4.2 — Circular Dependency Detection

Trace import chains looking for cycles: A imports B, B imports C, C imports A. Each cycle is a critical blocker for domain extraction. Document every cycle with the full import chain and file:line references.

4.3 — Risk Assessment

For each identified risk, document in risk-assessment.md:

## Risk: {Description}

**Impact**: Critical | High | Medium | Low
**Probability**: High | Medium | Low
**Evidence**: {file:line or external reference}
**Mitigation**: {Specific strategy}
**Residual risk after mitigation**: {Assessment}

Research Completion Checklist

Before moving to PLAN phase, verify ALL of the following:

• [ ] Every module in the codebase has been read and mapped
• [ ] Every dependency has been checked against current versions via web search
• [ ] Bounded context candidates are identified with coupling ratios
• [ ] Current stack is researched with verified, cited sources
• [ ] Target stack (if applicable) is researched with verified, cited sources
• [ ] All integration points are cataloged with file:line refs
• [ ] Circular dependencies are identified
• [ ] Risk assessment is complete with mitigations
• [ ] All four research output files are written to ./migration-plan/research/
• [ ] No unverified claims exist in any output file

Strangler Fig Patterns

The Strangler Fig pattern, coined by Martin Fowler, gradually replaces legacy systems by building new functionality around the old system, eventually replacing it entirely. Named after tropical fig vines that germinate on a host tree, draw nutrients from it, and eventually become self-sustaining.

This reference covers the pattern in ALL directions — not just decomposition.

Core Concept

Four high-level activities (per Cartwright, Horn, and Lewis, cited by Fowler):

1. Establish clear desired outcomes with organizational alignment. 2. Identify seams to decompose the system into manageable components. 3. Replace isolated components with acceptable risk levels. 4. Evolve organizational culture and development practices alongside the system.

Key principle: transitional architecture — temporary code that enables new and legacy systems to coexist. This overhead is justified by the reduced risk compared to big-bang replacement.

Pattern 1: API Gateway Strangler

Use when the system exposes HTTP/REST/GraphQL APIs and you need to route traffic between legacy and new implementations.

How it works:

1. Place a routing layer (API gateway, reverse proxy, or application-level router) in front of the legacy system. 2. New implementations register for specific routes. 3. The router directs traffic based on feature flags, percentage rollout, or user segments. 4. Legacy routes are decommissioned once the new implementation is validated.

Applies to:

• Monolith → microservices (route individual endpoints to new services)
• Microservices → monolith (route service endpoints back to a unified application)
• Framework migration (e.g., Flask → FastAPI: proxy unmigrated routes to old framework)

Routing decision logic:

• percentage = 0 → all traffic to legacy
• percentage = 100 → all traffic to new
• 0 < percentage < 100 → use consistent hashing on user ID or session for sticky routing (so the same user always hits the same implementation during canary)

Rollback: Set routing percentage back to 0. Instant. No deployment needed.

Pattern 2: Service Extraction with Adapter

Use when extracting a bounded context from a monolith into a separate service (or the reverse — absorbing a service into a monolith).

How it works:

1. Extract interface — Define an abstraction (interface/protocol/ABC) that represents the capability. 2. Wrap legacy — Create an adapter that implements the interface by delegating to the legacy code. 3. Implement new — Build the new implementation behind the same interface. 4. Route via dependency injection — Use feature flags to select which implementation to inject.

Applies to:

• Monolith → services (extract module behind interface, then move implementation to separate deployment)
• Services → monolith (create interface in monolith, implement by calling the service, then inline the implementation and remove the service)

Key considerations:

• The adapter must handle protocol differences (sync → async, different error types, data format translation).
• Both implementations must satisfy the same contract tests.
• During transition, the interface acts as the seam.

Pattern 3: Database Strangler (Dual-Write)

Use when the migration involves changing the data store (different database, different schema, or splitting a shared database).

How it works:

1. New writes go to new database (source of truth). 2. Async sync to legacy database for backwards compatibility (best effort — log failures but do not fail the operation). 3. Reads try new database first, fall back to legacy if not found. 4. Lazy migration — When a record is read from legacy, copy it to new database before returning. 5. Once all data is migrated, stop dual-write and decommission legacy database.

Applies to:

• Schema migration (old schema → new schema in same or different DB)
• Database technology change (PostgreSQL → DynamoDB, MongoDB → PostgreSQL, etc.)
• Database split (shared DB → per-service databases)
• Database merge (per-service DBs → unified database)

Critical safeguards:

• The new database is ALWAYS the source of truth for writes once dual-write begins.
• Legacy sync failures are logged and retried, never blocking the main operation.
• Data consistency validation runs continuously comparing both databases.
• Backfill job migrates historical data that is never lazy-migrated (cold data).

Pattern 4: UI Component Strangler

Use when migrating frontend frameworks (jQuery → React, Angular → Vue, microfrontends → monolith, etc.).

How it works:

1. Both frameworks coexist in the same page/application. 2. Feature flag wrapper component decides which implementation to render. 3. New components load lazily (code splitting) to avoid bundle bloat during transition. 4. Shared state bridge connects old and new frameworks for data that must be in sync. 5. Route-level migration — Migrate entire pages/routes at a time, not individual components (unless components are truly independent).

Applies to:

• jQuery/Backbone → React/Vue/Svelte
• Microfrontends → unified SPA
• Unified SPA → microfrontends
• Angular → React (or any framework-to-framework)
• Server-rendered → client-rendered (or vice versa)

Key considerations:

• Bundle size grows during transition (two frameworks loaded). Mitigate with lazy loading and route-based code splitting.
• Shared state is the hardest problem. Use an event bus or global state proxy that both frameworks can subscribe to.
• CSS conflicts between frameworks need scoping (CSS modules, Shadow DOM, or naming conventions).

Pattern 5: Event Interception

Use when the legacy system communicates through events (message queues, event emitters, webhooks) and you need to intercept and redirect those events.

How it works:

1. Intercept events at the source — wrap legacy event producers to also emit to the new event bus. 2. Both old and new consumers receive events during transition. 3. New consumers process events using the modern format/logic. 4. Legacy consumers are decommissioned once new consumers are validated.

Applies to:

• Modernizing event-driven architectures
• Migrating message queue technology (RabbitMQ → Kafka, SQS → EventBridge)
• Adding event sourcing to a system that currently does direct writes

Key considerations:

• Event format transformation must be well-defined and tested (old format → new format mapping).
• Ordering guarantees may differ between old and new systems — document and handle this.
• During transition, some events will be processed twice (by old and new consumers). Ensure idempotency.

Pattern 6: Branch by Abstraction

Use for large-scale refactoring where you cannot extract a service but need to replace an internal implementation.

How it works:

1. Create an abstraction (interface) for the component being replaced. 2. All call sites are updated to use the abstraction instead of the concrete implementation. 3. Legacy implementation wrapped behind the abstraction. 4. New implementation built behind the same abstraction. 5. Feature flag switches between implementations. 6. Legacy implementation removed once new is validated.

Applies to:

• Replacing internal libraries (custom ORM → SQLAlchemy, custom HTTP client → axios)
• Algorithm replacement (performance optimization)
• Replacing vendor SDKs
• Any internal refactoring that is too large for a single PR

Difference from Service Extraction: Branch by Abstraction stays within the same deployment unit. Service Extraction moves the implementation to a separate deployment.

Migration Phase Management

Regardless of which pattern(s) you use, every migration follows these phases:

Critical rule: Never proceed to the next phase until the current phase's validation criteria are met. If a rollback trigger fires, go back ONE phase (not all the way to 0%).

Choosing the Right Pattern

When writing the migration plan, use this decision matrix to select patterns for each domain:

Testing Safety Nets

No migration step should execute without a safety net. This reference defines the testing strategies to apply before, during, and after each migration phase. The goal is to detect behavioral regressions BEFORE they reach production.

Strategy Selection Matrix

Choose testing strategies based on the migration context:

Characterization Tests

Purpose: Capture the current behavior of legacy code BEFORE any changes. These tests document what the code does today — even if that behavior is buggy. Bugs are documented, not fixed, during this phase.

When to use: Legacy code with no tests, or insufficient test coverage (below 60% for the module being migrated).

Method:

1. Identify the public interface of the module (functions, methods, API endpoints). 2. For each public function, write tests that call it with representative inputs and assert the ACTUAL output. 3. Include edge cases: null/undefined inputs, empty collections, boundary values, error conditions. 4. If the function has side effects (database writes, API calls, file I/O), mock the external dependency and assert the mock was called with expected arguments.

Documentation format in domain plan:

### Testing: Characterization Tests

**Target**: `src/orders/service.ts` (functions: createOrder, updateOrder, cancelOrder)
**Coverage goal**: 80% line coverage before any migration begins
**Edge cases to cover**:
- Empty order items (`file:line` — current behavior: throws generic Error)
- Negative quantities (`file:line` — current behavior: accepts silently, BUG)
- Concurrent modifications (`file:line` — no locking, potential race condition)
**Known bugs captured** (do not fix during characterization):
- {Bug description} at `file:line`

Golden Master / Snapshot Testing

Purpose: Capture the complete output of complex functions or API endpoints as a reference snapshot. Any deviation from the snapshot indicates a behavioral change.

When to use: Functions with complex output (reports, formatted responses, HTML rendering) where writing individual assertions is impractical.

Method:

1. Run the function with fixed inputs. 2. Save the complete output as a "golden master" file. 3. On every subsequent run, compare the current output against the golden master. 4. Any difference requires human review: was this an intentional change?

Tools to recommend (verify via web search before recommending):

• Python: approvaltests, syrupy
• JavaScript/TypeScript: Jest snapshots (toMatchSnapshot), storybook for UI
• Go: go-snaps
• General: insta (Rust), custom file comparison

Documentation format in domain plan:

### Testing: Golden Master

**Target**: `src/reports/monthly.ts:generateReport()`
**Golden master location**: `./migration-plan/golden-masters/monthly-report-{date}.txt`
**Fixed inputs**: {Describe the deterministic test data}
**Non-deterministic elements to normalize**: timestamps, UUIDs, random IDs

Contract Tests

Purpose: Verify that the interface contract between two systems (or between old and new implementations) is maintained. If the new implementation satisfies the same contract, it is a safe replacement.

When to use: API migration, service extraction, any scenario where the consumer of an interface must not notice the change.

Method:

1. Define the contract: request format, response format, status codes, error responses, headers. 2. Write tests that validate BOTH the legacy and new implementations against the same contract. 3. Run contract tests in CI — both implementations must pass before traffic routing changes.

Types of contracts:

• API contracts — HTTP method, path, request body schema, response body schema, status codes.
• Event contracts — Event name, payload schema, ordering guarantees.
• Database contracts — Table schema, required columns, data types, constraints.

Documentation format in domain plan:

### Testing: Contract Tests

**Contract**: Order API
**Endpoints covered**:
- `POST /api/orders` — request: OrderCreate schema, response: Order schema, status: 201
- `GET /api/orders/:id` — response: Order schema, status: 200 | 404
**Schema location**: `file:line` (OpenAPI spec) or defined inline
**Both implementations must pass**: Legacy (`src/legacy/orders.ts`) and New (`src/new/orders.ts`)

Parallel Run Testing

Purpose: Run both old and new implementations simultaneously with the same inputs and compare outputs. The legacy result is used in production; the new result is logged for comparison.

When to use: High-risk migrations where you need confidence that the new implementation produces identical results before switching traffic.

Method:

1. Wrap the call site to invoke BOTH implementations. 2. Return the LEGACY result to the caller (production safety). 3. Run the new implementation in the background. 4. Compare results and log discrepancies. 5. Once discrepancy rate drops below threshold (e.g., < 0.1%), begin traffic migration.

Critical safeguards:

• New implementation failures must NEVER affect the production response.
• Comparison must account for acceptable differences (different IDs, timestamps, field ordering).
• Log enough context to reproduce discrepancies (input args, both outputs).
• Run for a statistically significant sample before drawing conclusions.

Documentation format in domain plan:

### Testing: Parallel Run

**Target function**: `calculateShipping()` at `file:line`
**Comparison criteria**:
- Result amount must match within $0.01
- Delivery date must match exactly
- Carrier selection must match
**Acceptable discrepancy rate**: < 0.1% over 10,000 invocations
**Duration**: 2 weeks minimum
**Monitoring**: Log to `{observability tool}` — ASK USER what they use

Property-Based Testing

Purpose: Discover edge cases by testing properties (invariants) that must hold for ALL inputs, not just hand-picked test cases. A test framework generates hundreds of random inputs and verifies the properties.

When to use: Algorithm replacement, business logic migration, any function where the space of valid inputs is large and edge cases are hard to enumerate.

Method:

1. Identify properties that must ALWAYS hold (e.g., "result is never negative", "output is sorted", "discount never exceeds 50%"). 2. Define input generators (random valid inputs). 3. Run the property test with 100+ iterations. 4. Any failing input is a potential regression.

Tools to recommend (verify via web search):

• Python: hypothesis
• JavaScript/TypeScript: fast-check
• Go: gopter
• Rust: proptest

Documentation format in domain plan:

### Testing: Property-Based

**Target**: `calculateDiscount()` at `file:line`
**Properties**:
- Result >= 0 (never negative)
- Result <= originalPrice (never exceeds price)
- Result >= originalPrice * 0.5 (max 50% discount, per business rule at `file:line`)
**Input space**: price [0.01, 100000], quantity [1, 1000], customerType [regular, premium]

Data Consistency Validation

Purpose: During database migration (dual-write phase), continuously verify that both databases contain the same data.

When to use: Any migration involving database changes — schema migration, database technology change, database split/merge.

Method:

1. Row count comparison — Both databases should have the same number of records (with a small lag tolerance for async sync). 2. Sample comparison — Randomly sample N records and compare field-by-field. 3. Checksum comparison — Compute checksums over key fields for large tables. 4. Reconciliation job — Scheduled job that finds and reports discrepancies.

Documentation format in domain plan:

### Testing: Data Consistency

**Tables under dual-write**: `orders`, `order_items`
**Validation frequency**: Every 15 minutes during migration
**Tolerance**: Row count difference < 100 (accounting for async lag)
**Sample size**: 1000 random records per validation run
**Discrepancy handling**: Log to monitoring, alert if > 0.1% mismatch

Visual Regression Testing

Purpose: Detect unintended visual changes when migrating frontend components.

When to use: Frontend framework migration, CSS refactoring, component library replacement.

Method:

1. Capture screenshots of every page/component BEFORE migration. 2. After migrating a component, capture screenshots again. 3. Pixel-diff comparison identifies visual regressions.

Tools to recommend (verify via web search):

• Playwright visual comparisons
• Chromatic (Storybook)
• Percy
• BackstopJS

Documentation format in domain plan:

### Testing: Visual Regression

**Pages/components captured**: {List with routes or component names}
**Baseline screenshots**: `./migration-plan/visual-baselines/`
**Tool**: {Verified via web search — include version}
**Threshold**: < 0.1% pixel difference per component

Testing Phase Timeline

Map testing strategies to migration phases: