| name | dte-migrate |
| description | Plan and execute a safe upgrade or migration — a Rails version bump, gem upgrades, or a schema/data migration — incrementally, reversibly, gated at every step. Composes gemfile-upgrade + gemfile-organize (dependency moves), database-admin + database-optimizer (schema/data), gem-research (is an upgrade safe/maintained), ce-plan/ce-work, and the project gate after each step. Use when the user says "upgrade Rails/this gem", "bump dependencies", "migrate the schema/data", "backfill this column", "zero-downtime migration", or "update our dependencies". Loops over a list of upgrades. Not for an architecture/structure migration (use dte-arc-work from a dte-arc-auditor roadmap) or a code bug (use dte-debug). |
dte-migrate — safe, incremental, reversible upgrades & data migrations
Read ../../references/conventions.md first (Planning is mandatory and validated, Runnable gate,
Progress: report every phase). This skill changes dependencies, schema, or data — the riskiest,
hardest-to-reverse work. So: one change per step, the gate green before each commit, reversible by design.
It composes the upgrade/DB tools; it does not free-hand a mass version bump.
Input
- A migration: a Rails/Ruby version bump, a set of gem upgrades, or a schema/data migration (add/rename
column, backfill, change type, move data).
- Or a list → handle each (serial by default — dependency/schema changes are not independent).
- Read the project
CLAUDE.md/AGENTS.md; note the DB, deploy model, and whether deploys are test-gated.
Establish the gate FIRST
Confirm the runnable gate (full test suite + boot/zeitwerk:check; for DB work add a migrate↔rollback
round-trip and a seed/load check) is green on the current tree before touching anything. It runs before
every commit; a red gate after a step = revert that step, never push through.
Procedure (per migration)
- Research safety first. For an upgrade, run
gem-research — is the target version maintained,
what breaks, what's the changelog/deprecation path? For a Rails bump, identify the upgrade guide steps.
Don't bump blind.
- Plan it (validated). Run
dte-arc-plan / ce-plan → a validated, stepwise plan: smallest
reversible increments (one major gem at a time; dual-write/backfill/verify/cutover for data; deprecation
warnings cleared before the bump). Every step has its own rollback.
- Execute step by step via
ce-work:
- Deps:
gemfile-upgrade for the bump, gemfile-organize to keep the Gemfile clean;
bundle update <gem> one at a time, run the gate, fix deprecations.
- Schema/data:
database-admin for the migration (reversible up/down, safe for large tables —
add column nullable → backfill in batches → add constraint), database-optimizer to check the new
index/query shape. Keep migrations idempotent and reversible.
- Gate after EVERY step. Run the gate (incl. migrate→rollback→migrate round-trip for DB steps). Green →
commit + report the step. Red → revert the step, log why, stop.
- Report + pause per step — what changed, gate result, what's next, the rollback if it goes wrong.
For a list of migrations
Serial; or hand the stepwise plan/INDEX to dte-loop to run gated + autonomous. One branch per
migration unless coupled. Report + pause per step.
Degrade gracefully
- No
gemfile-upgrade/gemfile-organize → bump with bundle update <gem> + manual Gemfile edits, noted.
- No
database-admin/database-optimizer → hand-write reversible migrations + EXPLAIN by hand, noted.
- No
gem-research → check the changelog/release notes manually; never bump blind regardless.
Guardrails
- Reversible or it doesn't ship. No data migration without a tested rollback / backfill-verify.
- Stop-and-ask before anything irreversible (a destructive
down, dropping a column, prod data change)
unless explicitly authorized. Never run a big bump as one commit.
Done when
The migration is done in small reversible steps, each gate-green (incl. rollback round-trip for DB),
deprecations cleared, dependencies clean, with a step-by-step report and the rollback path documented.
