Migration Strategy

1. Purpose

This skill selects the safest migration strategy for a given codebase by reading the four signals already recorded in AUDIT.md — module coupling (fan-out), test coverage, consumer count, and LOC — and running them through a decision table that produces one of three concrete strategies: Big Bang, Strangler Fig, or Parallel Run. The output is MIGRATION-PLAN.md, a committed document that defines the strategy, the ordered sequence of Phase 3 and 4 skill invocations, the skill dependency graph, a risk register with mitigations, a rollback decision tree naming specific roles, and the go/no-go criteria that gate Phase 6 cut-over. This skill runs after codebase-audit (Phase 1) and before any Phase 3 preparation or Phase 4 migration work begins — every downstream skill reads MIGRATION-PLAN.md to understand its execution context. The strategy is not chosen by intuition or preference; it is derived mechanically from audit data, and the derivation is recorded in the plan so any engineer can audit the reasoning.

---

2. Trigger Conditions

Use when:

• AUDIT.md exists at the repo root, all seven numbered sections are populated, and no section contains a ` placeholder — run grep -c '

---

4. Steps

1. Read audit_file in full. Extract and record the four strategy-selection signals for each module in scope. Write them to output/migration-strategy-signals-.json:

``json { "extracted_at": "", "audit_file": "", "modules": [ { "path": "", "fan_out": "", "fan_out_count": "", "coverage_pct": "", "consumer_count": "", "loc": "", "source_section": "" } ], "cve_verdict": "", "performance_baselines": { "coverage_pct": "", "bundle_size_gzip_kb": "", "startup_ms": "", "p99_latency_ms": "", "cve_count_critical": "", "cve_count_high": "" } } ``

Signal classification rules — apply to each module:

• fan_out: Low = fan-out count ≤ 3; Medium = 4–8; High = ≥ 9. Source: AUDIT.md §3.1.
• coverage_pct: read directly from AUDIT.md §4.1 for the module's row. If absent, treat as 0% and flag as [UNCERTAIN — not in audit coverage table].
• consumer_count: fan-in count for the module from AUDIT.md §3.2. Counts internal importers only; external API consumers (HTTP clients, SDK users) are listed separately in AUDIT.md §7.4 and added on top.
• loc: estimate from the coupling report in output/codebase-audit-coupling-*.json if available; otherwise run wc -l /**/*.{ts,js,py,rb,go} and record the result.

If any signal cannot be extracted from AUDIT.md (missing row, section not populated, or marked [UNCERTAIN]), record the signal as null and treat the module as requiring Parallel Run — missing data is a risk, not a free pass to a lighter strategy.

1. Apply the strategy decision table to each module. Derive the recommended strategy for the overall migration scope by taking the most conservative recommendation across all modules.

| Fan-out | Coverage | Consumer count | LOC | Recommended strategy | |---------|----------|----------------|-----|----------------------| | Low | ≥ 70% | ≤ 3 | Any | Big Bang | | Medium | ≥ 70% | Any | 10 | Any | Parallel Run | | Any signal = null | — | — | — | Parallel Run |

Tie-breaking rule: when multiple rows match, select the row that appears latest in the table (most conservative). A module that matches both "Medium / ≥70% / Any / .json under "strategy_derivation"`.

1. Determine the overall migration strategy as the most conservative strategy across all modules in scope:

• If any module requires Parallel Run → overall is Parallel Run.
• If no module requires Parallel Run but any requires Strangler Fig → overall is Strangler Fig.
• If all modules permit Big Bang → overall is Big Bang.

Write the strategy selection and derivation to the migration log.

1. Write output_plan_file (MIGRATION-PLAN.md) using the template below. Replace every ` with real content derived from audit_file`, the signals JSON, and the strategy derivation. Do not leave any section as "TBD" or copy placeholder text verbatim.

