Migration

Move a system safely from a documented current state to a defined target state.

Purpose

Move a system safely from a documented current state to a defined target state.

Recommended

  • Describe the current and target states, compatibility requirements, dependencies, and the observable completion conditions.
  • Identify data, schema, API, configuration, operational, and user-facing impacts before choosing a sequence.
  • Make the migration incremental where practical, validate intermediate states, and define what can coexist during the transition.
  • Design rollback before execution: checkpoints, triggers, owner, data handling, recovery time, and the difference between rollback and fix-forward.
  • Make destructive steps, deprecations, cleanup, and irreversible decisions explicit and separately reviewable.
  • Define validation for the source, transition, target, and post-cutover state before retiring old paths or data.

Avoid

  • Treating a successful copy or deploy as proof that the migration is complete.
  • Removing compatibility or legacy data before the target path and rollback evidence are established.
  • Leaving rollback as an emergency slogan without a trigger, procedure, decision owner, and data plan.
  • Combining unrelated cleanup or redesign with a migration that already carries transition risk.

Prompt skeleton

Prompt skeleton — deterministic, no model call

Current state
[Describe the source system, data, schemas, versions, traffic, and known constraints.]

Target state
[Define the destination behavior, architecture, data shape, ownership, and success criteria.]

Compatibility requirements
[State backward/forward compatibility, coexistence, consumer, and rollout constraints.]

Data and schema impact
[List affected records, schemas, transformations, consistency risks, and backup needs.]

Dependencies
[Identify services, releases, permissions, owners, maintenance windows, and external dependencies.]

Migration sequence
[Describe ordered, reversible steps, checkpoints, observability, and intermediate validation.]

Rollback
[Define triggers, decision owner, exact procedure, data handling, recovery target, and fix-forward alternative.]

Deprecation and cleanup
[State what remains during coexistence and the evidence required before removal.]

Validation
[Name pre-migration, transition, cutover, rollback rehearsal, and post-migration checks.]

Completion conditions
[Define the evidence that the target is healthy and the migration is safe to close.]

From templates/migration.md. Placeholders describe what to fill in; nothing here invents project facts.

Evidence

official

Sources