ln-76-architecture-migration-planner
Plans a reversible architecture migration with compatibility, data movement, rollout, and rollback. Use for current-to-target transitions; not execution, generic planning, or delivery review.
levnikolaevich · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add levnikolaevich/claude-code-skills --skill ln-76-architecture-migration-planner技能说明
name: ln-76-architecture-migration-planner description: "Plans a reversible architecture migration with compatibility, data movement, rollout, and rollback. Use for current-to-target transitions; not execution, generic planning, or delivery review."
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 completeIncomplete: 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
BLOCKEDrather 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 a