agent applied half the migration plan, the context window filled, and the new instance has no idea which steps finished
Fixes an agent that lost migration progress between sessions. Use when a new agent instance inherits a half-run migration plan and needs to know which steps finished. Key trigger: the database's migration state table (alembic_version, flyway_schema_history, _prisma_migrations) replaces the agent's memory as ground truth.
TL;DR: Stop trusting the agent's memory and query the database instead. Every migration tool records what it applied in a state table - alembicversion, flywayschemahistory, djangomigrations, prismamigrations, or schema_migrations. Diff that table against the migration files on disk, re-run only the pending ones, and make each future step write its result to a durable run log the next instance reads first.
The problem as reported:
agent applied half the migration plan, the context window filled, and the new instance has no idea which steps finished- Identify the tool from the migrations directory (alembic/versions, prisma/migrations, db/migrate, or a migrations folder).
- Ask the tool what it already applied - pick the matching command:
- alembic:
alembic current- Expected: prints the current revision id. - flyway:
flyway info- Expected: a table showing each migration as Success or Pending. - prisma:
npx prisma migrate status- Expected: lists applied migrations and any pending ones. - django:
python manage.py showmigrations- Expected: applied migrations marked [X]. - rails:
rails db:migrate:status- Expected: each migration marked up or down.
- List the migration files on disk and compare: pending = files with no matching row in the applied set. Expected: a concrete short list, e.g. "migrations 9 through 15 of 15".
- Re-run the migrate command. Expected: only the pending migrations run, in order, and the tool reports the database up to date afterward.
- Make the next handoff lossless: after every migration step, append one line ("step N applied ok") to a run log stored in the repo or a durable artifact, and make the agent read that file before doing anything else. Expected: a fresh instance reconstructs state from the log plus the state table without guessing.
Use this when
- An agent session restarted or the context window filled mid-migration.
- A new agent instance inherits a half-finished migration plan.
- You need ground truth on which migrations applied.
Not for this skill when
- Migrations are hand-run SQL scripts with no state table - then there is no ground truth to query and you need manual bookkeeping.
- You suspect a single migration half-applied inside its own transaction - check that tool's transaction semantics first.
Variant phrasings
- which migrations already ran after agent restart
- migration agent lost track of applied revisions
- resume migration after context window filled
- new agent instance doesn't know migration state
Why it happens
Progress lived only in the agent's conversation context, which doesn't survive a restart. The database, on the other hand, records every applied migration durably - the tool wrote it there precisely so runs can be resumed.
Edge cases
- A failed migration left a row marked failed (prisma) or no row at all (flyway) - the pending set needs a repair step before re-running.
- Multiple databases or schemas each have their own state table - query the right one.
- Someone edited a migration file after it applied - the next run fails checksum validation; that change is a new migration, not an edit.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_TvuznOepmar4QYuFm1Jgtw
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.