ln-76-architecture-migration-planner

# Architecture Migration Planner

**Goal:** Create a safe, reversible transition from an evidenced current architecture to an explicit target architecture. Change only the approved migration document; do not execute migrations, edit product code, build a generic task plan, approve delivery, or hide irreversible steps.

**Execution contract:** Treat the ordered checkbox workflow below as this skill's Definition of Done. Track every checkbox as `PENDING`, then resolve it to `PROVEN` with concrete evidence, `CLEARED` with evidence that its conditional trigger is absent, or `UNPROVEN`; reading, mentioning, delegating, skipping, or tool failure is not proof.
Before returning, resolve every `PENDING`, count only `PROVEN` and `CLEARED` items as complete, apply this skill's verdict, decision, and approval rules to every `UNPROVEN`, and prepend **Checklist: X/Y complete**<br>**Incomplete: None | section/item — reason; outcome impact; exact next action**; list every `UNPROVEN` item.

## Tool Routing

| Need | Preferred capability | Fallback |
|---|---|---|
| Current and target states | Repository evidence plus approved architecture artifacts | Explicit user-provided states with limitations |
| Consumers and compatibility | Language intelligence, schema tools, config search, telemetry, and direct inspection | Conservative inventory marked `UNVERIFIED` |
| Data scale and runtime risk | Production metrics, checked-in reports, migrations, and workload evidence | Ranges with validation gates before execution |
| External migration constraints | Official vendor migration and compatibility guidance | Mark dependent phases `BLOCKED` or `UNVERIFIED` |
| Document mutation | Minimal patch to the approved migration-plan artifact | Return `BLOCKED` when authority or path is unclear |

A migration phase must leave the system in a supported state. Additive and reversible steps precede cutover; destructive cleanup follows verified zero use.

## Artifact Rules

- Reuse a clear architecture migration document; otherwise use `docs/architecture/migration-plan.md`.
- Treat current-state, target-design, baseline, decisions, diagrams, interfaces, and telemetry as optional shared evidence.
- Keep the plan architectural: phases, compatibility, data, topology, gates, rollback, ownership, and removal.
- Leave file-level implementation tasks to downstream planning.
- Separate preparation, coexistence, migration, cutover, stabilization, and removal.
- Never describe rollback as "revert" when data or external effects are not reversible.
- Give every destructive step explicit approval, backup, restoration, and zero-consumer evidence requirements.

## Checklist

### 1. Establish the Transition Contract

- [ ] Resolve migration scope, business outcome, current state, target state, non-goals, deadline or horizon, owners, and approved destination.
- [ ] Read repository instructions, Git state, relevant architecture artifacts, migrations, deployment configuration, and compatibility policies.
- [ ] Verify that current and target states are specific enough to compute a gap; return `BLOCKED` rather than invent either state.
- [ ] Identify protected user journeys, invariants, SLOs, recovery objectives, compliance duties, and change windows.
- [ ] Keep the run read-only except for the approved migration document.

### 2. Build the Gap and Dependency Map

- [ ] Inventory affected modules, deployables, data stores, schemas, APIs, events, configuration, infrastructure, and operational procedures.
- [ ] Inventory internal and external consumers, owners, versions, traffic, data volume, and evidence quality.
- [ ] Map current-to-target changes in boundaries, ownership, contracts, data, runtime topology, observability, and failure behavior.
- [ ] Identify shared mutable resources, sequencing dependencies, long-running work, mixed-version windows, and irreversible effects.
- [ ] Record unknown consumers or usage as migration risks; absence of search results is not zero usage.

### 3. Design Compatibility and Data Safety

- [ ] Define old/new contract compatibility, version negotiation, adapters, dual-read or dual-write behavior, and deprecation policy where relevant.
- [ ] Use expand/migrate/contract for schema and data-shape changes; keep additive and destructive operations in separate releases.
- [ ] Define backfill selection, batching, throttling, idempotency, checkpoints, retries, reconciliation, and correctness oracle.
- [ ] Define source of truth during coexistence and conflict handling for concurrent writes.
- [ ] Define backup, restore, RPO/RTO impact, privacy, retention, and audit evidence for data movement.

### 4. Build Reversible Phases

- [ ] Define preparation, shadow or coexistence, progressive migration, cutover, stabilization, and old-path removal as independently verifiable phases.
- [ ] For every phase, state prerequisites, changed architecture state, owner, entry gate, observable success, abort condition, rollback or roll-forward action, and exit evidence.
- [ ] Define feature flags, routing controls, canary cohorts, rate limits, maintenance windows, and blast-radius controls where justified.
- [ ] Define metrics, logs, traces, reconciliation reports, dashboards, alerts, and SLO gates needed before traffic or data movement.
- [ ] Keep old and new versions interoperable through realistic deployment ordering and rollback windows.

### 5. Plan Cutover and Removal

- [ ] Define go/no-go authority, communication, freeze conditions, exact cutover control, and immediate verification.
- [ ] Define rollback boundaries separately for code, configuration, traffic, schema, and already-migrated data.
- [ ] Require measured zero use, migrated consumers, retention expiry, and explicit approval before destructive removal.
- [ ] List old code paths, contracts, flags, adapters, jobs, data, infrastructure, dashboards, and documentation to remove.
- [ ] Define post-cutover observation period, ownership handoff, incident response, and closure ev