Migration Guide Template

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/templates/migration-guide.md
Description	Not specified

Source Content

Migration Guide Template

Moves a reader from an old way to a new one without breaking their system. Composite form: how-to steps plus reference-grade breaking-change tables.

Skeleton

# Migrate from {{old}} to {{new}}

{{Two-person story first — it sets the stakes before anything else is
said: "Jack upgraded in place on a Friday and spent the weekend rolling
back. Jill migrated a staging copy first, hit the auth break safely, and
shipped Monday." This guide is Jill's checklist.}}

{{Who must migrate, by when, and what breaks if they don't.}}

## What changed and why

{{The decision in two or three sentences; link the ADR.}}

{{Mermaid flowchart of the migration path, including the rollback exit —
follow the diagram rules in ../mermaid.md.}}
_{{What to notice in the diagram.}}_

## Before you start

{{Backups, version floors, and a rollback path — one per bullet.}}

## Steps

1. {{Each step with the exact command and the expected result.}}

## Breaking changes

{{A table: each break, its symptom, and the fix — one row per change,
no empty cells.}}

## Verify

{{How to confirm the migration succeeded.}}

## The useful ending

{{One or two sentences, after everything above: what each person from the
opening walked away with, now that this is written down.}}

Rules for this template

• The rollback path is written before the steps — never after an incident.
• Every step names its expected result so the reader knows the moment something went sideways.
• Version numbers are exact (v2.3.1), never “latest”.
• Cast: always Jack (the path with friction) and Jill (the path that works) — see ../personas.md.
• Reminders: story, own line per person · useful ending.
• Format: short paragraphs · lists and tables · diagram + “what to notice”.