rsc-universal 0.1.1

package/skills/podcast/scripts/verify.sh

@@ -0,0 +1,246 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural linter for podcast publish artifacts.
+#
+# WHAT IT DOES (read-only; never edits or writes anything)
+#   Static, network-free checks over the artifacts you point it at. Give it ONE
+#   file or a DIRECTORY (it will pick up *.json / *.xml|*.rss / *.vtt inside).
+#     chapters.json   -> parses; has `version` + `chapters[]`; each chapter has a
+#                        numeric `startTime`; startTimes are monotonically
+#                        non-decreasing.                                  (FAIL)
+#     RSS feed/<item> -> every <enclosure> has url + length + type attributes;
+#                        an <itunes:duration> is present; every
+#                        <podcast:transcript> carries a `type` attribute; any
+#                        <itunes:image>/<podcast:chapters> referenced artwork
+#                        filename hinting a size >=1400 (best-effort).      (FAIL)
+#     transcript.vtt  -> first non-empty line is `WEBVTT`.                  (FAIL)
+#
+#   Artifacts that are ABSENT are skipped (pass) so partial-phase work is not
+#   penalized. A clean OR empty target exits 0 — never a false failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh ./episode-12/                 # lint every artifact in a dir
+#   ./verify.sh ep12.chapters.json            # lint one file
+#   ./verify.sh feed.xml ep12.vtt             # lint several files
+#
+# EXIT CODES
+#   0  all present artifacts pass, or nothing to check (empty/clean target)
+#   1  a hard failure in at least one artifact
+#   2  bad usage (no target, target missing, or python3 unavailable)
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+usage() { sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; }
+
+TARGETS=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) TARGETS="$TARGETS
+$1"; shift ;;
+  esac
+done
+
+if [ -z "$TARGETS" ]; then
+  printf '%sno target given%s\n' "$RED" "$NC" >&2; usage; exit 2
+fi
+if ! command -v python3 >/dev/null 2>&1; then
+  printf '%spython3 not found — required to parse artifacts%s\n' "$RED" "$NC" >&2; exit 2
+fi
+
+# Expand targets: a directory contributes its json/xml/rss/vtt files; a file is
+# itself. Missing paths are a usage error.
+FILES=""
+while IFS= read -r t; do
+  [ -z "$t" ] && continue
+  if [ -d "$t" ]; then
+    for f in "$t"/*.json "$t"/*.xml "$t"/*.rss "$t"/*.vtt; do
+      [ -e "$f" ] && FILES="$FILES
+$f"
+    done
+  elif [ -f "$t" ]; then
+    FILES="$FILES
+$t"
+  else
+    printf '%starget not found: %s%s\n' "$RED" "$t" "$NC" >&2; exit 2
+  fi
+done <<EOF
+$TARGETS
+EOF
+
+# Nothing matched (e.g. empty dir): not a failure.
+if [ -z "$(printf '%s' "$FILES" | tr -d '[:space:]')" ]; then
+  printf '%s[ ok ]%s no podcast artifacts found — nothing to check\n' "$GREEN" "$NC"
+  exit 0
+fi
+
+printf 'podcast verify\n\n'
+
+# Stock macOS bash 3.2 mis-scans $( ... ) when the embedded heredoc contains
+# apostrophes, so we write the linter to a temp file and run it normally.
+PY_SCRIPT="$(mktemp -t podcast_verify.XXXXXX)"
+trap 'rm -f "$PY_SCRIPT"' EXIT
+cat > "$PY_SCRIPT" <<'PY'
+import json, os, re, sys
+
+files = [l for l in os.environ.get("FILES", "").splitlines() if l.strip()]
+# de-dup, keep order
+seen = set(); ordered = []
+for f in files:
+    if f not in seen:
+        seen.add(f); ordered.append(f)
+
+lines = []
+hard = 0
+def ok(m):  lines.append("OK:" + m)
+def warn(m):lines.append("WARN:" + m)
+def fail(m):
+    global hard
+    lines.append("FAIL:" + m); hard += 1
+
+def looks_chapters(text):
+    try:
+        d = json.loads(text)
+    except Exception:
+        return False
+    return isinstance(d, dict) and "chapters" in d
+
+def check_chapters(path, text):
+    try:
+        d = json.loads(text)
+    except Exception as e:
+        fail("%s: not valid JSON: %s" % (path, e)); return
+    if "version" not in d:
+        fail("%s: missing `version`" % path)
+    ch = d.get("chapters")
+    if not isinstance(ch, list):
+        fail("%s: `chapters` must be an array" % path); return
+    if not ch:
+        ok("%s: parses, empty chapters[] (nothing to order)" % path); return
+    last = None; bad = False
+    for i, c in enumerate(ch):
+        st = c.get("startTime") if isinstance(c, dict) else None
+        if not isinstance(st, (int, float)):
+            fail("%s: chapter %d has non-numeric startTime (%r)" % (path, i, st)); bad = True; continue
+        if last is not None and st < last:
+            fail("%s: chapter %d startTime %s < previous %s (not monotonic)" % (path, i, st, last)); bad = True
+        last = st
+    if not bad:
+        ok("%s: %d chapters, version present, startTimes monotonic" % (path, len(ch)))
+
+def check_feed(path, text):
+    encs = re.findall(r"<enclosure\b[^>]*>", text, re.I)
+    if encs:
+        for e in encs:
+            for attr in ("url", "length", "type"):
+                if not re.search(r'\b%s\s*=' % attr, e, re.I):
+                    fail("%s: <enclosure> missing %s attribute" % (path, attr))
+        if not [1 for e in encs if all(re.search(r'\b%s\s*='%a,e,re.I) for a in ("url","length","type"))]:
+            pass
+        else:
+            ok("%s: <enclosure> has url+length+type" % path)
+    if re.search(r"<item\b", text, re.I):
+        if not re.search(r"<itunes:duration\b", text, re.I):
+            fail("%s: <item> present but no <itunes:duration>" % path)
+        if not re.search(r"<guid\b", text, re.I):
+            fail("%s: <item> present but no <guid>" % path)
+    # transcript tags must carry type=
+    for tr in re.findall(r"<podcast:transcript\b[^>]*>", text, re.I):
+        if not re.search(r'\btype\s*=', tr, re.I):
+            fail("%s: <podcast:transcript> missing required type attribute" % path)
+        else:
+            ok("%s: <podcast:transcript> carries type=" % path)
+    # best-effort artwork size hint
+    for img in re.findall(r'href\s*=\s*["\']([^"\']+)["\']', text, re.I):
+        m = re.search(r'(\d{3,4})x(\d{3,4})', img)
+        if m:
+            w = int(m.group(1))
+            if w < 1400:
+                warn("%s: artwork '%s' hints %dpx wide, below the 1400px floor" % (path, os.path.basename(img), w))
+
+def check_vtt(path, text):
+    for ln in text.splitlines():
+        if ln.strip() == "":
+            continue
+        if ln.strip().startswith("WEBVTT"):
+            ok("%s: starts with WEBVTT" % path)
+        else:
+            fail("%s: transcript does not start with WEBVTT (first line: %r)" % (path, ln.strip()[:40]))
+        return
+    warn("%s: empty .vtt" % path)
+
+checked = 0
+for path in ordered:
+    if not os.path.isfile(path):
+        continue
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            text = fh.read()
+    except Exception as e:
+        fail("%s: cannot read: %s" % (path, e)); continue
+    if not text.strip():
+        ok("%s: empty file — skipped" % path); continue
+
+    low = path.lower()
+    if low.endswith(".json"):
+        if looks_chapters(text):
+            check_chapters(path, text); checked += 1
+        else:
+            ok("%s: JSON, not a chapters file — skipped" % path)
+    elif low.endswith(".xml") or low.endswith(".rss"):
+        check_feed(path, text); checked += 1
+    elif low.endswith(".vtt"):
+        check_vtt(path, text); checked += 1
+    else:
+        # unknown extension passed directly — sniff content
+        stripped = text.lstrip()
+        if stripped.startswith("WEBVTT"):
+            check_vtt(path, text); checked += 1
+        elif stripped.startswith("{") and looks_chapters(text):
+            check_chapters(path, text); checked += 1
+        elif re.search(r"<rss\b|<item\b|<enclosure\b", text, re.I):
+            check_feed(path, text); checked += 1
+        else:
+            ok("%s: unrecognized artifact — skipped" % path)
+
+if checked == 0 and hard == 0:
+    print("OK:no recognized podcast artifacts — nothing to check")
+print("\n".join(lines))
+sys.exit(1 if hard > 0 else 0)
+PY
+
+PY_OUT="$(FILES="$FILES" python3 "$PY_SCRIPT")" && PY_RC=0 || PY_RC=$?
+
+fail_count=0; warn_count=0
+while IFS= read -r line; do
+  [ -z "$line" ] && continue
+  case "$line" in
+    OK:*)   printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "${line#OK:}" ;;
+    WARN:*) printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "${line#WARN:}"; warn_count=$((warn_count + 1)) ;;
+    FAIL:*) printf '%s[fail]%s %s\n' "$RED"    "$NC" "${line#FAIL:}"; fail_count=$((fail_count + 1)) ;;
+    *) printf '%s\n' "$line" ;;
+  esac
+done <<EOF
+$PY_OUT
+EOF
+
+printf '\n'
+if [ "$fail_count" -gt 0 ] || [ "$PY_RC" -ne 0 ]; then
+  printf '%s%d hard failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$warn_count" -gt 0 ]; then
+  printf '%s%d warning(s), 0 hard failures%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 0
+fi
+printf '%sall checks passed%s\n' "$GREEN" "$NC"
+exit 0

package/skills/postgresdb/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: postgresdb
+description: Use when designing or reviewing a PostgreSQL schema (types, constraints, normalization), writing or optimizing SQL, choosing or adding indexes, reading EXPLAIN/ANALYZE, planning a migration (expand-contract, concurrent index, batched backfill), or operating/securing Postgres (roles, RLS, PgBouncer pooling, VACUUM/autovacuum, pg_stat_statements, declarative partitioning, backups/PITR). Triggers - "slow query", "add an index", "EXPLAIN", "design this table", "zero-downtime migration", "row level security", "connection pool", "N+1", "JSONB", "full-text search", "pgvector". PostgreSQL 16; ORM-agnostic (SQLAlchemy/Alembic, Prisma, golang-migrate, raw SQL).
+tags: [postgres, sql, database, migrations]
+recommends: [secure-coding]
+origin: risco
+---
+
+# PostgreSQL — schema, indexing, queries, ops
+
+Engine-level PostgreSQL 16 guidance: design correct schemas, pick the right index, read EXPLAIN and
+fix slow SQL, run zero-downtime migrations, and operate/secure the database. Tooling-agnostic; every
+example is runnable.
+
+## When to use / When NOT to use
+
+**When to use:**
+
+- Schema/DDL decisions: types, keys, constraints, generated/identity columns, enum-vs-lookup, jsonb-vs-column.
+- Any query that is slow, scans too much, or returns wrong cardinality; reading a plan.
+- Index decisions: which kind, column order, partial/covering, and when NOT to add one.
+- Migrations against tables with real data or live traffic.
+- Concurrency: isolation, locking, deadlocks, queues.
+- Ops: pooling, vacuum, monitoring, partitioning, backups, RLS, least-privilege roles.
+
+**When NOT to use:**
+
+- ORM-API ergonomics (Prisma `updateMany` count trap, SQLAlchemy session lifecycle) → your ORM's own docs. This skill owns the **SQL the ORM emits and the engine behavior underneath**.
+- Non-Postgres engines (MySQL/SQLite/ClickHouse) — different MVCC, locking, planner.
+- App-layer caching / Redis / Kafka as products; only Postgres-as-queue via `SKIP LOCKED` is in scope.
+- Cloud-vendor console clicks — we give the SQL/params, not the RDS/Cloud SQL UI path.
+
+Deep dives: [schema-and-indexing](references/schema-and-indexing.md) (types, constraints, every index
+kind, bloat) · [query-optimization](references/query-optimization.md) (EXPLAIN, joins, concurrency,
+JSONB/FTS/pgvector) · [migrations](references/migrations.md) (zero-downtime DDL, per-ORM) ·
+[operations-and-security](references/operations-and-security.md) (roles, RLS, pooling, vacuum,
+partitioning, backups).
+
+## Non-negotiables
+
+1. `timestamptz` always for events; store UTC. Never naive `timestamp`.
+2. Money is `numeric(19,4)`, never `float`/`double precision`.
+3. Every FK gets a covering index — Postgres does **not** auto-index FK columns.
+4. `text` + `CHECK (length(...) <= n)`, not `varchar(n)` as a length hack.
+5. Index creation on a live table is **always** `CONCURRENTLY` (so it cannot run inside a txn).
+6. Never `ADD COLUMN ... NOT NULL` without a default/backfill plan; never add a volatile default on a large table without a batched backfill.
+7. Read the plan before adding an index: `EXPLAIN (ANALYZE, BUFFERS)` or it didn't happen.
+8. Migrations are forward-only in prod; never edit an applied migration.
+9. `SET lock_timeout` + `SET statement_timeout` around DDL on hot tables.
+10. RLS is opt-in per table and the **table owner bypasses it** — verify with a non-owner role (use `FORCE ROW LEVEL SECURITY` for the owner too).
+
+## Decision rules
+
+Fast lookups; runnable DDL lives in the references.
+
+### Pick the column type
+
+| Use case | Correct type | Avoid | Why |
+| --- | --- | --- | --- |
+| Surrogate PK (internal) | `bigint GENERATED ALWAYS AS IDENTITY` | `serial`, `int` | identity is SQL-standard, no sequence-ownership gotchas; `bigint` avoids 2.1B overflow |
+| Surrogate PK (public/distributed) | `uuid` v7 | `uuid` v4 | v7 is time-ordered → less B-tree fragmentation than random v4 |
+| Natural text id (slug, sku) | `text` + `UNIQUE` + `CHECK` | `varchar(n)` | length via CHECK; no rewrite to widen later |
+| Money / exact decimal | `numeric(19,4)` | `float8`, `money` | binary floats drift; `money` has locale issues |
+| Timestamp (event) | `timestamptz` | `timestamp` | stores a UTC instant; naive timestamp loses zone |
+| Duration | `interval` | int seconds | self-documenting, arithmetic-safe |
+| Small closed set, stable | `enum` | `text` w/o CHECK | type safety; but see lookup-table note |
+| Evolving set, joinable | lookup table + FK | `enum` | `ALTER TYPE ... ADD VALUE` is awkward; FK gives joins + soft-retire |
+| Flag | `boolean` | `int`, `varchar` | three-valued NULL still possible — add `NOT NULL DEFAULT` |
+| Tags (read-mostly) | `text[]` + GIN | comma string | array ops + GIN containment |
+| Tags (relational) | join table | `text[]` | when you need FK integrity / per-tag rows |
+| Semi-structured | `jsonb` | `json`, `text` | binary, indexable, dedup keys; promote hot keys to columns |
+| IP / CIDR | `inet` / `cidr` | `text` | validation + operators |
+| Time range (booking) | `tstzrange` + GiST | two columns | `&&` overlap + exclusion constraint |
+
+### Pick the index
+
+| Access pattern | Index | DDL | Notes |
+| --- | --- | --- | --- |
+| `=` / `<` `>` / range / `ORDER BY` | btree (default) | `CREATE INDEX ix_orders_status ON orders (status)` | also enforces uniqueness |
+| `LIKE 'prefix%'` | btree + `text_pattern_ops` | `CREATE INDEX ix_users_email_pat ON users (email text_pattern_ops)` | only for C-locale/prefix; not `%suffix` |
+| Case-insensitive eq | expr index or `citext` | `CREATE INDEX ix_users_lemail ON users (lower(email))` | query must use `lower(email)` too |
+| `@>` jsonb / array containment | GIN | `CREATE INDEX ix_orders_meta ON orders USING gin (meta)` | `jsonb_path_ops` if only `@>` |
+| Full-text `@@` | GIN on tsvector | `CREATE INDEX ix_orders_search ON orders USING gin (search)` | index a generated `tsvector` column |
+| Range overlap / exclusion / geo | GiST | `CREATE INDEX ix_book_during ON bookings USING gist (during)` | also PostGIS geometry |
+| Huge append-only time-series | BRIN | `CREATE INDEX ix_events_ts ON events USING brin (created_at)` | needs physical correlation |
+| Vector similarity | hnsw (pgvector) | `CREATE INDEX ix_docs_embed ON docs USING hnsw (embedding vector_cosine_ops)` | see query-optimization |
+| Dedup only | unique btree | `CREATE UNIQUE INDEX uq_users_email ON users (email)` | constraint = index |
+
+Hash indexes: almost never — equality-only, no multicolumn, rarely beats btree even though WAL-logged
+since PG10.
+
+### When NOT to add an index
+
+- Low-selectivity boolean / `status` with few distinct values (planner ignores it; seq scan wins).
+- Tiny tables (a seq scan reads one page; the index adds maintenance for nothing).
+- Write-heavy columns rarely filtered — every index is a write tax.
+- A column already the **left prefix** of an existing composite index.
+- Redundant with a `UNIQUE` constraint — the constraint already created an index.
+
+## Copy-paste patterns
+
+### Canonical table (types + constraints + identity)
+
+```sql
+-- GOOD: identity PK, public uuid, FK with action, numeric money, timestamptz,
+-- status via lookup FK, generated tsvector, CHECK constraints.
+CREATE TABLE orders (
+    id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    public_id    uuid NOT NULL DEFAULT gen_random_uuid(),  -- v4; see schema ref for v7
+    user_id      bigint NOT NULL REFERENCES users (id) ON DELETE RESTRICT,
+    status       text NOT NULL REFERENCES order_statuses (code) ON UPDATE CASCADE,
+    amount       numeric(19,4) NOT NULL CHECK (amount >= 0),
+    currency     text NOT NULL CHECK (length(currency) = 3),
+    note         text,
+    search       tsvector GENERATED ALWAYS AS (to_tsvector('simple', coalesce(note, ''))) STORED,
+    created_at   timestamptz NOT NULL DEFAULT now(),
+    updated_at   timestamptz NOT NULL DEFAULT now(),
+    UNIQUE (public_id)
+);
+CREATE INDEX ix_orders_user_id ON orders (user_id);     -- FKs are NOT auto-indexed
+CREATE INDEX ix_orders_status  ON orders (status);
+```
+
+```sql
+-- BAD: every column is a future migration or a bug.
+CREATE TABLE orders (
+    id          serial PRIMARY KEY,            -- sequence-ownership gotchas; use IDENTITY
+    user_id     int REFERENCES users(id),      -- int overflows at 2.1B; no FK index
+    status      varchar(20),                   -- length hack; no constraint on values
+    amount      float,                         -- money drift
+    created_at  timestamp DEFAULT now()        -- naive: loses the zone
+);
+```
+
+`updated_at` is not auto-maintained — add a `BEFORE UPDATE` trigger (see schema ref) or set it in the
+app; Postgres has no `ON UPDATE` clause.
+
+### Composite index column order
+
+Equality columns first, then the range/sort column.
+
+```sql
+-- Query: WHERE user_id = $1 AND created_at >= $2 ORDER BY created_at DESC
+-- GOOD: equality (user_id) then range (created_at)
+CREATE INDEX ix_orders_user_created ON orders (user_id, created_at DESC);
+
+-- BAD: range-first index cannot satisfy the equality efficiently for this query
+CREATE INDEX ix_orders_created_user ON orders (created_at, user_id);
+```
+
+Confirm with `EXPLAIN` that the plan shows `Index Cond: (user_id = ... AND created_at >= ...)`, not a
+`Filter:`.
+
+### Partial + covering (INCLUDE) index
+
+```sql
+-- Partial: index only the rows you query (smaller, hotter)
+CREATE INDEX ix_orders_active ON orders (user_id, created_at DESC)
+WHERE status <> 'cancelled';
+
+-- Covering: INCLUDE non-key columns to enable an index-only scan
+CREATE INDEX ix_orders_user_cover ON orders (user_id) INCLUDE (amount, created_at);
+```
+
+Index-only scan requires a recently-`VACUUM`ed table; confirm `Heap Fetches: 0` in `EXPLAIN (ANALYZE)`.
+
+### Keyset (cursor) pagination — not OFFSET
+
+```sql
+-- GOOD: keyset on a stable composite sort; uses ix_orders_user_created
+SELECT id, amount, created_at
+FROM orders
+WHERE user_id = $1
+  AND (created_at, id) < ($2, $3)   -- row-value comparator = last row of prev page
+ORDER BY created_at DESC, id DESC
+LIMIT 20;
+
+-- BAD: OFFSET scans and discards 100000 rows every page (O(n))
+SELECT * FROM orders WHERE user_id = $1 ORDER BY created_at DESC LIMIT 20 OFFSET 100000;
+```
+
+The index must match the `ORDER BY` direction exactly; include the tiebreaker (`id`).
+
+### UPSERT done right
+
+```sql
+-- GOOD: insert-or-update; EXCLUDED is the row that failed to insert
+INSERT INTO inventory (sku, qty)
+VALUES ($1, $2)
+ON CONFLICT (sku)
+DO UPDATE SET qty = inventory.qty + EXCLUDED.qty
+WHERE inventory.qty + EXCLUDED.qty >= 0   -- guard
+RETURNING id, qty;
+
+-- DO NOTHING returns no row on conflict; wrap to always get the row:
+WITH ins AS (
+    INSERT INTO tags (name) VALUES ($1)
+    ON CONFLICT (name) DO NOTHING
+    RETURNING id
+)
+SELECT id FROM ins
+UNION ALL
+SELECT id FROM tags WHERE name = $1 LIMIT 1;
+```
+
+### Queue with SKIP LOCKED
+
+```sql
+-- GOOD: contention-free job claim; concurrent workers never block each other
+UPDATE jobs
+SET status = 'processing', locked_at = now()
+WHERE id = (
+    SELECT id FROM jobs
+    WHERE status = 'pending'
+    ORDER BY created_at
+    FOR UPDATE SKIP LOCKED
+    LIMIT 1
+)
+RETURNING id, payload;
+```
+
+`SKIP LOCKED` skips rows another txn holds; `FOR UPDATE` alone would serialize all workers.
+
+### Kill the N+1
+
+```sql
+-- BAD: application loops, one query per order (N+1)
+--   for o in orders: SELECT * FROM order_items WHERE order_id = o.id
+-- GOOD: one set-based query
+SELECT o.id, json_agg(i.*) AS items
+FROM orders o
+JOIN order_items i ON i.order_id = o.id
+WHERE o.user_id = $1
+GROUP BY o.id;
+
+-- Top-N-per-group: JOIN LATERAL, not a window-filter scan
+SELECT u.id, recent.*
+FROM users u
+JOIN LATERAL (
+    SELECT id, amount, created_at FROM orders
+    WHERE user_id = u.id ORDER BY created_at DESC LIMIT 3
+) recent ON true;
+```
+
+An ORM emitting N queries is the same bug — fix it at the SQL boundary, not with a cache.
+
+### EXPLAIN, the right way
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, SETTINGS, FORMAT TEXT)
+SELECT * FROM orders WHERE user_id = $1 AND created_at >= $2;
+```
+
+Read these four first:
+
+1. **Estimated vs actual rows** — a large gap means stale stats; run `ANALYZE`.
+2. **The most expensive node** — highest `actual time` × `loops`.
+3. **`Seq Scan` on a big table** where you expected an index.
+4. **`Rows Removed by Filter`** — the predicate was not pushed to an index.
+
+Full method in [query-optimization](references/query-optimization.md).
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality → STOP |
+| --- | --- |
+| "I'll add the FK index later, the query works now" | Unindexed FK = seq scan + heavy lock cascade on parent `DELETE`/`UPDATE`. Index it now. |
+| "UUID PK is fine everywhere" | Random v4 fragments the B-tree and bloats WAL. Use `IDENTITY` internally or uuid **v7**. |
+| "`SELECT count(*)` to check existence" | Counts the whole match. Use `EXISTS (SELECT 1 ...)`. |
+| "CTEs are just for readability" | Pre-12 they were optimization fences; PG12+ inlines unless `MATERIALIZED`. Know which you want. |
+| "`NOT IN (subquery)`" | NULL-unsafe (one NULL → empty result) and slow. Use `NOT EXISTS`. |
+| "Store money as float, round on display" | Silent drift across arithmetic. `numeric(19,4)`. |
+| "`ADD COLUMN ... NOT NULL DEFAULT now()`" | Volatile default rewrites the table under ACCESS EXCLUSIVE. Non-volatile constant is instant (PG11+). |
+| "One big `jsonb` blob beats columns" | No constraints, no per-key stats, GIN bloat. Promote hot keys to typed columns. |
+| "RLS policy calling `auth.uid()` per row" | Re-evaluated per row. Wrap: `(SELECT auth.uid())` so it runs once. |
+| "`CREATE INDEX` in the migration is fine" | Blocks writes for the whole build. `CREATE INDEX CONCURRENTLY` (outside a txn). |
+| "`VACUUM FULL` will fix bloat" | Takes ACCESS EXCLUSIVE, rewrites the table. Use autovacuum tuning / `REINDEX CONCURRENTLY`. |
+
+## Quick reference
+
+### Isolation levels
+
+| Level | Prevents | Use when | Note |
+| --- | --- | --- | --- |
+| Read Committed (default) | dirty reads | most OLTP | each statement sees a fresh snapshot |
+| Repeatable Read | + non-repeatable / phantom (snapshot) | multi-statement consistent read | may raise `40001`; retry |
+| Serializable (SSI) | + write skew | invariants across rows | retry `40001` with backoff |
+
+Retry the txn on SQLSTATE `40001` (serialization_failure) and `40P01` (deadlock_detected).
+
+### Lock modes (DDL)
+
+`CREATE INDEX CONCURRENTLY` takes SHARE UPDATE EXCLUSIVE (allows writes); plain `CREATE INDEX`,
+`ALTER TABLE ... TYPE`, `ADD COLUMN` with a volatile default, and `VACUUM FULL` take ACCESS EXCLUSIVE
+(blocks everything). Full table in [migrations](references/migrations.md#lock-impact-reference).
+
+### Diagnostic one-liners
+
+```sql
+-- Unindexed foreign keys
+SELECT c.conrelid::regclass AS tbl, a.attname AS col
+FROM pg_constraint c
+JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY (c.conkey)
+WHERE c.contype = 'f'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_index i
+    WHERE i.indrelid = c.conrelid AND (i.indkey::int2[])[0] = a.attnum
+  );
+
+-- Top slow queries (needs pg_stat_statements)
+SELECT calls, round(mean_exec_time::numeric, 2) AS mean_ms,
+       round(total_exec_time::numeric, 2) AS total_ms, query
+FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 20;
+
+-- Dead tuples / bloat candidates
+SELECT relname, n_dead_tup, n_live_tup, last_autovacuum
+FROM pg_stat_user_tables WHERE n_dead_tup > 1000 ORDER BY n_dead_tup DESC;
+
+-- Blocking locks
+SELECT blocked.pid AS blocked_pid, blocking.pid AS blocking_pid, blocked.query AS blocked_query
+FROM pg_stat_activity blocked
+JOIN pg_locks bl ON bl.pid = blocked.pid AND NOT bl.granted
+JOIN pg_locks gl ON gl.locktype = bl.locktype AND gl.database IS NOT DISTINCT FROM bl.database
+  AND gl.relation IS NOT DISTINCT FROM bl.relation AND gl.granted
+JOIN pg_stat_activity blocking ON blocking.pid = gl.pid;
+
+-- Cache hit ratio (aim > 0.99)
+SELECT sum(heap_blks_hit) / nullif(sum(heap_blks_hit + heap_blks_read), 0) AS ratio
+FROM pg_statio_user_tables;
+
+-- Unused indexes
+SELECT relname, indexrelname, idx_scan
+FROM pg_stat_user_indexes WHERE idx_scan = 0 ORDER BY relname;
+```
+
+## Verify
+
+Run `scripts/verify.sh` from your project root. It lints discovered SQL with `sqlfluff` (if
+configured), syntax-sanity-checks migration files (the quote/paren balance check is dollar-quote and
+block-comment aware) and flags foot-guns (`CREATE INDEX` without `CONCURRENTLY` in a migration,
+`ADD COLUMN ... NOT NULL` without `DEFAULT`, `VACUUM FULL`), and — only if `DATABASE_URL` and `psql`
+are present — checks that `pg_stat_statements` is enabled. It exits non-zero **only** on a real
+`sqlfluff` lint error; everything else (missing tools, heuristic quote/paren warnings, DB unreachable)
+is advisory `[skip]`/`[warn]`, never a failure. Runs on stock macOS bash 3.2; it never writes and
+never connects without `DATABASE_URL`.
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+When this skill runs in a project with a `02-DOCS/` layer (the
+[`harness`](../harness/SKILL.md) Karpathy wiki), record this
+project's database decisions there and index them from the root `CLAUDE.md`, so the next
+agent inherits the conventions instead of re-deriving them.
+
+1. **Find the article** `02-DOCS/wiki/stack/postgresdb.md`, linked from a `## Knowledge map` section in the root
+   `CLAUDE.md`.
+2. **If missing or stale**, create/update it with the project's real choices — schema and naming conventions, the migration tool, indexing/partitioning decisions, the pooling setup, and any RLS policies —
+   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
+   `CLAUDE.md` itself, if absent).
+3. **Read it first on every use** and stay consistent; when a convention changes, update the
+   article (bump its `Updated` date) in the same change.
+
+No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Unlike the
+brand study, technical conventions are *recorded, not gated* — never block the task on this.
+
+## See Also
+
+- [references/schema-and-indexing.md](references/schema-and-indexing.md) — types, constraints, all index kinds, bloat.
+- [references/query-optimization.md](references/query-optimization.md) — EXPLAIN, joins, concurrency, JSONB/FTS/pgvector.
+- [references/migrations.md](references/migrations.md) — zero-downtime DDL, lock-impact table, per-ORM.
+- [references/operations-and-security.md](references/operations-and-security.md) — roles, RLS, pooling, vacuum, partitioning, backups.
+- Sibling skills: [`harness`](../harness/SKILL.md) (scaffolds the `01-TOOLS/POSTGRES` operational tool). Stack siblings: [`fastapi`](../fastapi/SKILL.md), [`nextjs`](../nextjs/SKILL.md), [`go`](../go/SKILL.md), [`flutter`](../flutter/SKILL.md), [`secure-coding`](../secure-coding/SKILL.md), [`deployment`](../deployment/SKILL.md).
+- Out of scope here — these are external tools with their own upstream documentation, not skills in this collection: ORM-surface traps (Prisma's `updateMany` count, serverless connection exhaustion) and per-runner migration wiring (Prisma, Alembic, golang-migrate, Drizzle, …). This skill owns the engine-level SQL and migration mechanics those tools sit on top of; for the tool's own API/CLI, read that tool's docs.

package/skills/postgresdb/evals/README.md

@@ -0,0 +1,55 @@
+# Eval harness — `postgresdb`
+
+This harness checks two things: **triggering** (does the skill fire on the right
+prompts and stay quiet on near-misses?) and **capability** (does loading the skill
+measurably improve the answer?). Cases live in `cases.yaml`. These run through an
+**agent harness**, not a pure shell script — a human or a driver agent feeds prompts
+and grades outputs. Keep grading honest.
+
+## 1. Triggering
+
+For each prompt in `cases.yaml`:
+
+1. Start a fresh agent session with **only the `postgresdb` skill** discoverable
+   (its `SKILL.md` description in scope; no sibling skills loaded).
+2. Paste the prompt verbatim. Observe whether the agent invokes / routes to
+   `postgresdb`.
+3. Run **3–5 trials per prompt** (the trigger decision is stochastic).
+4. Score:
+   - `should_trigger`: PASS if the skill fires in the majority of trials.
+   - `should_not_trigger`: PASS if the skill does **not** fire. When the case names
+     a `route_to` sibling, sanity-check the agent would plausibly route there (or to
+     `none`); a wrong-but-not-postgresdb route still passes this skill's gate.
+
+**Pass bar:** ≥ 90% trigger accuracy across all `should_trigger` + `should_not_trigger`
+prompts (i.e. at most ~1 miss out of the 14 cases). A `should_trigger` that fires < 50%
+of trials is a fail; a `should_not_trigger` that fires at all in a majority of trials is
+a fail.
+
+## 2. Capability
+
+For each `capability` scenario, run it **twice**:
+
+- **WITHOUT** the skill: a clean agent, no `postgresdb` skill available.
+- **WITH** the skill: same prompt, `postgresdb` loaded.
+
+Grade each transcript against that scenario's `must_include` checklist — one point per
+bullet that is correctly and specifically covered (not just name-dropped). Compute
+coverage = points / total bullets.
+
+**Pass bar:**
+- WITH the skill: ≥ 80% of `must_include` bullets covered.
+- The skill must **measurably improve** the output: WITH coverage should clearly beat
+  WITHOUT (target ≥ +30 percentage points, or crossing from fail→pass). If a baseline
+  agent already nails the rubric without the skill, the rubric is too easy — tighten it.
+
+## Notes
+
+- Prompts are deliberately varied: some never say "Postgres", "SQL", or "index"
+  (slow-query, multi-tenant isolation, duplicate-job-processing) — these test intent
+  recognition, not keyword matching.
+- Near-misses route to the genuinely correct sibling (`fastapi`, `flutter`,
+  `deployment`, `secure-coding`) or `none` when the request is out of every sibling's
+  scope (Prisma ORM trap, Redis caching).
+- This is judgment-based grading. Record trial counts and the per-bullet verdicts so a
+  reviewer can audit; don't report a bare pass/fail.