Diagnose and Repair Drizzle Migration Conflicts

This skill helps diagnose, repair, and prevent Drizzle Kit migration conflicts in a multi-developer repository, recognizing that Drizzle migrations encode both SQL and migration snapshots so the safe fix depends on the current migration directory shape, the Drizzle Kit version, and the git state. It classifies every request into one of four modes - Diagnose, Repair, CI hardening, or Explain - defaulting to Diagnose when the mode isn't explicit, and each mode unlocks a strictly bounded set of actions: Diagnose is read-only, running git status, git ls-files -u, and a helper script without executing drizzle-kit check or any write command; Repair adds file writes and drizzle-kit generate or check execution gated by explicit confirmation of exactly which files and which side, ours or theirs, to change; CI hardening adds proposing or editing workflow files without running migration commands against the user's database; Explain stays conceptual with only optional read-only inspection.

Repository discovery runs a fixed sequence of git and ripgrep commands to collect facts, then inspects drizzle.config for output directory and dialect, package.json scripts for the project-approved generate/check/migrate commands, and dependency versions for drizzle-kit and drizzle-orm, before resolving and running a bundled read-only helper script (checked against a repo-vendored copy, the Claude Code skills directory, or another reported install location) that never connects to a database or writes files. It then identifies whether the repo uses the legacy structure (a shared journal and snapshot files plus root-level numbered SQL files) or the newer folder-based structure (each migration as its own directory with migration.sql and snapshot.json), stopping to report ambiguity rather than guessing at a destructive repair if the structure is unknown or mixed.

Repair principles require resolving schema source conflicts first so the regenerated migration reflects the merged schema rather than one side's stale snapshot, treating the parent or target branch's migration history as the source of truth, preferring to discard and regenerate migration artifacts over hand-editing journal or snapshot files, and validating in tiers - structural checks first, then drizzle-kit check only after confirming its config cannot point at production, then project tests only after inspecting scripts and database targets. Hard safety rules forbid running drizzle-kit migrate, push, or seed scripts against a live database without explicit request and a clear target, forbid deleting migration files or running git checkout/restore without confirmed files and side, forbid recommending drizzle-kit push as a production fix since it skips auditable migration history, and forbid echoing secrets from config or environment files. Diagnostic reports use one of four fixed conclusion values: NO_CONFLICT_FOUND, SAFE_TO_REGENERATE, NEEDS_USER_CONFIRMATION, or BLOCKED_BY_AMBIGUITY.

Use it when Drizzle migration files, a journal file, or a snapshot file conflict after a pull, merge, or rebase, when drizzle-kit check reports non-commutative migrations, or when designing CI or merge-queue policy to prevent repeated conflicts. Do not use it to run database-backed migration commands without explicit user confirmation of the target, or for general schema design or query optimization beyond migration conflicts.

Given a repository with a Drizzle migration conflict, it produces a detected migration structure and mode, a diagnostic report with one of four fixed conclusion values, and a safe repair or CI-hardening path with destructive steps explicitly labeled as requiring confirmation.

Drizzle Kit and Drizzle ORM, git, ripgrep, and a bundled Python helper script (check_drizzle_migrations.py) that reads migration directories without ever connecting to a database or writing files; references official Drizzle docs, GitHub discussions, and community scripts with trust levels noted per source.

Teams running Drizzle Kit migrations across multiple developers who need a safe, confirmation-gated repair flow after a merge conflict, plus a path to hardening CI so the conflict doesn't recur.