migration-and-schema-harness

Manage database, schema, and API evolution safely. Use when a repo has migrations, database schemas, public API schemas, seed data, fixtures, compatibility requirements, rollback conventions, or needs

SKILL.md

GitHub

Migration And Schema Harness

Purpose

Make schema changes reversible, validated, and compatible with tests, fixtures, and release plans.

Inspect First

  • database config, migrations, schema files, API schemas, seed data, fixtures, ORM config, migration scripts, release docs, and CI

Procedure

  1. Identify schema ownership.

    • Database tables, API contracts, event schemas, generated clients, and fixtures.
  2. Define migration rules.

    • Forward migration expectations.
    • Rollback or mitigation expectations.
    • Backward compatibility requirements.
    • Seed and fixture update rules.
  3. Add checks.

    • Create target repo scripts/check-migrations.
    • Use scripts/check_migrations.py for lightweight inventory.
    • Keep dependency, build, and generated directories excluded by default; use --include-ignored only to debug scanner behavior.
    • Include migration checks in scripts/validate when relevant.
  4. Document.

    • docs/development/migrations.md
    • Link release rollback notes when migrations affect deployment.

Validation

  • Run migration validation commands when safe.
  • Confirm fixtures and seeds match schema changes.
  • Confirm rollback or mitigation notes exist.

Completion Criteria

  • Agents know how to change schemas without breaking compatibility or release safety.