# Migration Runbook (docs/history/migrations/YYYY-MM-DD-{slug}.md)

Record. Use for: a **one-shot** migration, upgrade, or data operation — authored before execution, executed once, then outcome-stamped and frozen. Supporting scripts live beside it in a same-named folder when needed (`YYYY-MM-DD-{slug}/`).

Required: **Goal**, **Steps**, **Verification**, and — after execution — the **Outcome** stamp. Optional: Preconditions, Rollback.

```
# Migration: {Title}

**Goal:** What this migration accomplishes and why it runs now, one or two lines.
**Executes against:** {environment / database / system}

## Preconditions

- Backups taken, feature flags set, access confirmed — exact checks

## Steps

1. One action per step, exact command in a code block
2. Note expected output where it disambiguates success from failure

## Verification

- The observable end state that confirms success — exact check commands

## Rollback

- How to undo, and the point of no return

## Outcome

<!-- Stamped once, immediately after execution; the file freezes with it. -->
**Executed:** YYYY-MM-DD — {result: clean | issues encountered + how resolved | aborted + why}
```