renumber-migration git:20261013.4e5c041B

Immutable. This exact content never changes and is served at /api/v1/blob/3293b1755d37e22c.

---
description: "STUB — not yet hydrated for this project. Resolve a sequential migration-number collision after another branch landed migrations first: adopt theirs, renumber yours on top, re-parent any snapshot. Hydrate this file against the project's migration tool before invoking it."
---

> ⚠️ **STUB.** This skill has no working procedure yet. Before it can be invoked, fill in: the migration tool, the file naming scheme, whatever journal/snapshot/checksum files accompany a migration, and the commands to regenerate them. Delete this banner once you have. If the project's migrations are not sequentially numbered, delete the skill instead.

## What this skill is for

Fixing the collision that happens whenever two branches each add migration `0042` and one of them lands first. It's mechanical, it's easy to get subtly wrong, and getting it wrong corrupts the migration history rather than failing loudly.

## Concerns that hold regardless of stack

Each is something a hydrated version must handle.

### Sequential numbers collide by construction

Any scheme where the next migration is "highest + 1" collides across concurrent branches. This isn't an edge case; it's the normal cost of readable ordering. The skill exists because the collision is routine.

### Detect the fork first

Find the point where this branch's migrations diverged from the base's, and which numbers the base has since claimed. Everything downstream depends on getting this boundary right.

### Adopt theirs, then renumber yours on top

Take the base's migrations at their existing numbers — they've already run somewhere — and renumber this branch's on top of them so the sequence stays contiguous. Never renumber the ones that landed first.

### Never renumber a migration that has already run

The hard rule. If a migration has been applied in *any* environment, its identity is recorded there. Renumbering it makes the recorded history and the repository disagree, and the failure surfaces later, somewhere else, as a migration that mysteriously re-runs or is mysteriously skipped.

### Re-parent the accompanying files

Most migration tools keep more than the SQL: a journal, a schema snapshot, a checksum, a "previous migration" pointer. Renumbering the file and leaving those stale is the most common way this goes wrong. Name every such file in the hydrated version and say how each is regenerated.

### Verify by replaying

After renumbering, run the migrations from scratch against an empty database and confirm the resulting schema matches the snapshot. That replay is the only real proof the sequence is coherent.

## Related

This is usually reached from `/finalize` Step 2, where merging the base branch is what surfaces the collision in the first place.