Agent skill · software engineering · caffeinelabs
troubleshooting-motoko-migrations
Deep reference for when the migration chain misbehaves — upgrade compatibility errors you cannot explain, migration files you cannot write, a project converted from legacy persistence, or a request to remove the chain. Load only when the rules in migrating-motoko-actors do not explain what you are seeing.
Why this skill is useful
Provides specific troubleshooting patterns and diagnostic insights for Motoko migration issues that the AI wouldn't reliably generate on its own.
What it needs
About 8k tokens when loaded. Last updated 2026-08-06.
What this skill does
Troubleshooting Motoko Migrations Reference for the failure modes of the mops-managed migration chain (migrations/). Do not load this for routine work. Writing a migration, deciding implicit vs explicit, or naming a new file is covered by migrating-motoko-actors — that skill's rules are sufficient for the normal path. Come here when: a compatibility or migration diagnostic does not match what you see in main.mo a write to a migration file fails, or you are tempted to rename/delete one the first file in the chain has a non-empty OldActor and you are unsure whether that is a bug the task asks you to remove migrations, restore inline initializers, or go back to (with migration = ...) mops check complains about a state shape that is not in the current source How the runtime decides what to run The whole chain is compiled into the backend wasm. There are no separate migration artifacts — changing any migration file changes the wasm. Applied migrations are tracked by module name (the filename without .mo) in the canister's persistent metadata. On upgrade, the runtime replays only the migrations that module name says have not been applied yet. Deploying onto a canister several versions behind replays all the missing steps in one upgrade — you never need intermediate deploys to "catch up". On fresh install, every file in the chain replays in lexicographic order. Every migration ever added runs on every fresh install of the project, forever. Two consequences drive most of the rules in this skill: Renaming a migration changes its identity. The runtime would treat the renamed file as never applied and replay it against state that no longer matches — or skip the work the old name recorded. Filenames are permanent. Editing an applied migration is invisible to a canister that already ran it. The runtime skips it by name, so an edited body never executes. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills caffeinelabs/troubleshooting-motoko-migrations