Migration Strategy

Produce a phased, evidence-backed migration plan for transitioning from the as-is architecture to the target architecture. Each phase includes concrete steps, validation gates, rollback triggers, and risk mitigations linked to the gap analysis. The strategy prioritizes safety — moving the safest, highest-impact changes first.

When to Use This Skill

• After completing Target Architecture to plan how to get there
• When stakeholders need a concrete, phased plan with timelines
• When the team needs to understand migration risks and rollback options
• As input to Refactor Backlog and Roadmap generation
• When coordinating a large-scale refactoring or modernization effort

Pipeline Position

[TO_BE_ARCHITECTURE.md + ARCH_GAPS_AND_RISKS.md + AS_IS_SYSTEM_MODEL.md] --> **MIGRATION STRATEGY** --> [MIGRATION_PLAN.md] --> Refactor Backlog & Roadmap --> ...

Input: TO_BE_ARCHITECTURE.md, ARCH_GAPS_AND_RISKS.md, AS_IS_SYSTEM_MODEL.md Output: MIGRATION_PLAN.md written to artifacts directory

Artifact Template

The output artifact follows the standard artifact template:

# [ARTIFACT TITLE]
## Summary
## Inputs
## Outputs
## Assumptions
## Open Questions
## Main Content
## Acceptance Criteria

Process

Step 1: Read Upstream Artifacts

1. Read TO_BE_ARCHITECTURE.md to understand:
   • Target components (TCOMP-NNNN)
   • Migration delta table (what changes, what stays)
   • Technology decisions (TDEC-NNNN)
   • Interface contracts (IFACE-NNNN)
   • Gap/Risk resolution map
2. Read ARCH_GAPS_AND_RISKS.md to understand:
   • Gap inventory (GAP-NNNN) with priorities
   • Risk registry (RISK-NNNN) with severities
   • Hotspot analysis
3. Read AS_IS_SYSTEM_MODEL.md to understand:
   • Current components (COMP-NNNN) and their dependencies
   • Current data flows and integration points
4. Build dependency graph: Map which target changes depend on which other changes completing first

Step 2: Determine Migration Approach

Select the overall migration strategy based on system characteristics.

1. Evaluate approaches:

   • Strangler Fig: Gradually replace components while keeping the old system running. Best for: systems with clear entry points, low coupling between modules.
   • Big Bang: Replace entire system at once. Best for: small systems, tightly coupled code where partial migration is impossible.
   • Parallel Run: Run old and new systems simultaneously, comparing outputs. Best for: critical data processing systems, financial calculations.
   • Feature Toggle: Migrate behind feature flags, enabling gradual rollout. Best for: user-facing applications, SaaS products.
   • Branch by Abstraction: Introduce abstraction layer, implement new version behind it, swap. Best for: deep library/framework changes.

2. Document decision:

