Migration Hygiene

Migration Hygiene Skill

When To Use

• Any change under supabase/migrations
• Any Supabase MCP migration apply/reconcile work
• Any migration history drift investigation

Required Workflow

1. Treat supabase/migrations as append-only and immutable once applied.
2. Never edit an already-applied migration file in place.
3. If behavior changes after apply, create a new follow-up migration file.
4. Migration filenames must be versioned and match Supabase history format:
   • <version>_<name>.sql
   • Example: 20260224155131_po_split_allocation_overalloc_guard.sql
5. Do not add non-versioned helper/ledger files under supabase/migrations.
6. Put explanatory context in docs (docs/operations/migration-status.md), not extra migration files.

Apply + Verify Checklist