`````markdown # Migration Plan —

> Produced by skills/02-strategize/migration-strategy · agent-revamp-skills > Based on: AUDIT.md (audit date: ) > Skill version: 0.1.0

| Field | Value | |-------|-------| | Migration goal | | | Source stack | | | Target stack | | | Selected strategy | | | Primary engineer | | | Plan date | | | Overall risk level | | | Sign-off status | PENDING |

---

## 1. Strategy Selection

### 1.1 Audit Signals

| Module | Fan-out | Fan-out Count | Coverage % | Consumer Count | LOC | Signal Source | |--------|---------|--------------|------------|----------------|-----|---------------| | | Low \| Medium \| High | | | | | AUDIT.md §3.1, §4.1 |

Performance baselines (reference point for Phase 5 equivalence gates):

| Metric | Baseline | Source | Date | |--------|---------|--------|------| | Line coverage (overall) | | AUDIT.md §4.1 | | | Bundle size (gzip) | | AUDIT.md §5.1 | | | Startup time (median cold start) | | AUDIT.md §5.2 | | | p99 latency (highest-traffic route) | | AUDIT.md §5.3 | | | Critical CVE count | | AUDIT.md §6.1 | | | High CVE count | | AUDIT.md §6.1 | |

### 1.2 Decision Table Application

| Module | Matching Row | Resulting Strategy | Override Applied? | |--------|-------------|-------------------|------------------| | | | | None \| |

### 1.3 Selected Strategy:

#### What this strategy means concretely

Big Bang: The entire migration unit is replaced in a single release. No coexistence period. The old stack is removed the same day the new stack is deployed. This is safe only when: fan-out is Low, coverage is ≥ 70%, and consumer count is ≤ 3 — meaning the blast radius is small and detectable in tests. Pre-conditions: all Phase 3 preparation complete, all Phase 5 equivalence tests passing in staging. Rollback is a git revert plus one deploy; the window is measured in minutes.

Strangler Fig: The new stack is built alongside the old. Traffic is shifted incrementally by path prefix, feature flag, or percentage rollout. Both stacks coexist for the duration of Phase 4 (days to weeks). Each migrated route or module is validated independently before the next is migrated. The old stack is removed only when all routes have migrated and Phase 5 shadow mode shows 0.0% divergence over 24 hours. Rollback per route is a proxy config change; full rollback is a feature flag flip.

Parallel Run: Both stacks process the same production inputs simultaneously. The old stack's output is served to users; the new stack's output is logged and compared asynchronously. No user-facing traffic cut-over occurs until divergence rate reaches exactly 0.0% over a sustained window (minimum 24 hours). This strategy is mandatory when coverage is below 70% — the test suite cannot detect all regressions, so production traffic comparison is the only reliable equivalence signal. Rollback at any time is stopping the new stack's parallel processing; users are never exposed to new-stack output during this phase.

---

## 2. Phase Sequence

| Order | Phase | Skill | Target Module / Unit | Depends On (order #) | Parallelizable With | |-------|-------|-------|----------------------|----------------------|---------------------| | 1 | 3 | test-coverage-baseline | | — | — | | 2 | 3 | | | 1 | — | | 3 | 4 | | | 1, 2 | | | 4 | 5 | behavioral-equivalence | | 3 | — |

---

## 3. Skill Dependency Graph

`` 1 → (no dependencies) 2 → 1 3 → 1, 2 4 → 3 ``

Cycle check:

---

## 4. Risk Register

| # | Risk | Source | Likelihood (1–3) | Impact (1–3) | Score | Mitigation | Residual Score | |---|------|--------|-----------------|-------------|-------|------------|----------------| | 1 | | AUDIT.md § | | | | | | | 2 | | AUDIT.md § | | | | | | | 3 | | AUDIT.md § | | | | | |

Halt check:

---

## 5. Rollback Decision Tree

`` Is the migration in progress? ├── No → No rollback needed. └── Yes ├── Is this a Big Bang migration? │ ├── Yes → Is the new stack returning 5xx for >1% of requests? │ │ ├── Yes → executes git revert + deploy within 15 min. │ │ │ Notify: │ │ └── No → Continue monitoring. Re-evaluate at next 15-min checkpoint. │ └── No (Strangler Fig or Parallel Run) │ ├── Is shadow mode divergence rate >0.1% over any 1-hour window? │ │ ├── Yes → sets feature flag to old stack within 5 min. │ │ │ File incident. Notify: │ │ │ Do not re-enable new stack until divergence root cause is identified. │ │ └── No → Continue. Re-evaluate at next 15-min checkpoint. │ └── Has any migrated route returned 5xx in staging that was 200 in old stack? │ ├── Yes → reverts the proxy config for that route only. │ │ Does not roll back other routes. Files a regression report. │ └── No → Continue. ``

Rollback authority:

• Route-level rollback (Strangler Fig / Parallel Run): ` can execute without approval. Must notify ` within 30 minutes.
• Full rollback (all routes / Big Bang revert): requires sign-off from one stakeholder in ` unless the incident is P0 (complete outage), in which case ` acts immediately and notifies within 15 minutes.
• Rollback window: tracked from the moment Phase 4 begins for each unit. The window closes when Phase 5 behavioral-equivalence returns PASS and Phase 6 cut-over is complete.

---

## 6. Hard Constraints Applied

| Constraint | Effect on Strategy or Sequencing | |-----------|----------------------------------| | | |

---

## 7. Go / No-Go Criteria for Phase 6 Cut-over

• [ ] behavioral-equivalence VALIDATION-REPORT.md verdict is PASS for all migrated units — grep VALIDATION-REPORT.md for PASS.
• [ ] Shadow mode ran ≥ 24 continuous hours with 0.0% divergence rate — read shadow log timestamps and compute rate.
• [ ] All golden fixtures in tests/golden/ are committed and passing — npx jest tests/golden/ exits 0.
• [ ] p99 latency for all migrated routes is ≤ baseline recorded in §1.1 + 5ms tolerance — read APM or k6 output.
• [ ] No CRITICAL CVEs introduced by new dependencies — npm audit --audit-level=critical exits 0 (or language equivalent).
• [ ]
• [ ]
• [ ] All stakeholders in § Sign-off below have confirmed readiness for production cut-over.

---

## Sign-off

> This section must be completed before Phase 3 begins. > No preparation or migration work may start until Status is APPROVED.

| Role | Name | Date | Notes | |------|------|------|-------| | Primary engineer | | | | | | | | | | | | | |

Status: PENDING

> To approve: fill in your Date and Notes above, then change Status to APPROVED. `````