### Migration Approach: [Selected Approach]
- **Rationale**: [Why this approach fits the system and constraints]
- **Alternatives Rejected**: [Other approaches and why they don't fit]
- **Constraints Respected**: [CON-NNNN from review brief]
- **Risk Level**: Low | Medium | High

Step 3: Design Migration Phases

Break the migration into ordered phases, safest and highest-impact first.

Phase ordering principles:

1. Foundation first: Infrastructure, tooling, and patterns that other changes depend on
2. Safety first: Security fixes (P0 gaps) before feature improvements
3. Inside out: Core abstractions before peripheral components
4. Low risk first: Changes with easy rollback before irreversible changes
5. Quick wins early: High-impact, low-effort changes to build momentum

For each phase, define:

### PHASE-0001: [Phase Title]
- **Duration**: [Estimated time range]
- **Objective**: [One-sentence goal of this phase]
- **Prerequisites**: [PHASE-NNNN IDs that must complete first, or "None"]
- **Migration Approach**: [Which overall approach applies to this phase]

#### Changes
| Change ID | Description | Type | From (AS-IS) | To (TO-BE) | Gaps Addressed |
|-----------|-------------|------|-------------|-----------|----------------|
| CHG-0001 | Introduce repository pattern | Refactor | COMP-0003 | TCOMP-0004 | GAP-0001 |
| CHG-0002 | Add input validation middleware | Add | (none) | TCOMP-0001 | GAP-0003, RISK-0002 |

#### Validation Gate: GATE-0001
- **Name**: [Gate name]
- **Criteria**:
  - [ ] [Specific, measurable validation criterion]
  - [ ] [Additional criterion]
- **Validation Method**: [How to verify: automated tests, manual review, load test, security scan]
- **Pass Threshold**: [What constitutes passing]
- **Blocking**: Yes | No (if No, phase can proceed with documented exceptions)

#### Rollback Strategy
- **Trigger Conditions**: [What would trigger a rollback]
  - [Specific metric threshold or failure condition]
  - [Additional trigger]
- **Rollback Steps**:
  1. [Step-by-step rollback procedure]
  2. [Next step]
- **Rollback Time Estimate**: [How long rollback takes]
- **Data Considerations**: [How to handle data created during the phase]
- **Point of No Return**: [Is there a point after which rollback is not feasible? If so, when?]

#### Risk Mitigations
| Risk ID | Mitigation Action | Owner | Status |
|---------|------------------|-------|--------|
| RISK-0001 | [Specific mitigation for this phase] | [Role] | Planned |

Assign PHASE-NNNN IDs: Phases are ordered by execution sequence, numbered sequentially starting at 0001.

Step 4: Define Validation Gates

Create a comprehensive validation gate inventory.

1. For each phase transition, define a GATE:

### GATE-0001: [Gate Name]
- **Phase**: PHASE-0001 -> PHASE-0002 (or PHASE-0001 completion)
- **Type**: Automated | Manual | Hybrid
- **Criteria**:
  - [ ] All unit tests pass (zero failures)
  - [ ] Integration tests cover new interfaces
  - [ ] No P0 or P1 regressions in affected components
  - [ ] Performance benchmarks within acceptable range
  - [ ] Security scan shows no new vulnerabilities
- **Evidence Required**: [What artifacts prove the gate is passed]
- **Approval Required**: [Who must sign off]
- **Fallback**: [What happens if gate fails]

2. Gate types:

   • Quality Gate: Tests pass, coverage maintained, no regressions
   • Performance Gate: Latency, throughput, resource usage within bounds
   • Security Gate: No new vulnerabilities, secrets properly managed
   • Data Gate: Data integrity verified, migration scripts validated
   • Operational Gate: Monitoring, logging, alerting in place for new components
   • Business Gate: Stakeholder approval, feature parity confirmed

3. Assign GATE-NNNN IDs: Number sequentially by phase order, then by gate order within phase

Step 5: Map Risk Mitigations

Link every RISK-NNNN from the gap analysis to specific mitigation actions within migration phases.

1. For each RISK-NNNN, determine:

   • When mitigated: Which PHASE addresses this risk
   • How mitigated: Specific actions taken
   • Residual risk: What risk remains after mitigation
   • Monitoring: How to detect if the risk materializes during migration

2. Risk mitigation matrix:

| RISK ID | Title | Severity | Mitigated In | Mitigation Action | Residual Risk | Monitor |
|---------|-------|----------|-------------|-------------------|---------------|---------|
| RISK-0001 | DB single point of failure | Critical | PHASE-0002 | Add read replica + failover | Manual failover delay | DB health check |
| RISK-0003 | Auth token leakage | High | PHASE-0001 | Rotate secrets, add vault | Key rotation window | Audit logs |

3. Unmitigated risks: If any RISK-NNNN cannot be mitigated within the migration plan, document explicitly with rationale and acceptance criteria

Step 6: Define Communication and Coordination Plan

Outline how migration progress is tracked and communicated.

1. Stakeholder communication:

   • Phase start/completion notifications
   • Gate pass/fail notifications
   • Rollback event notifications
   • Progress reporting cadence

2. Team coordination:

   • Branch strategy for concurrent work
   • Code freeze windows if needed
   • Dependency coordination between teams
   • Handoff procedures between phases

3. Documentation updates:

   • When to update architecture documentation
   • How to keep artifacts in sync during migration
   • Post-migration documentation requirements

Step 7: Create Migration Timeline

Produce a visual timeline of the migration.

1. Phase dependency diagram:

```mermaid
graph LR
    PHASE-0001[Phase 1: Foundation] --> PHASE-0002[Phase 2: Security]
    PHASE-0001 --> PHASE-0003[Phase 3: Data Layer]
    PHASE-0002 --> PHASE-0004[Phase 4: API Refactor]
    PHASE-0003 --> PHASE-0004
    PHASE-0004 --> PHASE-0005[Phase 5: Performance]

2. **Gantt chart** (estimated):
```markdown
```mermaid
gantt
    title Migration Timeline
    dateFormat  YYYY-MM-DD
    section Foundation
    PHASE-0001: Foundation           :p1, 2026-03-01, 2w
    GATE-0001: Quality Gate          :milestone, g1, after p1, 0d
    section Security
    PHASE-0002: Security Hardening   :p2, after g1, 1w
    GATE-0002: Security Gate         :milestone, g2, after p2, 0d
    section Data Layer
    PHASE-0003: Data Abstraction     :p3, after g1, 3w
    GATE-0003: Data Gate             :milestone, g3, after p3, 0d

### Step 8: Compile Migration Plan Artifact

Assemble all findings into the final artifact.

1. **Write** `MIGRATION_PLAN.md` following the template
2. **Verify** every GAP-NNNN is addressed in at least one phase
3. **Verify** every RISK-NNNN has a mitigation entry
4. **Verify** every phase has a validation gate and rollback strategy
5. **Verify** phase dependencies form a valid DAG (no circular dependencies)

## Output Format

### MIGRATION_PLAN.md Structure

```markdown
# Migration Plan: [Project Name]

## Summary
[3-5 sentences: number of phases, overall timeline estimate, migration approach, key risks]

## Inputs
- TO_BE_ARCHITECTURE.md
- ARCH_GAPS_AND_RISKS.md
- AS_IS_SYSTEM_MODEL.md

## Outputs
- MIGRATION_PLAN.md (this document)

## Assumptions
- [ASM-NNNN]: [Assumption with rationale]

## Open Questions
- [OQ-NNNN]: [Questions requiring resolution before migration begins]

## Main Content

### Migration Approach
[Approach selection with rationale]

### Phase Overview
| Phase ID | Title | Duration | Prerequisites | Gaps Addressed | Gate |
|----------|-------|----------|--------------|----------------|------|

### Phase Details
[PHASE-NNNN entries with full detail including changes, gates, rollback, mitigations]

### Validation Gate Registry
| Gate ID | Phase | Type | Key Criteria | Approval |
|---------|-------|------|-------------|----------|

### Rollback Summary
| Phase | Trigger | Rollback Time | Point of No Return |
|-------|---------|--------------|-------------------|

### Risk Mitigation Matrix
| RISK ID | Severity | Phase | Action | Residual Risk |
|---------|----------|-------|--------|---------------|

### Migration Timeline
```mermaid
[Phase dependency diagram]

[Gantt chart]

Communication Plan

[Stakeholder and team coordination details]

Gap Resolution Coverage

GAP ID	Priority	Addressed In	Change IDs

Success Criteria

• All PHASE gates passed
• All P0 and P1 gaps resolved
• All critical and high risks mitigated
• Zero data loss during migration
• Rollback procedures tested for each phase

Acceptance Criteria

• Every phase has validation gate and rollback strategy
• Every GAP-NNNN addressed in at least one phase
• Every RISK-NNNN has mitigation entry
• Phase dependencies form valid DAG
• Timeline includes realistic duration estimates
• Rollback triggers are specific and measurable
• Communication plan covers all stakeholders

**Output path**: `artifacts/brownfield/<project_name>/MIGRATION_PLAN.md`

**Template**: `${CLAUDE_PLUGIN_ROOT}/reference/templates/MIGRATION_PLAN.template.md`

## Determinism Rules

These rules ensure reproducible output regardless of when or how many times the skill is invoked on the same inputs.

1. **PHASE-NNNN IDs**: Ordered by execution sequence (dependency-respecting topological sort), numbered sequentially starting at 0001. For phases at the same dependency level, sort alphabetically by phase title.
2. **GATE-NNNN IDs**: Numbered sequentially by phase order, then by gate order within a phase, starting at 0001
3. **CHG-NNNN IDs**: Within each phase, sort changes alphabetically by description, assign sequentially starting at 0001 per phase (or globally, consistently)
4. **Risk mitigation rows**: Sort by RISK-NNNN ID numerically
5. **Gap resolution rows**: Sort by GAP-NNNN ID numerically
6. **Phase overview table rows**: Sort by PHASE-NNNN ID
7. **Sections**: Always in template order, never reordered
8. **No timestamps**: Do not include generation timestamps in artifact body (Gantt chart dates are planning estimates, not generation timestamps)
9. **Gantt chart dates**: Use relative offsets from a configurable start date if actual dates are not known

## Evidence Citation Rules

Migration strategy references upstream artifacts rather than raw code (since code evidence was already established in prior skills).

**Format for upstream references**: `[ARTIFACT_NAME: ID]` (e.g., `[TO_BE: TCOMP-0003]`, `[ARCH_GAPS: GAP-0001]`, `[AS_IS: COMP-0002]`)

**Examples**:
```markdown
> Phase 1 addresses the critical security gap [ARCH_GAPS: GAP-0005] by introducing the auth service [TO_BE: TCOMP-0002]
> Rollback for this phase reverts to the original API handler [AS_IS: COMP-0001]
> This phase mitigates the database single-point-of-failure risk [ARCH_GAPS: RISK-0001]

Rules:

• Every phase change MUST reference the GAP/RISK it addresses
• Every rollback strategy MUST reference the AS-IS component it reverts to
• Every validation gate MUST reference the TCOMP it validates
• Codebase [file:line] references are acceptable for rollback procedures that reference specific files

Quality Checklist

Before finalizing the artifact, verify:

• Every PHASE has at least one validation gate (GATE-NNNN)
• Every PHASE has a rollback strategy with specific trigger conditions
• Every GAP-NNNN from gap analysis is addressed in at least one phase
• Every RISK-NNNN from gap analysis has a mitigation entry
• Phase dependencies form a valid DAG (no circular dependencies)
• Phases ordered safely: foundation first, security early, low-risk before high-risk
• Duration estimates are provided for each phase
• Rollback time estimates are provided for each phase
• Point-of-no-return is identified for irreversible changes
• Communication plan covers phase transitions and gate results
• Gantt chart reflects phase dependencies accurately
• No phase attempts changes that depend on an incomplete prerequisite phase
• CHG-NNNN entries reference both AS-IS and TO-BE component IDs
• Migration approach is explicitly chosen with rationale

Error Handling

• TO_BE_ARCHITECTURE.md not found: Report error; direct user to run target-architecture first
• ARCH_GAPS_AND_RISKS.md not found: Report error; direct user to run architecture-gap-analysis first
• No gaps to address: If gap analysis found no issues, migration plan should document a "no migration needed" conclusion with verification steps
• Circular phase dependencies: Restructure phases to break cycles; document the constraint that caused the cycle in Open Questions
• Conflicting phase ordering: If safety-first and impact-first orderings conflict, prioritize safety and document the trade-off
• Unknown duration estimates: Use ranges (e.g., "1-3 weeks") and document uncertainty in Assumptions
• External dependencies: If migration depends on external teams or vendors, flag as risks with mitigation (parallel paths, fallbacks)