@mrciphersmith/keryx 0.3.2 → 0.3.3

package/src/gdskills/bundled/stacks/sql-db/governance/scout.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "Use when writing SQL schema, migrations, or queries for Postgres/MySQL -- safe zero-downtime schema changes (adding NOT NULL, backfills), indexing (composite column order, covering/partial indexes), transaction discipline, and parameterized query design.",
+    "decision": "create",
+    "topMatch": "sql-db/sql-db-testing",
+    "recordedAt": "2026-09-25T15:30:40.157Z",
+    "skillName": "sql-db-implementation"
+  },
+  {
+    "query": "Use when writing or fixing tests for SQL migrations and queries -- transactional test wrapping with rollback, fixture/seed data design, testing a migration's up/down path on representative row counts, and asserting on actual query results and query counts rather than just 'no error'.",
+    "decision": "create",
+    "topMatch": "quality/fresh-eyes",
+    "recordedAt": "2026-09-25T15:30:44.924Z",
+    "skillName": "sql-db-testing"
+  },
+  {
+    "query": "Use when reviewing a migration or query diff for SQL/database-specific risk -- injection (string-built SQL, ORM raw-SQL escape hatches), missing/misordered indexes, an unsafe blocking NOT NULL or index-creation statement, N+1 query shape, and transactions left open across a slow call. Read-only, no edits.",
+    "decision": "create",
+    "topMatch": "php-laravel/php-laravel-code-review",
+    "recordedAt": "2026-09-25T15:30:47.232Z",
+    "skillName": "sql-db-code-review"
+  },
+  {
+    "query": "Use when a migration fails to apply, a query planner regresses to a full table scan, or a constraint violation blocks a deploy -- resolves failed/broken migrations, missing-index query regressions, deadlocks, and NOT NULL/unique/foreign-key constraint violations with the smallest root-cause fix.",
+    "decision": "create",
+    "topMatch": "sql-db/sql-db-implementation",
+    "recordedAt": "2026-09-25T15:30:49.254Z",
+    "skillName": "sql-db-build-fix"
+  }
+]

package/src/gdskills/bundled/stacks/sql-db/pack.json

