Migration Guide

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.