migration-guide — write upgrade steps for a breaking change

Produce a guide that lets a user on the old version land on the new one with the least friction.

Pin down what actually broke

Identify the precise breaking change before writing a word. Get it from the diff and history, not from the description alone:

• git diff <old>..<new> on the affected surface, and gh pr view <n> for the

PR that introduced it.

• Dispatch the researcher (purpose: explore) to confirm the exact old and new

shapes: the old name/signature/default, the new one, and whether a compatibility shim or deprecation window exists.

Never document a rename or signature change from memory — the exact symbols are what users will copy.

Structure

# Migrating to <version>

## What changed <one paragraph: the change and why, in user terms>

## Upgrade steps

1. <ordered, mechanical steps>

## Before / after # before ... # after ...

## If you can't upgrade yet <deprecation window, shim, or flag to opt out — if one exists>

Write the steps

• Make each step mechanical and verifiable ("rename --foo to --bar", not

"update your flags"). A user should be able to follow it without rereading the whole guide.

• Show a minimal, real before/after for each distinct change. Keep examples

copy-pasteable.

• State explicitly when there is no automated path and a manual edit is

required.

Verify

Route the finished guide through the reviewer (purpose: review). Migration guides are acted on directly, so a wrong flag name or step is high-cost — the cross-vendor fact-check is worth it here.