@@ -0,0 +1,40 @@
+{
+  "id": "sql-db",
+  "family": "capability",
+  "modules": ["sql-db-rules", "sql-db-skills"],
+  "detectionMarkers": ["sql"],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 337, Wave 4 batch 5"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["sql-db-implementation"],
+    "test": ["sql-db-testing"],
+    "review": ["sql-db-code-review"],
+    "build-fix": ["sql-db-build-fix"],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "SQL / Database",
+    "auditFocus": [
+      "a query built with string concatenation or f-string/template interpolation of a user-influenced value instead of a parameterized placeholder or prepared statement, including inside an ORM's raw-SQL/raw-query escape hatch",
+      "an ADD COLUMN ... NOT NULL with no default, or a SET NOT NULL with no prior NOT VALID CHECK + VALIDATE CONSTRAINT step, on a table that can have existing rows",
+      "a WHERE/JOIN/ORDER BY column with no supporting index, or a composite index whose column order does not match the query's actual equality-then-range filter shape",
+      "a loop that issues one query per row (a classic N+1) where a JOIN, an IN-clause batch, or eager loading would do it in one round trip",
+      "a migration with no reverse/down operation, or one that is not safe to run twice (missing IF EXISTS/IF NOT EXISTS on a DDL statement that isn't naturally idempotent)",
+      "a transaction held open across a slow external call (an HTTP request, a queue publish, a sleep) instead of being committed before or reopened after it"
+    ],
+    "buildCommands": [
+      "EXPLAIN (ANALYZE, BUFFERS) <query>  -- Postgres: confirm no unexpected sequential scan on the touched tables",
+      "EXPLAIN ANALYZE <query>  -- MySQL: confirm the query uses the intended index",
+      "the project's own migration runner in dry-run/plan mode when one exists, before applying against a real database"
+    ],
+    "fixGuardrails": [
+      "Never fix a slow query by adding an index without checking its column order against the query's actual WHERE/JOIN/ORDER BY shape first.",
+      "Never rewrite a parameterized query into a string-concatenated one to work around a driver quirk; fix the parameter binding instead.",
+      "Never resolve a migration failure by dropping the failing constraint or making a NOT NULL column nullable again without saying so explicitly in the report.",
+      "Never skip or delete a migration step to reach a green migration run."
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/sql-db/rules/coding-style.mdc

@@ -0,0 +1,69 @@
+---
+extends: common
+paths: ["**/*.sql"]
+metadata:
+  origin: authored
+---
+
+# SQL coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to raw `.sql` files
+(schema definitions, migrations, hand-written query files) across Postgres,
+MySQL, and generic SQL engines. Applies only to `*.sql` files — application
+code that embeds SQL as strings (a Python/Go/JS query builder call) is
+covered by that language's own stack pack, not this one.
+
+## Naming
+
+- Tables and columns are `snake_case`, plural for tables (`orders`,
+  `order_items`), singular for columns (`user_id`, not `user_ids` on a
+  scalar foreign key) — match whatever convention the project's existing
+  schema already uses instead of introducing a second one.
+- Name a foreign-key column `<singular_referenced_table>_id`
+  (`orders.user_id` referencing `users.id`), so its relationship is
+  readable without opening the schema.
+- Name an index `idx_<table>_<column(s)>` and a unique constraint
+  `uq_<table>_<column(s)>`; name a foreign key constraint
+  `fk_<table>_<referenced_table>` — explicit names are required so a
+  failing constraint's error message names something a reader recognizes,
+  instead of an engine-generated identifier like `orders_user_id_fkey1`.
+
+## Formatting
+
+- One clause per line for anything beyond a trivial single-table query —
+  `SELECT`, `FROM`, `WHERE`, `GROUP BY`, `ORDER BY` each start their own
+  line, with join conditions immediately under their `JOIN`. A query dense
+  enough to need review is dense enough to need this shape.
+- Keywords uppercase (`SELECT`, `FROM`, `WHERE`, `JOIN`), identifiers
+  lowercase — do not mix case within one file's own convention.
+- Explicit `JOIN ... ON` conditions, never an implicit comma join
+  (`FROM a, b WHERE a.id = b.a_id`) — the join type and its condition
+  belong together, not split across `FROM` and `WHERE`.
+- Every migration file's DDL statements are wrapped in the smallest
+  transaction the engine allows (Postgres: a single implicit transaction
+  per migration is usually safe except around `CREATE INDEX CONCURRENTLY`,
+  which cannot run inside a transaction block at all — split it into its
+  own migration step rather than wrapping it anyway).
+
+## Column and type choices
+
+- Pick the narrowest correct type: an `enum`/`CHECK`-constrained text
+  column over a free `VARCHAR` for a closed set of values, `TIMESTAMPTZ`
+  (Postgres) / a UTC-normalized `DATETIME` (MySQL) over a naive local-time
+  column, `NUMERIC`/`DECIMAL` for money — never `FLOAT`/`DOUBLE` for a
+  value that must round exactly.
+- A nullable column means "this can genuinely be absent," not "I didn't
+  decide yet" — a column with no legitimate absent case gets `NOT NULL`
+  from the migration that introduces it (with a default, or through the
+  safe multi-step pattern in `rules/patterns.mdc` when the table already
+  has rows).
+
+## Comments and documentation
+
+- A non-obvious index (a partial index's predicate, a composite index
+  whose column order looks surprising) gets a one-line comment stating
+  which query it serves — an index with no stated purpose is a maintenance
+  liability the next person can't safely drop or reorder.
+- A migration that is not naturally reversible (a data-destructive
+  backfill, a column drop) states its rollback plan or its "no rollback,
+  here is why" reasoning in a comment at the top of the file.

package/src/gdskills/bundled/stacks/sql-db/rules/patterns.mdc

@@ -0,0 +1,134 @@
+---
+extends: common
+paths: ["**/*.sql"]
+metadata:
+  origin: authored
+---
+
+# SQL patterns
+
+Narrows `core-common-rules`' stack-agnostic design guidance to migration
+safety, query design, and indexing for `.sql` files across Postgres,
+MySQL, and generic SQL engines. Extends the general N+1/index/migration
+guidance in the core `database-patterns.mdc` rule with engine-specific
+mechanics for the zero-downtime cases that rule states only as a general
+three-step pattern. Applies only to `*.sql` files.
+
+## Zero-downtime schema changes
+
+- **Adding a nullable column** is always safe as a single migration on
+  both engines.
+- **Adding a `NOT NULL` column with a constant default** does not require
+  a full table rewrite on modern Postgres (11+) or MySQL (8.0+, via
+  `ALGORITHM=INSTANT` for an appended column) — prefer `ADD COLUMN ...
+  NOT NULL DEFAULT <constant>` directly over the older three-step
+  add-nullable/backfill/constrain dance when every existing and new row
+  can share the same default value.
+- **Adding `NOT NULL` to an existing column that needs a real backfill**
+  (not a constant default) still needs the multi-step sequence: add the
+  column nullable, deploy code that writes it on every insert/update,
+  backfill existing rows in batches (not one giant `UPDATE`, which holds
+  locks and generates a huge amount of WAL/binlog), then constrain.
+  - Postgres: prefer `ALTER TABLE t ADD CONSTRAINT t_col_not_null CHECK
+    (col IS NOT NULL) NOT VALID;` followed by a separate `ALTER TABLE t
+    VALIDATE CONSTRAINT t_col_not_null;` over a direct `ALTER TABLE t
+    ALTER COLUMN col SET NOT NULL` — `NOT VALID` skips the initial
+    table scan (applies only to new rows immediately), and
+    `VALIDATE CONSTRAINT` then scans under `SHARE UPDATE EXCLUSIVE`,
+    which does not block concurrent reads/writes the way the scan inside
+    a plain `SET NOT NULL` does.
+  - MySQL: `ALTER TABLE t MODIFY COLUMN col <type> NOT NULL` is an
+    in-place operation but still requires a full table scan/rebuild on
+    most storage engines — schedule it like any table-rewriting DDL
+    (off-peak, or through the project's online-migration tool such as
+    `gh-ost`/gantry-style tooling if one is already in use).
+- **Adding an index on an existing table**: Postgres —
+  `CREATE INDEX CONCURRENTLY` (cannot run inside a transaction block; put
+  it in its own migration step) to avoid the `ACCESS EXCLUSIVE`-adjacent
+  write lock a plain `CREATE INDEX` takes. MySQL — `CREATE INDEX` on
+  InnoDB uses `ALGORITHM=INPLACE` by default for most index additions,
+  which permits concurrent DML; verify with `ALGORITHM=INPLACE, LOCK=NONE`
+  explicitly if the table is under sustained write load.
+- **Renaming or changing a column's type**: no engine makes this safe as
+  one step under a rolling deploy — add the new column, dual-write from
+  application code, backfill, cut reads over, then drop the old column in
+  a later migration once nothing reads it.
+- **Dropping a column or table**: stop reading/writing it from application
+  code first (a full deploy cycle), then drop it in a subsequent
+  migration — dropping while old code still reads the column breaks that
+  code immediately on deploy overlap.
+
+## Indexing
+
+- Index every foreign key column and every column that appears in a
+  `WHERE`, `JOIN ON`, or `ORDER BY` clause on a table large enough that a
+  sequential/full-table scan would be noticeable — confirm with
+  `EXPLAIN ANALYZE` on production-representative data volume, not on an
+  empty dev table where every plan looks fast.
+- **Composite index column order**: put equality-filtered columns before
+  range-filtered ones, and put the columns a query's `WHERE` actually
+  restricts before columns only used for `ORDER BY`. An index on
+  `(status, created_at)` serves `WHERE status = 'open' ORDER BY
+  created_at` efficiently; the same index in the order `(created_at,
+  status)` cannot use the equality filter to narrow the scan first and
+  degrades toward a broader range scan.
+- **Covering indexes**: when a query only ever selects a handful of
+  columns already present in an index's key or `INCLUDE`/covered columns
+  (Postgres `INCLUDE`, or MySQL's implicit covering when all selected
+  columns are in the index), the engine can satisfy it as an index-only
+  scan without touching the table's heap/pages at all — worth adding
+  narrowly for a hot, narrow query, not as a default habit.
+- **An index has a write cost**: every index is maintained on every
+  insert/update/delete touching its columns. Do not add a composite index
+  for every column combination a report might someday filter by; add the
+  ones actual queries use, and periodically check for unused indexes
+  (`pg_stat_user_indexes.idx_scan = 0` on Postgres) before a schema
+  accumulates dead weight.
+- A partial index (`CREATE INDEX ... WHERE <predicate>`, Postgres) is
+  narrower and cheaper to maintain than a full index when a query always
+  filters on a fixed condition (`WHERE deleted_at IS NULL`,
+  `WHERE status = 'active'`) — prefer it over a full index whose non-
+  matching rows the query never touches.
+
+## Query design
+
+- A query issued inside an application-code loop, once per row of an
+  outer result set, is an N+1 — replace it with a single `JOIN`, an
+  `IN (...)` batch, or the ORM's eager-load option before merging. This
+  narrows the core `database-patterns.mdc` N+1 rule to the SQL shape
+  itself: the fix is a query that returns everything needed in one round
+  trip, not a cache layered on top of the repeated queries.
+- Select only the columns a caller actually needs — `SELECT *` in a
+  hand-written `.sql` file breaks silently when a column is added later
+  and can leak a sensitive column (a password hash, a token) into a
+  result set nothing downstream expected to see.
+- Wrap a multi-statement write (anything touching more than one table, or
+  more than one row-affecting statement against the same table) in an
+  explicit transaction — `BEGIN`/`COMMIT` or the driver's transaction
+  API — so a failure partway through rolls back cleanly instead of
+  leaving related tables inconsistent.
+- Keep a transaction's lifetime to the database work alone — commit
+  before making a slow external call (an HTTP request, a queue publish,
+  a `sleep`), or open a fresh transaction after it completes. A
+  transaction held open across an external call holds its locks for the
+  external call's entire duration, which can stall every other writer
+  touching the same rows.
+- Prefer `UPSERT` (Postgres `INSERT ... ON CONFLICT DO UPDATE`, MySQL
+  `INSERT ... ON DUPLICATE KEY UPDATE`) over a read-then-decide-insert-or-
+  update round trip when the goal is "write this row whether or not it
+  already exists" — the read-then-write version races under concurrent
+  writers even inside a transaction unless it also takes an explicit lock.
+
+## Migration hygiene
+
+- Every migration that mutates existing data (not just schema) states its
+  reverse operation, or explicitly states there isn't one and why (a
+  destructive backfill, a data transformation that can't be inverted).
+- Make DDL idempotent where the engine allows it (`IF NOT EXISTS` on
+  `CREATE TABLE`/`CREATE INDEX`, `IF EXISTS` on `DROP`) so a migration
+  runner that re-applies a partially-run migration after a crash does not
+  fail on an object that already exists.
+- Never combine a long-running backfill and a blocking schema change in
+  the same migration step — split them so the schema change (fast) and
+  the backfill (potentially slow, batched) can be reviewed and rolled
+  back independently.

package/src/gdskills/bundled/stacks/sql-db/rules/security.mdc

@@ -0,0 +1,74 @@
+---
+extends: common
+paths: ["**/*.sql"]
+metadata:
+  origin: authored
+---
+
+# SQL security
+
+Narrows `core-common-rules`' stack-agnostic security rules to injection
+safety and access control for `.sql` files across Postgres, MySQL, and
+generic SQL engines. Applies only to `*.sql` files — parameterized-query
+enforcement in application code (the driver/ORM call site) is covered by
+that language's own stack pack; this file covers the `.sql` side (stored
+procedures, functions, views) and the shared vocabulary both sides share.
+
+## Injection
+
+- Never build a query by concatenating or string-formatting a
+  user-influenced value into SQL text — this applies inside a stored
+  procedure or function body exactly as it does in application code: a
+  dynamic `EXECUTE`/`EXEC` built from concatenated input is injectable
+  even though the vulnerable code lives in the database, not the app.
+- Postgres `EXECUTE`/`format()` inside `PL/pgSQL`: use `format('...%I...',
+  identifier)` for identifiers (table/column names that must be dynamic)
+  and `format('...%L...', value)` or a parameterized `USING` clause for
+  values — `%I`/`%L` quote-escape correctly; plain string concatenation
+  of either does not.
+- MySQL stored procedures: build dynamic SQL with `PREPARE stmt FROM
+  @sql; EXECUTE stmt USING @param;` — bind user-influenced values through
+  `USING`, never interpolate them into `@sql` itself before `PREPARE`.
+- An ORM or query builder's raw-SQL escape hatch (a `.raw()`, `.exec()`,
+  or template-literal query method) carries the same rule as a
+  hand-written query: pass user-influenced values through its
+  placeholder/parameter API, never through string interpolation into the
+  raw SQL text, even when the surrounding call looks like it's "just
+  building a string for convenience."
+- A dynamic identifier (a table or column name chosen at runtime, common
+  in multi-tenant schema-per-tenant designs or admin tooling) cannot go
+  through a value placeholder at all — placeholders bind values, not
+  identifiers. Validate it against an allowlist of known-safe identifiers
+  before using it, never trust it as free text even when it "came from
+  our own config."
+
+## Access control
+
+- Grant the narrowest role/privilege a connection actually needs — an
+  application's runtime database user should not hold `DROP`/`CREATE`/
+  superuser privileges it never uses; a migration runner's credentials
+  (which do need DDL rights) should be separate from the application's
+  runtime connection.
+- Use row-level security (Postgres `CREATE POLICY` on a table with `ROW
+  LEVEL SECURITY` enabled) or an equivalent application-enforced tenant
+  filter consistently — do not rely on every query remembering to add
+  `WHERE tenant_id = ?` by convention alone when the engine can enforce it
+  structurally.
+- A view or stored procedure that runs with elevated privileges
+  (Postgres `SECURITY DEFINER`, a MySQL `DEFINER`-owned routine) is a
+  privilege-escalation surface if it accepts unvalidated input that
+  influences what it reads or writes — treat its parameters with the same
+  injection discipline as a top-level query, since callers with lower
+  privileges can reach the elevated code path through it.
+
+## Data exposure
+
+- Never `SELECT *` a table containing a sensitive column (password hash,
+  API token, PII) into a result set a caller with less trust than the
+  query's own privilege level will see — select named columns so adding a
+  sensitive column later can't leak silently into an existing query.
+- Encrypt or hash sensitive columns before they reach storage
+  (`pgcrypto`'s `crypt()`/`digest()` on Postgres, an application-layer
+  hash before insert) rather than relying on transport encryption alone —
+  a compromised backup or replica exposes plaintext columns even when
+  every connection to the primary was encrypted.

