Migration Day Runbook Skill
File migrations fail at the edges, not the middle: work edited during the copy window (lost or forked), permissions that mapped wrong (the intern sees the comp sheet; Legal sees nothing), links across the company now pointing at a dead platform, and an old system left writable so half the team never leaves. The runbook handles the edges: a short announced freeze, copy with verification (counts and spot-checks, not vibes), a permissions remap done as its own workstream, cutover comms with the three answers everyone needs, and the old platform flipped read-only — the single move that makes migrations stick.
What This Skill Produces
- The runbook — phased: prepare → freeze → copy → verify → permissions → cutover → afterlife, each with owner and duration
- The verification plan — counts by folder, spot-restores, and the biggest-risk samples checked by hand
- The permissions remap — old-model groups/shares → new-model equivalents, with the deny-by-default posture for mismatches
- The comms set — the advance notice, the freeze reminder, and the cutover announcement with its three answers
Required Inputs
Ask for these if not provided:
- From → to, and the size — platforms, volume (GB and file count), and any known exotica (huge files, weird formats, apps writing into the old drive)
- The sharing surface — external shares, published links, and integrations pointing at the old platform; each is a breakage waiting for its line in the runbook
- The freeze tolerance — can the team stop editing for a day? A weekend? Never (then the delta-sync approach, stated)?
- The permission model gap — how sharing works old vs. new; the remap is where migrations quietly leak confidential files
Framework: The Edge Rules
- Freeze short, announce twice: the copy happens inside a declared no-edits window (evening/weekend for most teams) — announced a week out and the day before. Edits during the copy are the classic loss; the freeze is cheaper than the fork-hunt.
- Verify by count and by sample: post-copy: file counts per top-level folder old-vs-new, total size within tolerance, and hand-checks of the highest-stakes folders (Legal, Finance, the current projects). A migration is "done" when verification says so, not when the progress bar does.
- Permissions are a workstream, not a checkbox: inventory the old platform's shares (especially external ones), map to the new model, and where the models don't align, fail closed — over-restricting gets a complaint ticket; over-sharing gets an incident. External shares get re-issued deliberately, not bulk-recreated.
- The cutover announcement answers exactly three questions: where do I go now (the link) · what happened to my stuff (same structure, here's the map) · what do I do if something's missing (the named person, the SLA). Everything else is noise; these three prevent the help-desk flood.
- The old platform goes read-only, immediately: the afterlife rule — readable for the transition period (comfort + the missing-file safety net), writable never (or half the team quietly stays). A read-only banner pointing at the new home does more for adoption than any training session. Decommission date set now, calendar-reminded, executed after the retention check (document-retention-map).
Output Format
Migration Runbook: [old] → [new], [date]
Phases
| Phase |
When |
Owner |
Duration |
| [Prepare (inventory, permissions map, comms 1) · Freeze · Copy · Verify · Permissions · Cutover (comms 3) · Afterlife (read-only flip)] |
|
|
|
Verification Plan
[Counts per top folder · size tolerance · the hand-check list (highest-stakes folders) · the pass/fail line]
Permissions Remap
[Old shares inventory → new equivalents · fail-closed mismatches · external shares re-issued deliberately]
Comms
[T-7 notice · T-1 freeze reminder · cutover announcement: the three answers + the missing-file contact]
Rollback Line
[The condition that aborts (verification fails, permissions can't map) · rollback = unfreeze the old, reschedule — cheap because the old is untouched until read-only]
Quality Checks
Anti-Patterns
1---2name: migration-day-runbook3description: Move a team's files to a new platform without losing work or a week — the pre-migration freeze, the verified copy, the permissions remap, the cutover announcement, and the old-system read-only afterlife. Use when asked we're moving from Dropbox to Drive, migrate our files to SharePoint, plan the file migration day, or how do we switch platforms safely. Produces the migration runbook: freeze window, copy-and-verify steps, permissions mapping, the cutover comms, and the rollback line.4---5
6# Migration Day Runbook Skill
7
8File migrations fail at the edges, not the middle: work edited during the copy window (lost or forked), permissions that mapped wrong (the intern sees the comp sheet; Legal sees nothing), links across the company now pointing at a dead platform, and an old system left writable so half the team never leaves. The runbook handles the edges: a short announced freeze, copy *with verification* (counts and spot-checks, not vibes), a permissions remap done as its own workstream, cutover comms with the three answers everyone needs, and the old platform flipped read-only — the single move that makes migrations stick.
9
10## What This Skill Produces
11
12- **The runbook** — phased: prepare → freeze → copy → verify → permissions → cutover → afterlife, each with owner and duration
13- **The verification plan** — counts by folder, spot-restores, and the biggest-risk samples checked by hand
14- **The permissions remap** — old-model groups/shares → new-model equivalents, with the deny-by-default posture for mismatches
15- **The comms set** — the advance notice, the freeze reminder, and the cutover announcement with its three answers
16
17## Required Inputs
18
19Ask for these if not provided:
20- **From → to, and the size** — platforms, volume (GB and file count), and any known exotica (huge files, weird formats, apps writing into the old drive)
21- **The sharing surface** — external shares, published links, and integrations pointing at the old platform; each is a breakage waiting for its line in the runbook
22- **The freeze tolerance** — can the team stop editing for a day? A weekend? Never (then the delta-sync approach, stated)?
23- **The permission model gap** — how sharing works old vs. new; the remap is where migrations quietly leak confidential files
24
25## Framework: The Edge Rules
26
271. **Freeze short, announce twice:** the copy happens inside a declared no-edits window (evening/weekend for most teams) — announced a week out and the day before. Edits during the copy are the classic loss; the freeze is cheaper than the fork-hunt.
282. **Verify by count and by sample:** post-copy: file counts per top-level folder old-vs-new, total size within tolerance, and hand-checks of the highest-stakes folders (Legal, Finance, the current projects). A migration is "done" when verification says so, not when the progress bar does.
293. **Permissions are a workstream, not a checkbox:** inventory the old platform's shares (especially external ones), map to the new model, and where the models don't align, **fail closed** — over-restricting gets a complaint ticket; over-sharing gets an incident. External shares get re-issued deliberately, not bulk-recreated.
304. **The cutover announcement answers exactly three questions:** where do I go now (the link) · what happened to my stuff (same structure, here's the map) · what do I do if something's missing (the named person, the SLA). Everything else is noise; these three prevent the help-desk flood.
315. **The old platform goes read-only, immediately:** the afterlife rule — readable for the transition period (comfort + the missing-file safety net), writable never (or half the team quietly stays). A read-only banner pointing at the new home does more for adoption than any training session. Decommission date set now, calendar-reminded, executed after the retention check ([document-retention-map](../document-retention-map/SKILL.md)).
32
33## Output Format
34
35# Migration Runbook: [old] → [new], [date]
36
37## Phases
38| Phase | When | Owner | Duration |
39|---|---|---|---|
40[Prepare (inventory, permissions map, comms 1) · Freeze · Copy · Verify · Permissions · Cutover (comms 3) · Afterlife (read-only flip)]
41
42## Verification Plan
43[Counts per top folder · size tolerance · the hand-check list (highest-stakes folders) · the pass/fail line]
44
45## Permissions Remap
46[Old shares inventory → new equivalents · fail-closed mismatches · external shares re-issued deliberately]
47
48## Comms
49[T-7 notice · T-1 freeze reminder · cutover announcement: the three answers + the missing-file contact]
50
51## Rollback Line
52[The condition that aborts (verification fails, permissions can't map) · rollback = unfreeze the old, reschedule — cheap because the old is untouched until read-only]
53
54## Quality Checks
55
56- [ ] The copy happens inside an announced freeze
57- [ ] Verification is counts + samples with a pass/fail line, before cutover comms
58- [ ] Permission mismatches fail closed, external shares handled by hand
59- [ ] The announcement answers exactly the three questions with a named missing-file contact
60- [ ] The old platform is read-only from cutover, with a decommission date set
61
62## Anti-Patterns
63
64- [ ] Do not copy a live drive — the freeze is one evening; the fork-hunt is one month
65- [ ] Do not trust the progress bar as verification — counts and samples or it didn't happen
66- [ ] Do not bulk-recreate external shares — each one re-issued is each one re-decided
67- [ ] Do not leave the old platform writable "during transition" — that's two sources of truth, i.e., zero
68- [ ] Do not skip the rollback line — a migration that can't abort will be pushed through broken
Mohit Aggarwal