1. Run a halt check on the risk register. Read the completed risk table in MIGRATION-PLAN.md §4. For any row where Score ≥ 6 AND the Mitigation column contains only "TBD", "none", or is blank:

• Do not commit MIGRATION-PLAN.md.
• Write a blocking finding to the migration log: "Risk #N (score ) has no mitigation. Return to Phase 1 to gather: ." The specific information must name a concrete artifact (e.g., "test coverage report for src/auth/", "load test results for /api/payments") not a vague action ("investigate further").
• STOP. Do not proceed to Step 6.

1. Commit MIGRATION-PLAN.md to the repo root. The commit message must be: plan: establish migration strategy for (Phase 2). This commit is a distinct, standalone point in git history — do not squash it with Phase 3 preparation work, because it is the reference point for "what was decided before we started."

1. Present MIGRATION-PLAN.md to primary_engineer and stakeholders for review. Ask each stakeholder to fill in their Date and Notes in § Sign-off and change Status from PENDING to APPROVED. Do not begin Phase 3 until Status is APPROVED and every stakeholder row has a Date.

• If a stakeholder rejects the plan (declines to sign, or adds a Note indicating disagreement): record the rejection reason in the migration log, archive the current plan to output/MIGRATION-PLAN-rejected-.md, and STOP with: "Plan rejected by : . Address the feedback and re-run this skill."

1. Write all outputs declared in Section 7. Run every Equivalence Test in Section 6 and record results in output/migration-strategy-equiv-.md. Evaluate every item in Section 9 Done Criteria; report pass/fail inline, then print the final verdict.

---

5. Agent Handoffs

migration-planner

• File: agents/migration-planner.md
• Triggered by: Step 4 (writing the phase sequence and dependency graph)
• Prompt template:

`` GOAL: AUDIT_FILE: REPO_ROOT: CONSTRAINTS: EXCLUDE_UNITS: MANIFEST_FORMAT: json OUTPUT_PLAN_FILE: OUTPUT_MANIFEST_FILE: output/migration-manifest-.json ` The planner populates §2 Phase Sequence and §3 Skill Dependency Graph in MIGRATION-PLAN.md`. The skill writes the strategy selection (§1) and risk register (§4) itself — do not delegate those to the planner. Only delegate the sequencing and dependency ordering.

---

6. Equivalence Tests

| Test Name | Input | Expected Output | Tool | |-----------|-------|-----------------|------| | plan-file-exists | ls | File exists and is >2 KB — a file smaller than 2 KB is the skeleton template, not a completed plan. | Bash: wc -c returns a value >2048. | | no-placeholders-remain | grep -c '' | Returns 0 — no unfilled placeholder text remains in the committed plan. | Bash: count must be 0. | | strategy-cited | Read MIGRATION-PLAN.md §1.3 | Section names the strategy (Big Bang, Strangler Fig, or Parallel Run), cites at least one fan-out count, one coverage %, and one AUDIT.md section reference (e.g., AUDIT.md §3.1). | Read — grep for AUDIT.md § in §1.3; count must be ≥ 1. | | decision-table-recorded | Read MIGRATION-PLAN.md §1.2 | Table has one row per module in scope, each row names the matching decision-table row and the resulting strategy. No row says "intuition" or omits a matching row. | Read | | risk-register-≥3-rows | Read MIGRATION-PLAN.md §4 risk table | Table has ≥ 3 data rows. Every row has a non-empty Mitigation column. No row has Score ≥ 6 with Mitigation = "TBD" or blank. | Read + Bash: grep -c '| [0-9]' MIGRATION-PLAN.md ≥ 3 in the risk table block. | | dependency-graph-acyclic | Read MIGRATION-PLAN.md §3 adjacency list | No order number appears in its own dependency list, directly or transitively. A cycle would mean a skill waits for itself. | Read — manually verify or run topological sort: python3 -c "import sys; ..." against the adjacency list. | | rollback-names-role | Read MIGRATION-PLAN.md §5 | Every leaf action in the rollback decision tree names a specific person or role (e.g., @alice, primary_engineer, on-call engineer). No leaf says "the team", "someone", or "engineering". | Read — grep for the team\|someone\|engineering in §5; count must be 0. | | baselines-recorded | Read MIGRATION-PLAN.md §1.1 performance baselines table | Coverage %, bundle size, startup time, p99 latency, and CVE counts are all populated (or expl

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Siddharth00
• Source: Siddharth00/agent-revamp-skills
• License: MIT

Install and usage instructions live in the source repository linked above.