package/src/gdskills/bundled/stacks/sql-db/rules/testing.mdc

@@ -0,0 +1,83 @@
+---
+extends: common
+paths: ["**/*.sql"]
+metadata:
+  origin: authored
+---
+
+# SQL testing
+
+Narrows `core-common-rules`' stack-agnostic testing rules to testing raw
+`.sql` — migrations, schema, and hand-written query files — across
+Postgres, MySQL, and generic SQL engines. Applies only to `*.sql` files;
+testing a query or migration issued from application code (a language's
+ORM test helpers) is covered by that language's own stack pack, and
+should still follow the transactional-wrapping and fixture discipline
+below where that language's test suite talks to a real database.
+
+## Test isolation
+
+- Wrap each test in a transaction that is rolled back at teardown
+  (`BEGIN` before the test, `ROLLBACK` after) rather than truncating and
+  re-seeding tables between tests — rollback is faster and guarantees no
+  leftover state regardless of what the test wrote.
+- When a test must exercise something a transaction can't roll back
+  cleanly (`CREATE INDEX CONCURRENTLY`, an advisory-lock scenario, a
+  cross-transaction concurrency test), isolate it in its own
+  database/schema that is torn down and recreated instead of relying on
+  transactional rollback for that one case.
+- Never point a test suite at a shared development or staging database —
+  a fixed, disposable test database (a local container, an ephemeral
+  schema per CI run) so tests don't observe or clobber each other's data.
+
+## Fixtures and seed data
+
+- Seed only the rows a given test actually needs, built through the same
+  helper/factory the rest of the suite uses — do not duplicate a large
+  shared seed script per test file, and do not depend on a global fixture
+  a different test also mutates.
+- Name fixture data so a failure is legible (`user_with_expired_token`,
+  not `test_user_3`) — a table-driven or parameterized test case should
+  carry a descriptive case name for the same reason.
+- A fixture representing a timestamp or "now"-relative value is
+  constructed relative to a fixed, injected clock/reference time in the
+  test, not `NOW()`/`CURRENT_TIMESTAMP` evaluated live — a live clock
+  value makes boundary cases (rows that just expired, rows created "just
+  now") flaky depending on when the test happens to run.
+
+## Testing migrations
+
+- Test a migration's `up` path against a database seeded to look like
+  production before the change: representative row counts for anything
+  the migration scans or backfills, not an empty table where every
+  approach looks instant.
+- Test the reverse/`down` path when the migration states one — running
+  `up` then `down` should leave the schema equivalent to before, and
+  running `up` twice (or `down` twice) should not error when the
+  migration was written to be idempotent.
+- For a batched backfill migration, test with a row count large enough to
+  exercise at least two batches, and assert every row was updated exactly
+  once (no row skipped at a batch boundary, none processed twice in a way
+  that would double-apply a non-idempotent update).
+
+## Testing queries
+
+- Assert on the query's actual result set (rows, values, ordering when
+  the query specifies `ORDER BY`), not merely that it executed without
+  error — a query testing only "did not throw" would pass even after a
+  regression silently returns zero or the wrong rows.
+- For a query added to fix an N+1, assert the query count too (most
+  ORMs/test harnesses expose a query counter or log) — a regression test
+  for an N+1 fix should fail again if the fix regresses back to per-row
+  queries, not just check the final result shape.
+- Test the empty-result case (a `WHERE` that matches nothing) and the
+  boundary case for any range condition (`created_at >= X`) explicitly —
+  these are exactly where an off-by-one in a range filter or a `JOIN`
+  that should have been a `LEFT JOIN` shows up.
+
+## Verification
+
+- Run the full suite against the transactional-rollback isolation
+  described above before considering a change to `.sql` test fixtures or
+  migration tests done — a test that passes in isolation but leaves state
+  for the next test to trip over is not actually isolated.

