## TL;DR
The agent ran migrations selectively and skipped one, so later revisions applied against a schema missing the skipped work. Diff the state table against the migration files to name the skipped revision, check whether its effects already exist (later migrations may have created them), then apply it, reconcile by hand, or stamp past it when the schema already matches. Verify the full chain on a scratch database afterwards.

## The query

```text
agent applied migrations out of order - it skipped a revision and now the schema is inconsistent
```

## Use this when

- An agent skipped a revision and the schema is inconsistent
- Migrations applied out of order
- The state table and the file chain disagree on what ran
- A later migration failed because an earlier one never applied

## Not for

- Branching heads (merge them, a different fix)
- A revision file that is missing (restore it first)
- Intentional out-of-order applies with a tool that supports them (use the tool's ordering flags)

## Steps

### 1. Name the skipped revision

```sql
SELECT version_num FROM alembic_version;
```

Then list the file chain:

```bash
alembic history
```

Walk the chain from the recorded version: the first file revision not reflected in the state table (and not an ancestor of it) is the skipped one. Expected output: the exact revision id that was skipped.

### 2. Check whether the skipped work already exists

Read the skipped revision's upgrade function and check each of its effects against the live schema: do the tables, columns, or indexes already exist (perhaps created by a later migration that assumed them)?

Expected output: one of three answers: nothing exists (clean apply possible), everything exists (schema already matches, stamp past it), or partially exists (hand reconciliation needed).

### 3. Case A: nothing exists - apply the skipped revision

Bring the database to the skipped revision's parent if needed, then upgrade through it. With alembic, the safest path is often to run the single revision's upgrade on a controlled basis and let the chain continue:

```bash
alembic upgrade [skipped revision]
```

Expected output: the revision applies cleanly because its prerequisites (its own parent chain) are satisfied. Then upgrade head for the rest.

### 4. Case B: everything exists - stamp past it

When the schema already matches the post-revision state (a later migration did the work), mark it applied without running it:

```bash
alembic stamp [skipped revision]
```

Expected output: the state table advances past the revision with no SQL run. Only do this when you have verified every effect exists: stamping over missing work creates a silently incomplete schema.

### 5. Case C: partially exists - reconcile by hand, then stamp or apply

Apply the missing pieces manually (the statements whose effects are absent), then stamp the revision so the chain continues. Expected output: the schema fully matches the post-revision state by inspection, and the state table reflects it.

### 6. Prove the chain on a scratch database

On a fresh database, run the full upgrade from zero through head. Expected output: it completes with no errors, proving the file chain itself is sound and the incident was purely about the skipped apply, not broken files.

## Tool compatibility

Written for alembic; the pattern (diff state vs files, apply/reconcile/stamp) maps directly to flyway (repair/baseline), django (migrate/fake), and rails (version targeting).

## Variant phrasings

### agent skipped a migration revision out of order

Steps 1 and 2: name the skipped revision and check what of its work exists.

### migrations applied out of order how to fix

Steps 3 through 5: apply, stamp, or hand-reconcile depending on what the schema already contains.

### alembic stamp skipped revision

Step 4: stamp only when every effect of the revision is verifiably present.

## Why it happens

Migration tools assume linear application: each revision's upgrade is written against the schema its parent produced. Skipping a revision applies later work to the wrong base schema, and the failure (or silent inconsistency) surfaces far from the cause. The state table is the only reliable record of what actually ran, which is why the fix starts there, not with the agent's memory of what it did.

## Edge cases

- A skipped revision whose parent is also skipped compounds: walk the whole chain from the recorded version, not just one step.
- Stamping is the most dangerous step here: a wrong stamp is invisible until something queries the missing schema. Verify effects individually.
- Teach the agent to never apply revisions selectively: the unit of migration is the chain from the current version to head, always.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_IU3IfFp6Nxq0hY-r6VIXtg