id: schema-migration
name: Database Schema Migration
tags: [data, safety, code-review, pr-time]
audience: dev
summary: Fires when a migration file is added or modified. Demands dry-run against a prod-shaped sandbox, data-loss static analysis, and an index-size review.
description: |
  Fires when a migration file is added or modified. Migrations are the
  hardest change to roll back in production, so they get the most gates:
  dry-run against a production-shaped sandbox, static analysis for data
  loss (DROP COLUMN, type narrowing), and an index-size review.

triggered_by:
  - file_change: "**/migrations/**"
  - file_change: "**/*.migration.ts"
  - file_change: "**/*.migration.sql"

risk:
  score: 9
  blast_radius: high
  reason: "Schema changes are difficult to roll back in production without coordinated data migration. A bad migration corrupts state across all consumers."

required_agents:
  - database
  - backend-developer
  - devops-infra
  - code-reviewer

required_gates:
  - id: migration_dry_run
    description: "Run the migration against the sandbox stack; verify the rollback path also executes cleanly"
  - id: data_loss_check
    description: "Static analysis for DROP COLUMN, DROP TABLE, narrowing type changes, and DELETE without WHERE"
  - id: index_review
    description: "Verify new indexes are justified by query patterns and sized appropriately for production data volume"

auto_workflows:
  - on: "migration.added == true"
    action: "open-issue-in-devops-repo-with-deploy-notes"
  - on: "data_loss_detected == true"
    action: "require-explicit-data-migration-plan-in-pr-body"

human_approval_required:
  - condition: "data_loss_detected"
  - condition: "production_target == true"