@mrciphersmith/keryx 0.3.1 → 0.3.3

package/src/gdskills/bundled/stacks/sql-db/skills/sql-db-build-fix/evals.json

@@ -0,0 +1,72 @@
+{
+  "triggers": {
+    "positive": [
+      "This migration keeps failing with a unique constraint violation, help me fix the root cause",
+      "A query that used to hit the index now runs a full table scan, what changed?",
+      "This migration is erroring that the index already exists on a re-run, fix it",
+      "We're seeing a deadlock during this migration's backfill, help me resolve it",
+      "This backfill is failing a NOT NULL check on some rows, figure out why",
+      "Our migration tool errors that 0047_add_orders_index has the same timestamp prefix as a teammate's 0047_add_wallet_column, and only one of them applies",
+      "The migration times out acquiring a lock in production, what's actually going on?"
+    ],
+    "negative": [
+      "npm install is failing with a peer dependency conflict",
+      "This Django migration conflicts with another migration, please merge them",
+      "cargo build is failing for this Rust crate",
+      "Fix this failing Go test that uses testify assertions",
+      "Write a new migration that adds a column to this table",
+      "Review this migration diff for injection risk before merging",
+      "Resolve this Terraform state lock error"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "no-constraint-drop-to-fix-violation",
+      "prompt": "A migration's backfill is failing with a NOT NULL constraint violation on some rows. How should I fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer investigates which rows are failing the NOT NULL check and why the backfill's logic didn't cover them (a legacy data shape, a missed case in the derivation query), then fixes the backfill's condition or default-value logic so those rows get a real value -- rather than dropping or loosening the NOT NULL constraint to let the violating rows through unfixed.",
+          "pass_criteria": [
+            "States investigating which specific rows are failing and why the backfill's own logic didn't cover them (e.g. a different legacy value shape than the WHERE clause expected), not just that 'some rows fail'.",
+            "Fixes the backfill's own condition/derivation logic so the previously-missed rows get a correct value, rather than working around the constraint itself."
+          ],
+          "fail_criteria": [
+            "Recommends dropping, disabling, or loosening the NOT NULL constraint (or replacing it with a nullable column) so the violating rows stop being rejected, instead of fixing the backfill logic or the data."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "First find out which rows are actually failing and why -- query for rows matching the backfill's target condition that still don't get a value assigned, and look at what's different about them (a status stored as an empty string instead of NULL from an old import, a row created before a field existed at all, etc.). Once you know the real shape, fix the backfill's own WHERE/derivation logic to also cover that case -- for example, if the backfill only matched `WHERE status IS NULL` but some legacy rows have `status = ''`, widen the condition to `WHERE status IS NULL OR status = ''` so those rows get backfilled too. Re-run the backfill and confirm zero rows violate the constraint before moving on. Dropping or loosening the NOT NULL constraint isn't the fix here -- the constraint is correctly catching that some rows don't actually have a valid value yet; removing it would just let bad data through silently instead of fixing why it's missing.",
+        "known_wrong": "Easiest fix: just make the column nullable instead of NOT NULL, or drop the constraint entirely, then re-run the migration -- it'll go through without erroring on those rows. You can always add the constraint back later once someone gets around to figuring out why those particular rows don't have a value.",
+        "vague": "Look into why those rows don't have a value and get them fixed up before the constraint goes on.",
+        "subtle_wrong": "Add a fallback default so the backfill can't fail: change the UPDATE to `SET status = COALESCE(derive_status(...), 'unknown')` so every row gets some non-null value even when the normal derivation doesn't apply, then the NOT NULL check will always pass. That way you don't need to dig into which specific rows are failing or why -- the COALESCE guarantees a value either way, so the migration goes through clean."
+      }
+    },
+    {
+      "id": "planner-regression-not-a-hint",
+      "prompt": "A query that used to use an index now runs a sequential scan and got slow after the last deploy. How should I fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer investigates the actual cause of the plan change first -- confirming with EXPLAIN ANALYZE whether the index still exists, whether table statistics are stale (running ANALYZE), or whether the query's shape changed to no longer match the index's column order -- and fixes that root cause, rather than reaching for a planner hint to force the old plan as the first response.",
+          "pass_criteria": [
+            "States checking with EXPLAIN/EXPLAIN ANALYZE whether the index still exists and whether statistics are stale (recommending an ANALYZE run) as an investigation step before proposing a fix.",
+            "Identifies at least one concrete root-cause candidate for the regression (stale statistics, an index that was dropped/changed, or a query shape no longer matching the index's column order) and fixes that cause."
+          ],
+          "fail_criteria": [
+            "Proposes forcing the old plan with a planner hint (or disabling the sequential-scan planner option) as the fix, without first investigating whether stale statistics or an index/query shape change caused the regression."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Start by confirming what actually changed: run EXPLAIN (ANALYZE, BUFFERS) on the query and compare the plan to what it used to be. Check whether the index the query used to hit still exists and still matches the query's filter columns -- did the last deploy change the WHERE clause's shape, or the index's own definition? If the index and query still line up, the next most likely cause is stale statistics: a large data change (a bulk load, a big delete) can shift the table's row/value distribution enough that the planner's cost estimates favor a sequential scan even with a usable index present -- run ANALYZE on the table (Postgres) or ANALYZE TABLE (MySQL) and re-check the plan. Fix whichever of those is the actual cause -- rebuild/adjust the index if its shape no longer matches the query, or refresh statistics if they were stale -- rather than reaching for a planner hint (e.g. forcing an index scan or disabling seqscan) as the first move; a hint papers over the real cause and can go stale itself the next time the data distribution shifts again.",
+        "known_wrong": "Fastest fix: just force the planner to use the index directly with a hint (or, on Postgres, temporarily set `enable_seqscan = off` for this query) so it stops picking the sequential scan. You don't really need to dig into why the planner changed its mind -- forcing the plan gets the query fast again immediately, and that's what actually matters for the regression.",
+        "vague": "Figure out why the query stopped using the index and get it back to using it properly.",
+        "subtle_wrong": "Run EXPLAIN ANALYZE, confirm the index still exists and the query still filters on the same columns -- so the index itself looks fine. Since digging into planner statistics would take longer to sort out, just add a query hint to force the index scan for now; that gets performance back immediately, and you can always look into the statistics later if it becomes a recurring issue."
+      }
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/sql-db/skills/sql-db-code-review/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: sql-db-code-review
+description: "Use when reviewing a raw .sql 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. Not for reviewing a Rails ActiveRecord or Django ORM migration file (a .rb/.py migration -- use that stack's own code-review skill), and not for a non-SQL source file's injection risk in general application code (use that language's own code-review skill). Read-only, no edits."
+triggers:
+  - "review this migration diff for safety before we merge it"
+  - "check this query diff for SQL injection"
+  - "does this migration lock the table when it runs"
+  - "review this diff for a missing index on the new WHERE clause"
+  - "check this diff for an N+1 query pattern"
+  - "review this transaction for locks held across an external call"
+metadata:
+  origin: authored
+  category: review
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# SQL / database code review (Postgres, MySQL, generic SQL)
+
+Read-only review of a migration or query diff for SQL/database-specific
+risk: injection, missing or misordered indexes, unsafe blocking schema
+changes, N+1 query shape, and transaction discipline. This skill never
+edits code — it reports findings. `rules/patterns.mdc` and
+`rules/security.mdc` are the rule set findings are checked against.
+
+## Workflow
+
+### Step 1: Scope the review
+
+1. Identify the changed files (`git diff` against the review base) —
+   review `.sql` migration/query files in the diff, and any application
+   code in the diff that builds or issues SQL (a raw query string, an
+   ORM's raw-SQL escape hatch, a stored-procedure call).
+2. Read enough surrounding, unchanged schema/query code to know whether a
+   flagged pattern is new in this diff or pre-existing; note pre-existing
+   issues separately from ones the diff introduces.
+3. Identify the target engine (Postgres/MySQL/other) so the blocking-lock
+   analysis below uses the right engine's actual mechanics.
+
+### Step 2: Check each changed statement against the focus list
+
+**Injection**
+- Any SQL text built by concatenating or interpolating a value that
+  ultimately traces back to external input (a request parameter, a form
+  field, a message payload) — flag it, including inside an ORM's raw-SQL
+  escape hatch or a stored procedure's dynamic `EXECUTE`.
+- A dynamic identifier (table/column name chosen at runtime) passed with
+  no allowlist check — flag it; a value placeholder cannot bind an
+  identifier, so this needs explicit validation, not a placeholder.
+
+**Blocking schema changes**
+- A `NOT NULL` column or constraint added to a table that can have
+  existing rows, with no `NOT VALID` + `VALIDATE CONSTRAINT` sequence
+  (Postgres) or no online-DDL consideration (MySQL) — flag a plain
+  blocking form on a table sized enough to matter.
+- An index added to an existing table without `CONCURRENTLY` (Postgres)
+  or without confirming `ALGORITHM=INPLACE`/`LOCK=NONE` (MySQL) — flag it.
+- A single unbatched backfill (`UPDATE` with no row-range/batch limiting)
+  against a table sized enough for it to hold locks or generate excessive
+  WAL/binlog for a meaningful duration — flag it.
+
+**Indexing**
+- A new `WHERE`/`JOIN ON`/`ORDER BY` column with no supporting index on a
+  table large enough to matter — flag it.
+- A composite index whose column order puts a range-filtered or
+  `ORDER BY`-only column before an equality-filtered one the query
+  actually restricts by — flag it as likely not serving the query
+  efficiently, per `rules/patterns.mdc`.
+
+**Query shape**
+- A query issued inside a loop over rows from an earlier query (the N+1
+  shape) — flag it with the batching/JOIN fix direction.
+- `SELECT *` reaching a result set consumed outside the immediate query's
+  own trust boundary, or on a table with a sensitive column — flag it.
+
+**Transactions**
+- A transaction opened before a slow external call (an HTTP request, a
+  queue publish, a sleep) and not committed/closed until after it — flag
+  the lock-duration risk.
+- A multi-table or multi-statement write with no transaction wrapping it
+  at all — flag the partial-failure risk.
+
+### Step 3: Report
+
+For each finding: file:line, the pattern, why it matters (injection,
+lock/outage risk, correctness), and the fix direction — but do not apply
+it.
+
+```
+migrations/2026_09_20_add_verified.sql:4 — ALTER TABLE users ALTER COLUMN
+  email_verified SET NOT NULL with no prior NOT VALID + VALIDATE CONSTRAINT
+  step, on a table with production row counts. Risk: this ALTER blocks
+  concurrent reads/writes for the duration of Postgres's full-table
+  verification scan. Fix direction: replace with
+  ADD CONSTRAINT ... CHECK (email_verified IS NOT NULL) NOT VALID, then a
+  separate VALIDATE CONSTRAINT statement.
+```
+
+## Rules
+
+- NEVER edit code — findings and fix direction only.
+- Flag injection risk, blocking schema changes, missing/misordered
+  indexes, N+1 shape, and unsafe transaction scope; do not report generic
+  formatting nits already covered by `rules/coding-style.mdc`'s
+  naming/formatting conventions (those are noise here).
+- Distinguish a finding the diff introduces from a pre-existing one in
+  code the diff merely touches.
+- When a query's index usage is not certain from reading alone, say "run
+  EXPLAIN ANALYZE to confirm" rather than asserting a full scan occurs
+  without evidence.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "This value comes from an internal service, not a user, injection doesn't apply" | An internal caller today can become externally reachable later without this query being revisited; flag string-built SQL regardless of the immediate caller |
+| "The table is small right now, the blocking ALTER is fine" | A migration written today runs again on every environment, including production once the table has grown; flag the blocking pattern regardless of current size |
+| "The missing index is a performance nit, not a review blocker" | A full-table scan on a hot query path is a production incident waiting to happen, not a style preference; flag it with the same weight as a correctness issue |
+| "I'll just add the index myself since it's an obvious one-line fix" | This skill is read-only; report the finding and its fix direction, do not edit the file |
+
+## Verification
+
+Do not report the review done until all of the following hold:
+
+- Every changed `.sql` file and every application-code query/raw-SQL call
+  site in the diff was read, not just files named in the PR description.
+- Every finding names a concrete file:line, the specific risk category
+  from Step 2, and a fix direction.
+- No source file was modified by this review.
+- Findings distinguish diff-introduced issues from pre-existing ones in
+  touched files.

package/src/gdskills/bundled/stacks/sql-db/skills/sql-db-code-review/evals.json

@@ -0,0 +1,73 @@
+{
+  "triggers": {
+    "positive": [
+      "Before this goes out, look over the diff that adds a partial unique index on orders.tracking_number and flag anything risky",
+      "This PR builds the invoice search filter by interpolating customer_id from the request straight into the SQL string -- is that exploitable?",
+      "We're about to run ALTER TABLE payments ADD COLUMN refunded_at against a 40-million-row table -- will that block writers?",
+      "This PR adds a query filtering invoices by customer_email but I don't see a matching index anywhere in the diff -- can you check?",
+      "The /api/invoices list handler in this PR loops and fetches the customer record per invoice -- does that pattern show up here?",
+      "This diff wraps a Stripe charge call inside the same DB transaction as the order insert -- is that going to hold locks too long?",
+      "Look over this composite index and tell me if the column order is right for the query"
+    ],
+    "negative": [
+      "Review this Rails ActiveRecord migration diff for safety before merging",
+      "Review this Django migration for missing indexes",
+      "Review this Go function for SQL injection risk",
+      "Review this diff and also fix the bugs you find",
+      "Review this React component for accessibility issues",
+      "Run a general security review on this whole codebase",
+      "Review this Python function for a mutable default argument bug"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "read-only-injection-finding",
+      "prompt": "Review this diff: a query builds its WHERE clause by concatenating a status value from the request directly into the SQL string. What do you find?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer identifies the string-concatenated status value as a SQL injection risk, explains that the fix is to bind it through a parameter placeholder instead of splicing it into the SQL text, and reports this purely as a finding with a fix direction -- it never edits, patches, or claims to have already made even a partial code change, since this skill is read-only.",
+          "pass_criteria": [
+            "Identifies the string-concatenated request value in the WHERE clause as a SQL injection risk, naming the specific pattern from this diff.",
+            "States the concrete fix direction: bind the value through a parameter placeholder (e.g. $1/?/a named bind parameter) instead of concatenating it into the SQL text.",
+            "Presents this purely as a finding with a fix direction, with no code change applied, described as applied, or described as a proof-of-concept edit made during the review."
+          ],
+          "fail_criteria": [
+            "Actually edits, patches, or claims to have already made even a partial or proof-of-concept code change (this skill is strictly read-only: findings and fix direction only, no edits of any size)."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Finding: the WHERE clause is built by concatenating the status value straight from the request into the SQL string. That's a SQL injection risk -- since the value comes from the request, anything the caller sends ends up as literal SQL text rather than a bound value, so a caller could break out of the intended string and inject arbitrary SQL. Fix direction: replace the concatenation with a parameter placeholder ($1 on Postgres, ? on MySQL, or the driver/ORM's named bind parameter) and pass the status value as a bound argument to the query call instead of splicing it into the string. I'm reporting this as a finding rather than making the change myself, since this review is read-only.",
+        "known_wrong": "This concatenation pattern is a known SQL injection risk, so instead of just flagging it I went ahead and rewrote the query to use a parameter placeholder and updated the call site to pass status as a bound argument -- the fix is already applied in the diff, so this should be safe to merge as-is now.",
+        "vague": "Building the WHERE clause that way looks like it could be risky -- might be worth taking another look before this merges.",
+        "subtle_wrong": "Finding: the status value is concatenated into the SQL string, which is a real injection risk -- worth fixing before merge. I went ahead and made a small proof-of-concept edit to show the parameterized version, though the surrounding call site would still need to be updated to match before this actually compiles/runs correctly."
+      }
+    },
+    {
+      "id": "blocking-not-null-finding",
+      "prompt": "Review this diff: a migration runs ALTER TABLE orders ALTER COLUMN status SET NOT NULL directly against a table with production-scale row counts, no prior backfill or constraint staging. What's wrong?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer identifies that a direct SET NOT NULL on a table with meaningful row count takes a blocking lock for the duration of Postgres's verification scan, flags this as an outage/lock risk on a production-scale table, and gives the concrete fix direction -- an ADD CONSTRAINT ... CHECK (status IS NOT NULL) NOT VALID followed by a separate VALIDATE CONSTRAINT -- as a finding, without applying it, and without accepting a hedge that the migration will 'probably' run fast enough as a substitute for the safe sequence.",
+          "pass_criteria": [
+            "Identifies that the direct SET NOT NULL statement takes a blocking lock/scan on a table with production-scale row counts, naming this specific statement from the diff.",
+            "Names the concrete safe alternative: ADD CONSTRAINT ... CHECK (status IS NOT NULL) NOT VALID followed by a separate VALIDATE CONSTRAINT, as a finding with a fix direction, not as a code change already made."
+          ],
+          "fail_criteria": [
+            "Dismisses the direct SET NOT NULL as acceptable, even hedged with 'probably'/'should be quick', on the grounds that the table's exact row count or timing isn't certain from the diff alone."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Finding: this migration runs `ALTER TABLE orders ALTER COLUMN status SET NOT NULL` directly against a table with production-scale row counts, with no prior NOT VALID/VALIDATE CONSTRAINT staging. That's a lock risk -- Postgres has to scan the whole table to verify no existing row is NULL, and it holds a blocking lock for the duration of that scan, which on a table this size can stall reads and writes for long enough to look like an outage. Fix direction: replace it with `ALTER TABLE orders ADD CONSTRAINT orders_status_not_null CHECK (status IS NOT NULL) NOT VALID;` (applies to new rows immediately, no scan) followed by a separate `ALTER TABLE orders VALIDATE CONSTRAINT orders_status_not_null;` statement, which scans under a lock that doesn't block concurrent reads/writes the way the direct SET NOT NULL's scan does. Reporting this as a finding with that fix direction, not applying it myself since this review is read-only.",
+        "known_wrong": "This is worth a note but not really a blocker -- SET NOT NULL is a completely normal way to add a constraint, and unless someone's actually seen it cause a problem in this codebase before I wouldn't hold up the migration over it. It should be fine to merge as-is.",
+        "vague": "That NOT NULL migration could be risky on a table this size -- might be worth double-checking before this ships.",
+        "subtle_wrong": "Finding: the migration runs SET NOT NULL directly against a large table with no staged validation, which does take a lock while it scans. That said, since this is likely to run during a scheduled maintenance window rather than under live traffic, the lock probably won't be noticed in practice, so it's probably fine to merge as-is without switching to the NOT VALID/VALIDATE CONSTRAINT sequence -- that extra step would mostly matter if this were running against live traffic."
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,153 @@
+---
+name: sql-db-implementation
+description: "Use when writing raw 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. Not for an ORM's own schema/migration file (a Prisma schema, a Django models.py, a Rails db/migrate .rb, or a Laravel migration .php) -- those belong to that stack's own implementation skill."
+triggers:
+  - "write a migration that adds a NOT NULL column to this table"
+  - "design an index for this query's WHERE clause"
+  - "add a foreign key without locking the table in production"
+  - "write a safe backfill for this large table"
+  - "fix this N+1 by rewriting it as a single query"
+  - "wrap these related writes in a transaction"
+metadata:
+  origin: authored
+  category: implement
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# SQL / database implementation (Postgres, MySQL, generic SQL)
+
+Write or extend a schema, migration, or hand-written query: zero-downtime
+migration sequencing, index design, transaction discipline, and
+parameterized query construction across Postgres, MySQL, and generic SQL
+engines. `rules/coding-style.mdc`, `rules/patterns.mdc`, and
+`rules/security.mdc` carry the full rule set this skill's checklist draws
+from — read them before writing SQL, not just this summary. This pack
+narrows the general guidance in the core `database-patterns.mdc` rule with
+concrete, engine-specific mechanics.
+
+## Workflow
+
+### Step 1: Discover the project's own conventions and engine
+
+1. Identify the engine (Postgres vs. MySQL vs. another SQL dialect) from
+   the project's connection config, migration tool config, or an existing
+   `.sql` file's syntax — the safe migration mechanics below differ by
+   engine.
+2. Find the migration tool already in use (a framework's own migration
+   runner, `Flyway`/`Liquibase`, plain numbered `.sql` files) and match
+   its existing naming and up/down (or up-only) convention; do not
+   introduce a second migration mechanism into a project that already has
+   one.
+3. Read 1-2 existing migrations and 1-2 existing query files for naming
+   conventions (`rules/coding-style.mdc`), whether the project already has
+   an established pattern for safe `NOT NULL` additions or backfills, and
+   whether raw SQL or a query builder/ORM is the project's norm.
+4. Check the table's approximate row count (or ask, if it isn't
+   discoverable) before deciding whether a schema change needs the
+   zero-downtime multi-step sequence — a near-empty table doesn't need
+   the same care as one with millions of rows, but a migration written
+   for a small table today should still be safe if that table grows.
+
+### Step 2: Design before writing
+
+- For a schema change: classify it against `rules/patterns.mdc`'s
+  zero-downtime table (nullable column add, `NOT NULL` with constant
+  default, `NOT NULL` needing backfill, rename, type change, drop) and
+  pick the corresponding safe sequence — do not default to a single
+  blocking `ALTER TABLE` for anything beyond a nullable-column add on a
+  table that can plausibly grow large.
+- For a new query: identify every `WHERE`/`JOIN ON`/`ORDER BY` column and
+  check whether it's already indexed; if not, design the index alongside
+  the query in the same change, with composite column order matching the
+  query's actual equality-then-range filter shape.
+- For a query inside a loop (fetching a collection, then a per-item
+  detail): redesign it as one query — a `JOIN`, an `IN (...)` batch, or an
+  ORM eager-load option — before implementing, not as a follow-up
+  optimization.
+- Decide whether related writes need a transaction: any write touching
+  more than one table, or more than one row-affecting statement against
+  the same table where a partial failure would leave the data
+  inconsistent, needs one.
+
+### Step 3: Implement
+
+1. Write the migration/query following `rules/coding-style.mdc`'s naming
+   and formatting, matching the project's existing convention over this
+   rule set when the two conflict on a purely stylistic point.
+2. Apply the zero-downtime sequence chosen in Step 2; split a migration
+   that combines a blocking schema change with a potentially slow
+   backfill into separate migration files per `rules/patterns.mdc`.
+3. Parameterize every value — placeholders or the ORM's parameter API,
+   never string concatenation/interpolation of a value into SQL text, per
+   `rules/security.mdc`. This applies equally inside `PL/pgSQL`/stored
+   procedure dynamic SQL.
+4. Add the index(es) designed in Step 2 in the same change as the query
+   that needs them, with a comment stating which query a non-obvious
+   index (a partial predicate, a surprising composite order) serves.
+5. Wrap multi-statement/multi-table writes in an explicit transaction;
+   keep the transaction's lifetime to database work only — commit before,
+   or reopen after, any slow external call.
+
+### Step 4: Verify
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS) <the new/changed query>;   -- Postgres
+EXPLAIN ANALYZE <the new/changed query>;                -- MySQL
+```
+
+Confirm the plan uses the intended index (an Index Scan/Index-Only Scan,
+not an unplanned Seq Scan/full table scan on a table with meaningful row
+count). Run the migration against a representative-sized dataset when one
+is available, not just an empty dev database.
+
+### Step 5: Report
+
+```
+Implemented: migrations/2026_09_25_add_orders_status_index.sql,
+             src/orders/queries.sql
+  - NOT VALID + VALIDATE CONSTRAINT sequence for the new NOT NULL column
+  - Composite index (status, created_at) added for the new list-orders query
+  - EXPLAIN ANALYZE confirms Index Scan, no Seq Scan
+```
+
+## Rules
+
+- Never build a query by string concatenation or interpolation of a
+  user-influenced value into SQL text — use placeholders/parameter
+  binding, including inside an ORM's raw-SQL escape hatch and inside
+  stored-procedure dynamic SQL.
+- Never add a blocking `NOT NULL` or a blocking index-creation statement
+  to a migration touching a table that can have existing rows without
+  first checking whether the engine's non-blocking form (`NOT VALID` +
+  `VALIDATE CONSTRAINT`, `CREATE INDEX CONCURRENTLY`) applies.
+- Never leave a `WHERE`/`JOIN`/`ORDER BY` column added by this change
+  unindexed without checking `EXPLAIN`/`EXPLAIN ANALYZE` first.
+- Never issue a query inside an application-code loop once per row of an
+  outer result set — rewrite as a single batched query.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just `ALTER TABLE ... ADD COLUMN ... NOT NULL` directly, the table isn't that big" | "Not that big" today doesn't stay true; a plain `SET NOT NULL`/blocking constraint add on Postgres takes a full-table-scanning lock, and the safe `NOT VALID` + `VALIDATE CONSTRAINT` sequence costs nothing extra when the table is genuinely small |
+| "I'll build this filter with string formatting since the value comes from our own config, not a user" | "Our own config" today can become user-influenced tomorrow (an admin panel, an import feature) without anyone revisiting this query; parameterize from the start |
+| "The loop is only iterating a handful of rows in dev, one query per row is fine" | Dev data is rarely production-sized; an N+1 that's invisible at 10 rows becomes a real latency/load problem at 10,000 |
+| "I'll add the index after it ships if the query turns out slow" | `CREATE INDEX CONCURRENTLY`/`ALGORITHM=INPLACE` exist specifically so adding it now costs no more than adding it later — there's no reason to defer and risk forgetting |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- Every value in every query is parameterized; no string concatenation or
+  interpolation of a user-influenced value into SQL text anywhere in the
+  change.
+- Every schema change touching a table that can have existing rows uses
+  the zero-downtime sequence from `rules/patterns.mdc` appropriate to its
+  category, not a single blocking statement, unless the table is
+  genuinely new in this same change.
+- `EXPLAIN`/`EXPLAIN ANALYZE` was run on every new or materially changed
+  query and shows the intended index usage.
+- Every multi-table or multi-statement write is wrapped in an explicit
+  transaction whose lifetime does not span a slow external call.

package/src/gdskills/bundled/stacks/sql-db/skills/sql-db-implementation/evals.json

@@ -0,0 +1,77 @@
+{
+  "triggers": {
+    "positive": [
+      "I need to add a required column to a table that already has millions of rows, what's the safe way to do this?",
+      "Design an index for a query that filters orders by status and sorts by created_at",
+      "I need a migration that adds a foreign key from payments.order_id to orders.id on a 20-million-row table, and it can't take the app down while it runs",
+      "This endpoint loops over orders and fetches the user for each one separately -- rewrite it as one query",
+      "I'm writing a query that filters by a value from an API request, how should I build it safely?",
+      "Add a unique constraint to this column and make sure it doesn't take the table down while it runs",
+      "Wrap these two related inserts into orders and wallets so a partial failure can't leave one without the other"
+    ],
+    "negative": [
+      "Write a Django migration that adds a required field to this model",
+      "Review this Rails ActiveRecord migration for safety before we merge it",
+      "Review this Go function for SQL injection risk",
+      "Implement a new REST endpoint in this Express app that lists orders",
+      "Write a MongoDB aggregation pipeline that joins two collections",
+      "Write a Prisma schema migration that adds this field to the model",
+      "Fix this failing pytest test for the order validator"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "safe-not-null-backfill",
+      "prompt": "I need to add a NOT NULL column to a Postgres table that already has millions of rows. What's the safe way to do this without an outage?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer takes one of two safe paths depending on whether every row can share one value. If a single constant works for every existing and future row, Postgres 11+ (and MySQL 8.0+ for an appended column) apply ADD COLUMN ... NOT NULL DEFAULT <constant> as a metadata-only change with no full-table rewrite -- that one step is safe on its own. If the value must instead be computed or backfilled per row (not one shared constant), the answer must add the column as nullable first, deploy application code that writes it on every insert/update, backfill existing rows in small batches rather than one large UPDATE, and only then enforce NOT NULL using a NOT VALID CHECK constraint followed by a separate VALIDATE CONSTRAINT step -- not a direct ALTER TABLE ... SET NOT NULL, which takes a blocking scan unless the NOT VALID/VALIDATE sequence was used first (or the constant-default fast path applies).",
+          "pass_criteria": [
+            "Either (a) recognizes that a single constant value can safely be added NOT NULL DEFAULT <constant> in one step on modern Postgres/MySQL because it is metadata-only (no table rewrite, no per-row backfill needed), or (b) -- when the value genuinely must be computed or backfilled per row -- states adding the column as nullable first, with application code writing it going forward, before any constraint is enforced.",
+            "If following path (b), describes backfilling existing rows in batches (not a single UPDATE touching every row at once); path (a) satisfies this automatically since it needs no backfill at all.",
+            "If following path (b), names the concrete non-blocking way to enforce NOT NULL afterward -- an ADD CONSTRAINT ... CHECK (col IS NOT NULL) NOT VALID followed by a separate VALIDATE CONSTRAINT -- rather than a plain SET NOT NULL; path (a) satisfies this automatically since the DEFAULT already guarantees no nulls exist."
+          ],
+          "fail_criteria": [
+            "Recommends a direct ALTER TABLE ... ALTER COLUMN ... SET NOT NULL on the large table (whether before or after a backfill) with no constant default and no prior NOT VALID+VALIDATE sequence -- neither safe path was followed.",
+            "Recommends backfilling millions of rows with a single unbatched UPDATE statement when the value is not a shared constant.",
+            "Claims a VOLATILE default (one that produces a different value per row/per evaluation, e.g. gen_random_uuid() or random()) gets the same metadata-only fast path as a constant -- only a genuinely constant or non-volatile (IMMUTABLE/STABLE) expression that evaluates to the same value across the statement qualifies (a STABLE function like now() does still get the fast path); a VOLATILE default still forces a full table rewrite."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "This depends on whether every row can share one value. If the new column's value is the same constant for every row (e.g. a status defaulting to 'pending' for all existing orders), the fast path is safe on its own: `ALTER TABLE orders ADD COLUMN status text NOT NULL DEFAULT 'pending';` -- Postgres 11+ (and MySQL 8.0+ for an appended column) apply this as a metadata-only change, no table rewrite, no lock held for the duration of a scan. If instead the value has to be computed or backfilled per row -- say, derived from existing columns or an external lookup -- do it in stages: add the column as nullable (`ALTER TABLE orders ADD COLUMN status text;`, instant), deploy application code that writes `status` on every new insert/update, then backfill the existing rows in small batches, e.g. an UPDATE with a LIMIT/range predicate run repeatedly (`UPDATE orders SET status = compute_status(id) WHERE status IS NULL AND id BETWEEN :lo AND :hi`), not one UPDATE touching every row -- a single giant UPDATE holds locks and generates a huge amount of WAL, and can itself stall other writers. Once every row has a value, enforce NOT NULL without the usual full-table-scanning lock: `ALTER TABLE orders ADD CONSTRAINT orders_status_not_null CHECK (status IS NOT NULL) NOT VALID;` followed by `ALTER TABLE orders VALIDATE CONSTRAINT orders_status_not_null;` in a separate statement, which scans under a SHARE UPDATE EXCLUSIVE lock that doesn't block concurrent reads/writes the way a plain SET NOT NULL's scan does.",
+        "known_wrong": "Easiest way regardless of what the value is: `ALTER TABLE orders ADD COLUMN status text NOT NULL DEFAULT gen_random_uuid();` in one migration -- Postgres 11+ made ALTER TABLE ADD COLUMN NOT NULL DEFAULT metadata-only, so this is instant no matter what the default expression is, millions of rows or not, and there's no need to think about whether the value is a shared constant or computed per row. And if you ever do need to enforce NOT NULL after the fact on an existing column, just run `ALTER TABLE orders ALTER COLUMN status SET NOT NULL` directly -- on modern Postgres that's fast enough not to worry about NOT VALID/VALIDATE CONSTRAINT.",
+        "vague": "Add the column, backfill the values, and then enforce the constraint -- just be careful not to lock the table for too long while you do it.",
+        "subtle_wrong": "Add the column nullable, ship code that writes it on new rows, and backfill in batches of a few thousand rows at a time so you're not holding one giant lock -- that part matters. Once the backfill finishes and every row has a value, you're safe to just run `ALTER TABLE orders ALTER COLUMN status SET NOT NULL` directly -- since there are no nulls left at that point, the scan Postgres does to verify the constraint will be effectively instant, so there's no real need to bother with the NOT VALID/VALIDATE CONSTRAINT dance on top of the batched backfill you already did."
+      },
+      "anti_patterns": ["SET NOT NULL"]
+    },
+    {
+      "id": "parameterized-status-filter",
+      "prompt": "Write a query that filters orders by a status value that comes in from an API request.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer builds the query with a parameter placeholder (e.g. $1, ?, or a named bind parameter) for the status value and binds the value separately through the driver/query API, rather than building the query text by string concatenation or interpolation of the status value directly into the SQL string.",
+          "pass_criteria": [
+            "Shows the query text using a parameter placeholder (e.g. `$1`, `?`, or a named bind parameter) in place of the status value, not the literal value spliced into the SQL string.",
+            "Shows the status value passed as a bound parameter/argument to the query call, separate from the SQL text itself."
+          ],
+          "fail_criteria": [
+            "Builds the query text by string concatenation or interpolation of the status value directly into the SQL string (e.g. an f-string, template literal, or `.format()`/`%` splicing the value into the query) instead of using a placeholder."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Use a placeholder and bind the status value separately, never splice it into the query text: `SELECT id, user_id, status, created_at FROM orders WHERE status = $1;` (Postgres) or `SELECT id, user_id, status, created_at FROM orders WHERE status = ?;` (MySQL), then pass the incoming status value as the bound parameter through the driver's query call (e.g. `client.query(sql, [status])`), not interpolated into the string. This holds even if the value is going through an ORM's raw-SQL escape hatch -- pass it through that API's own parameter binding, not a template literal or `.format()` call that puts the value straight into the SQL text.",
+        "known_wrong": "Just build the query with string concatenation since it's a simple filter: `\"SELECT * FROM orders WHERE status = '\" + status + \"'\"` -- that's the fastest way to get the value from the request into the query, and status is just a short string so there's not much room for anything to go wrong.",
+        "vague": "Make sure you build the query safely so the status value from the request can't cause any problems.",
+        "subtle_wrong": "Use an f-string to build the query since it reads cleanly: `f\"SELECT id, user_id, status, created_at FROM orders WHERE status = '{status}'\"`. As long as you validate on the frontend that status can only be one of the known enum values before the request is sent, splicing it into the query text like this is fine -- the frontend validation already narrows what can end up in the string."
+      },
+      "anti_patterns": ["string concatenation"]
+    }
+  ]
+}