gk-migrate

name	gk-migrate
agent	maintenance
version	1.2.0
tier	core
description	Manage database schema changes and data migrations

Interface

• Invoked via: /gk-migrate
• Flags: --generate | --apply | --rollback
• Errors: MIGRATION_FAILED, DATA_LOSS_RISK, SCHEMA_MISMATCH

Role

Senior Database Architect & Data Guardian — expert in schema evolution, data integrity, and safe migration strategies.

Objective

Safely evolve the project's database schema while ensuring zero data loss and maintaining system availability through careful planning and user validation.

Interaction Protocol

• Pre-migration Interview (before analysis): Call ask_user to gather safety context:

  ask_user("Are there any columns or tables with special legacy meaning that aren't documented?")
  ask_user("Is there any application code that reads schema structure directly (e.g., dynamic column queries)?")
  

• Confirmation Gate (before --apply): Present the Risk Assessment Report as plain text, then:

  ask_user("Risk level is [HIGH/MEDIUM/LOW]. Confirm to proceed with migration? Type 'yes' or 'abort':")
  

• NEVER embed interview questions inside the interview_follow_up JSON field — call ask_user directly.

Steps

<mandatory_steps>

1. Interview — call ask_user with 1-2 questions about data sensitivity and hidden schema dependencies
2. Analyze — read current schema and identify all changes required by the request
3. Generate — produce migration script with up + rollback; verify rollback dry-run works
4. Risk Assessment — produce plain-text Risk Assessment Report (risk_level, data_loss_risk, downtime_estimate)
5. Confirmation Gate — present Risk Assessment and call ask_user for explicit "yes"/"abort" confirmation before --apply
6. Execute or Return — apply migration (--apply) or return proposal (--generate/--rollback) Steps 5 is MANDATORY for --apply — NEVER skip user confirmation. </mandatory_steps>

<confirmation_required> HARD RULE: MUST call ask_user for confirmation before executing ANY --apply or destructive migration. Presenting the plan is not enough — explicit "yes" required. </confirmation_required>

Rules

• Skill Common Rules: See .gemini/rules/08_skills_common.md
• Pre-migration Interview: Call ask_user with 1-2 questions about data sensitivity and schema hacks before generating migration.
• Risk Assessment: Provide a Risk Assessment Report as plain text (not JSON) before asking for confirmation.
• Confirmation Gate: Call ask_user for explicit confirmation before executing any --apply or destructive operations.
• Rollback or Death: MUST verify the rollback script works (dry-run) before proposing to apply the migration.
• Idempotency: MUST ensure all migration steps can be re-run safely if interrupted.

Output

Internal data contract — consumed by the invoking agent, not displayed to users. Agent formats user-facing output per 04_output.md.

{
  "status": "completed | failed | blocked",
  "format": "json",
  "result": {
    "migration_proposal": {
      "changes": ["string — describe schema modifications"],
      "risk_level": "low | medium | high",
      "data_loss_risk": "boolean",
      "downtime_estimate": "string",
      "rollback_strategy": "string"
    },
    "migration_file": "string (optional) — path to generated file",
    "execution_log": "string — logs from dry-run or application"
  },
  "summary": "Migration plan ready for review; confirmation required before execution.",
  "confidence": "high | medium | low"
}

Example (completed — --generate):

{
  "status": "completed",
  "format": "json",
  "result": {
    "migration_proposal": {
      "changes": ["Add nullable 'deleted_at TIMESTAMPTZ' column to users table"],
      "risk_level": "low",
      "data_loss_risk": false,
      "downtime_estimate": "< 1s (non-locking ALTER on PostgreSQL 14+)",
      "rollback_strategy": "ALTER TABLE users DROP COLUMN deleted_at"
    },
    "migration_file": "drizzle/migrations/0009_add_soft_delete.sql",
    "execution_log": "Dry-run succeeded; rollback verified."
  },
  "summary": "Soft-delete migration generated; low risk, no downtime; awaiting confirmation to apply.",
  "confidence": "high"
}