package/src/gdskills/bundled/stacks/sql-db/skills/sql-db-build-fix/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: sql-db-build-fix
+description: "Use when a raw SQL migration fails to apply, a query planner regresses to a full table scan, or a constraint violation blocks a deploy -- resolves failed/broken migrations, missing-index query regressions, deadlocks, and NOT NULL/unique/foreign-key constraint violations with the smallest root-cause fix. Not for a Django/Rails/Laravel ORM's own migration file (a .py/.rb/.php migration -- use that stack's own build-fix skill)."
+triggers:
+  - "this migration is failing to apply, help me fix it"
+  - "this query used to use the index and now does a sequential scan"
+  - "I'm getting a unique constraint violation running this migration"
+  - "this migration is failing with a foreign key violation"
+  - "the query planner stopped using this index after the last deploy"
+  - "two migrations conflict and one fails to apply"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# SQL / database build fix (Postgres, MySQL, generic SQL)
+
+Resolve a failed or broken migration, a query planner regression (an
+index that stopped being used), or a constraint violation blocking a
+deploy — with the smallest change that fixes the actual root cause.
+`rules/patterns.mdc` and `rules/security.mdc` govern what a "correct" fix
+looks like; this skill never reaches for a suppression (dropping a
+constraint, skipping a migration step) instead of a fix.
+
+## Workflow
+
+### Step 1: Reproduce and classify
+
+Run the migration/query against a local or staging database that mirrors
+the failure, and read the exact error text. Classify it:
+
+- **Migration apply failure** — a DDL statement errors (object already
+  exists, object doesn't exist, syntax error, a lock timeout).
+- **Constraint violation** — `NOT NULL`, `UNIQUE`, `CHECK`, or foreign-key
+  violation raised while running a migration's backfill or while the
+  application inserts/updates a row.
+- **Planner regression** — a query that used an index before now runs a
+  sequential/full-table scan (`EXPLAIN`/`EXPLAIN ANALYZE` shows the
+  changed plan).
+- **Deadlock/lock timeout** — two transactions each holding a lock the
+  other needs, or a migration's lock request timing out against live
+  traffic.
+- **Migration ordering conflict** — two migrations both claim the same
+  version/sequence number, or one depends on schema state a
+  not-yet-applied migration would create.
+
+### Step 2: Fix by category
+
+**Migration apply failure:** read the exact error. "Object already
+exists" on a re-run usually means the migration isn't idempotent — add
+`IF NOT EXISTS`/`IF EXISTS` where the engine supports it, or check
+whether a previous partial run needs manual cleanup before retrying
+(state which, in the report). Never just delete/skip the migration file
+to make the runner stop complaining.
+
+**Constraint violation on backfill or insert:** find the actual row(s)
+violating the constraint — do not disable or drop the constraint to make
+the error go away. A `NOT NULL` violation during backfill usually means
+the backfill's default/derivation logic missed a case (a row with a
+legitimately different history); a `UNIQUE` violation usually means
+duplicate data existed before the constraint was added — decide the
+correct resolution (merge, dedupe, or a documented exception) rather than
+loosening the constraint to accept invalid data.
+
+**Planner regression (unused index):** confirm with
+`EXPLAIN (ANALYZE, BUFFERS)` (Postgres) / `EXPLAIN ANALYZE` (MySQL)
+whether the index still exists, whether statistics are stale
+(`ANALYZE <table>` on Postgres, `ANALYZE TABLE` on MySQL, after a large
+data change), or whether the query's own shape changed in a way that no
+longer matches the index's column order (per `rules/patterns.mdc`'s
+composite-order guidance) — fix the actual cause (re-run `ANALYZE`,
+correct the index shape) rather than forcing a plan with a planner hint
+as the first resort.
+
+**Deadlock/lock timeout:** read which two operations held conflicting
+locks (Postgres logs both queries and lock modes in a deadlock error;
+MySQL's `SHOW ENGINE INNODB STATUS` shows the last deadlock). Fix by
+making both code paths acquire locks in the same order, shortening the
+transaction that holds the lock too long, or batching a migration's
+backfill into smaller steps that each commit — not by retrying blindly or
+raising the lock timeout to paper over the contention.
+
+**Migration ordering conflict:** renumber/rebase the conflicting
+migration against the current head per the project's migration tool's own
+conflict-resolution convention; never force-apply one migration over
+another's recorded state without understanding what schema each expects.
+
+### Step 3: Verify
+
+Re-run the migration end-to-end (up, and down if it has one) against a
+representative dataset. Re-run the regressed query with
+`EXPLAIN`/`EXPLAIN ANALYZE` and confirm the expected plan. Confirm no
+constraint violation remains across the full backfill, not just the row
+that originally failed.
+
+### Step 4: Report
+
+```
+Fixed: migrations/2026_09_18_backfill_status.sql
+  - Root cause: 340 legacy rows had status = '' (not NULL) from a prior
+    import, which the backfill's WHERE status IS NULL clause missed
+  - Extended the backfill condition to also match status = ''
+  - Migration re-run clean against a full-size copy of the table
+```
+
+State the root cause in one sentence, not just "fixed the error."
+
+## Rules
+
+- Find and fix the smallest change that addresses the actual root cause —
+  never widen a fix beyond what the failure requires.
+- NEVER drop or loosen a constraint (`NOT NULL`, `UNIQUE`, a foreign key)
+  to make a violation stop erroring instead of fixing the data or the
+  logic that produced the violation.
+- NEVER delete or skip a failing migration step to reach a "successful"
+  migration run.
+- NEVER force a query plan with a planner hint as the first fix for a
+  regression before checking whether statistics are stale or the index
+  shape no longer matches the query.
+- NEVER raise a lock/statement timeout to make a deadlock or contention
+  error stop appearing without addressing the actual lock ordering or
+  transaction duration.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just drop the NOT NULL constraint so the insert succeeds" | Silences the violation without fixing why a NULL reached this point — the constraint existed to catch exactly this; find and fix the actual bad data or code path instead |
+| "This migration keeps failing on re-run, I'll delete it and start over" | Deleting a migration that already partially applied against some environments leaves them permanently out of sync with a fresh one; add IF EXISTS/IF NOT EXISTS or fix the idempotency issue instead |
+| "The query got slow, I'll just add a planner hint to force the old plan" | A hint papers over the actual cause (stale statistics, a changed index shape) and can go stale itself the next time data distribution shifts; fix the underlying cause first |
+| "I'll bump the lock timeout so this migration stops timing out" | A longer timeout doesn't resolve the contention, it just waits longer before the same conflict occurs; fix the lock ordering or shrink the transaction instead |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- The migration re-runs clean end-to-end (up, and down if applicable)
+  against a representative dataset, not just the originally failing row.
+- No constraint was dropped or loosened as part of the fix, unless the
+  report explicitly states the constraint itself was wrong and why.
+- For a planner regression, `EXPLAIN`/`EXPLAIN ANALYZE` confirms the
+  expected plan after the fix, not just that the query no longer errors.
+- The report states the root cause in one sentence, not just "it works
+  now."