rsc-universal 0.1.1

package/skills/db-migrations/references/expand-contract-playbook.md

@@ -0,0 +1,152 @@
+# Expand-contract playbook
+
+Ordered deploy/migrate checklists for the common changes. Every example DDL sets `lock_timeout` first
+and uses the non-blocking path, so it is safe to ship as written. Each phase is a **separate deploy**;
+the cooling period between *switch reads* and *contract* is what preserves a no-schema-change rollback.
+
+Notation: `M` = a migration (schema change), `A` = an app deploy. They alternate.
+
+---
+
+## Add a `NOT NULL` column
+
+A single `ADD COLUMN ... NOT NULL DEFAULT <expr>` or `SET NOT NULL` validates/rewrites the whole table
+under lock. Split it.
+
+1. **M1 (expand)** — add the column nullable; metadata-only.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE users ADD COLUMN status text;
+   ```
+2. **A1** — app dual-writes `status` on every insert/update (defaults it in code).
+3. **Backfill** — fill historical rows in batches (see `backfill-and-batching.md`).
+4. **M2** — add the constraint without a blocking scan, then validate, then flip `NOT NULL`.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE users ADD CONSTRAINT users_status_nn CHECK (status IS NOT NULL) NOT VALID;
+   ALTER TABLE users VALIDATE CONSTRAINT users_status_nn;
+   ALTER TABLE users ALTER COLUMN status SET NOT NULL;
+   ```
+   On PG 12+, a validated `CHECK (col IS NOT NULL)` lets `SET NOT NULL` skip its own full scan.
+
+---
+
+## Rename a column
+
+The running app reads the old name, so you cannot rename in place. Run a dual-name window.
+
+1. **M1 (expand)** — add the new column nullable.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE users ADD COLUMN email_address text;
+   ```
+2. **A1** — write BOTH `email` and `email_address`; keep READING `email`.
+3. **Backfill** `email_address` from `email` in batches; verify counts/checksum.
+4. **A2** — read `email_address`; still dual-write both. **Cooling period starts.**
+5. **M2 (contract)** — days later, after the new app has run clean.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE users DROP COLUMN email;
+   ```
+
+A view aliasing the new column to the old name can shorten the app-side change, but it does not remove
+the need for the cooling period.
+
+---
+
+## Split one column into two
+
+Example: `full_name` → `first_name`, `last_name`.
+
+1. **M1** — add both new columns nullable.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE people ADD COLUMN first_name text;
+   ALTER TABLE people ADD COLUMN last_name text;
+   ```
+2. **A1** — on write, populate all three (`full_name` plus the two parts).
+3. **Backfill** the split for historical rows; verify a reconstructed `full_name` matches the original.
+4. **A2** — read the split columns; keep writing `full_name` through the cooling period.
+5. **M2 (contract)** — drop `full_name` after cooling.
+
+Merging two columns into one is the same shape with the directions reversed.
+
+---
+
+## Change a column type
+
+A non-trivial type change rewrites every row and can invalidate the running app's expectations. Treat it
+as a rename to a new column.
+
+1. **M1** — add the new column with the target type, nullable.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE orders ADD COLUMN amount_cents bigint;
+   ```
+2. **A1** — dual-write both old and new; read the old.
+3. **Backfill** with the conversion expression in batches; verify.
+4. **A2** — read the new column; keep dual-writing.
+5. **M2 (contract)** — drop the old column after cooling.
+
+This avoids the in-place `ALTER COLUMN ... TYPE`, which takes an exclusive lock and rewrites under it
+(and, with a `USING` expression, can fail mid-rewrite on bad data).
+
+---
+
+## Drop a column or table
+
+Dropping is a *contract* step, never the first move — the running app may still reference it.
+
+1. **A1** — ship an app version that no longer reads or writes the target.
+2. Wait the cooling period; confirm via logs/metrics that nothing touches it.
+3. **M1 (contract)** — drop it.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE users DROP COLUMN legacy_flag;
+   ```
+
+`DROP COLUMN` is metadata-only and fast in Postgres, but the lock it needs is brief-yet-exclusive, so
+keep `lock_timeout` short and retry rather than queue behind a long transaction.
+
+---
+
+## Add a foreign key
+
+`ADD CONSTRAINT ... FOREIGN KEY` validates every existing row under lock. Split validation off.
+
+1. Ensure the referenced column is indexed/unique (add that index `CONCURRENTLY` first if missing).
+2. **M1** — add the constraint as `NOT VALID` (instant; only new/changed rows are checked).
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE orders
+     ADD CONSTRAINT orders_user_fk FOREIGN KEY (user_id) REFERENCES users (id) NOT VALID;
+   ```
+3. **M2** — validate existing rows without blocking writes.
+   ```sql
+   ALTER TABLE orders VALIDATE CONSTRAINT orders_user_fk;
+   ```
+
+If validation reveals orphan rows, that is a data-correctness problem — clean it before validating
+(see `../../data-cleaning/SKILL.md`), do not loosen the constraint.
+
+---
+
+## Add an index on a live table
+
+Plain `CREATE INDEX` holds a SHARE lock and blocks writes for the whole build — the classic "our deploy
+deadlocks when we add an index" symptom.
+
+```sql
+-- This statement must NOT run inside a transaction block.
+CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders (user_id);
+```
+
+A failed `CONCURRENTLY` build leaves an INVALID index. Find it and rebuild:
+
+```sql
+DROP INDEX CONCURRENTLY idx_orders_user_id;
+CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders (user_id);
+```
+
+How to make a runner skip its transaction wrapper for this one statement is in `tools-and-runners.md`.
+For Postgres lock-level semantics (which lock blocks what), see `../../postgresdb/SKILL.md`.

package/skills/db-migrations/references/tools-and-runners.md

@@ -0,0 +1,88 @@
+# Tools and runners (2026)
+
+This skill is engine- and runner-neutral; this file is the lookup for *which* tool and *how* to make it
+run the unsafe-by-default step safely. Versions are current as of 2026-06.
+
+## Versioned vs declarative
+
+- **Versioned** runners replay an ordered list of scripts (V1, V2, …). You write each step; the runner
+  tracks which have run. Flyway, Liquibase, Alembic, golang-migrate, drizzle-kit.
+- **Declarative** (schema-as-code) tools take your *target* schema and compute the diff to get there.
+  Atlas is the main one. You review the planned diff; you do not hand-write each `ALTER`.
+
+Declarative removes drift and hand-written DDL errors, but the *sequencing* in this skill still applies —
+a planned diff that drops then re-adds a column, or adds `NOT NULL` in one shot, is still an outage. Read
+the plan before you apply it.
+
+## Stack → tool
+
+| Stack / need | Tool | Version (2026-06) | Note |
+|---|---|---|---|
+| JVM, SQL-first, many DBs | Flyway | 12.6.x (12.6.1, May 2026) | Version-based, 50+ DBs. Redgate dropped the Teams tier in 2025, pushing to Enterprise / Native Connectors. |
+| Max format flexibility | Liquibase | current | SQL/XML/YAML/JSON changelogs; most flexible, most verbose. |
+| Python / SQLAlchemy | Alembic | 1.18.x (1.18.4, Feb 2026) | Requires Python ≥ 3.10; plugin system since 1.18.0. |
+| Go | golang-migrate | current | The Go standard; up/down SQL files. |
+| TypeScript / Drizzle | drizzle-kit | current | Runner mechanics in `../../drizzle-orm/SKILL.md`; safety sequence here. |
+| Schema-as-code, planned diffs | Atlas | current | Declarative — give it the target, review the diff. |
+| Vitess / PlanetScale | branch + deploy request | — | Online DDL built into the workflow; see `../../planetscale/SKILL.md`. |
+| Big MySQL `ALTER`, native online DDL can't keep it online | gh-ost or pt-osc | — | See below. |
+
+## Running a statement OUTSIDE the per-migration transaction
+
+`CREATE INDEX CONCURRENTLY` (and `DROP INDEX CONCURRENTLY`, `ALTER TYPE ... ADD VALUE` on older PG)
+**cannot run inside a transaction block**, but most runners wrap each migration in `BEGIN/COMMIT` by
+default. Opt the offending migration out:
+
+- **Flyway** — name the script with the `B`/`transactional=false` setting, or set
+  `flyway.executeInTransaction=false` (per-script via a `-- flyway:` config callback / config file).
+- **Alembic** — set `transaction_per_migration` appropriately and, for the autogenerate path, emit the
+  statement with `op.execute(...)` after committing; the common pattern is
+  `with op.get_context().autocommit_block(): op.execute("CREATE INDEX CONCURRENTLY ...")`.
+- **Django** — add `atomic = False` to the `Migration` class (or use `AddIndexConcurrently` from
+  `django.contrib.postgres.operations`).
+- **Rails** — `disable_ddl_transaction!` in the migration, then `add_index ..., algorithm: :concurrently`.
+- **golang-migrate** — split the concurrent statement into its own migration file; migrate runs each file
+  without wrapping when the statement requires it (keep one statement per file).
+- **drizzle-kit** — generate the SQL, then hand-edit the migration so the concurrent statement stands
+  alone; details in `../../drizzle-orm/SKILL.md`.
+
+## gh-ost vs pt-osc (big MySQL ALTER)
+
+Both copy the table into a new shape and swap it in, so a large `ALTER` does not hold a long metadata
+lock. They differ in *how* they capture concurrent writes:
+
+| | gh-ost | pt-online-schema-change |
+|---|---|---|
+| Change capture | Triggerless — reads the binlog | Trigger-based — triggers on the original table |
+| Consistency | Eventual (binlog replay) | Strict (synchronous triggers) |
+| Write overhead | Lower; no triggers on the hot table | Higher; every write fires a trigger |
+| Throttling | Throttles on replica lag; easy pause/resume | Throttles, but triggers can fail to get the metadata lock under heavy concurrency / long transactions |
+| Cutover control | Fine-grained, can postpone | Less granular |
+
+**Prefer gh-ost on a very busy master** — triggerless means no write amplification on the hot path, and
+the lag-aware throttle plus postponable cutover are easier to operate. Reach for pt-osc when you need
+strict synchronous consistency and the write volume is modest enough that trigger overhead and
+metadata-lock contention are not a concern.
+
+## CI gate — Squawk
+
+**Squawk** is the standard static linter for Postgres migration SQL. Run it in CI so a bare
+`CREATE INDEX`, a one-shot `NOT NULL`, a blocking constraint add, or a column drop fails the PR before
+review.
+
+```yaml
+# .github/workflows/migrations.yml (excerpt)
+- name: Lint migrations
+  run: npx squawk@latest migrations/*.sql
+```
+
+```toml
+# .squawk.toml — example: keep the dangerous rules on, silence ones you handle out of band
+[lint]
+excluded_rules = []   # start strict; add an id here only with a written reason
+# e.g. "prefer-robust-stmts" enforces lock_timeout + CONCURRENTLY patterns
+```
+
+`scripts/verify.sh` in this skill runs the same class of static checks (no DB connection) against the
+example migrations shipped in these references, so the skill stays self-consistent with what it tells you
+to gate on.

package/skills/db-migrations/scripts/verify.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — db-migrations skill gate.
+#
+# This is a self-consistency + artifact-shape check on the skill's OWN files, not a live DB check.
+# It NEVER connects to a database and NEVER writes anything.
+#
+# What it asserts:
+#   1. The skill ships a Squawk / migration-lint reference (CI gate the body tells you to add).
+#   2. SKILL.md documents each forbidden DDL pattern as a Bad->Good (lock_timeout, CONCURRENTLY,
+#      multi-step NOT NULL, batched backfill).
+#   3. Example .sql shipped in references/ is itself safe — none of the danger signatures the body
+#      forbids: bare CREATE INDEX (no CONCURRENTLY), an ALTER that is missing lock_timeout, or
+#      ADD COLUMN ... NOT NULL without the multi-step path. (DROP INDEX CONCURRENTLY is exempt from
+#      the lock_timeout rule; it manages its own locking.)
+#
+# Exit code: non-zero only if the skill's own artifacts are inconsistent with what the body teaches.
+# An empty / missing references dir is a clean skip, not a failure (exit 0).
+#
+# Portable to stock macOS bash 3.2: no mapfile, no associative arrays; arrays are initialised so they
+# expand safely under `set -u`.
+
+GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+# Resolve the skill root from this script's location, so the gate works from any CWD.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+SKILL_MD="$SKILL_DIR/SKILL.md"
+REF_DIR="$SKILL_DIR/references"
+
+# ---- 1. SKILL.md documents the safe patterns ----
+if [ -f "$SKILL_MD" ]; then
+  needles=(
+    "lock_timeout"
+    "CONCURRENTLY"
+    "NOT VALID"
+    "VALIDATE CONSTRAINT"
+    "Squawk"
+  )
+  missing=""
+  for n in "${needles[@]}"; do
+    grep -Fq "$n" "$SKILL_MD" || missing="$missing $n"
+  done
+  if [ -n "$missing" ]; then
+    fail "SKILL.md is missing required safe-migration concepts:$missing"
+  else
+    ok "SKILL.md documents lock_timeout, CONCURRENTLY, NOT VALID/VALIDATE, Squawk"
+  fi
+  # The body must show a Bad->Good contrast (it teaches by counter-example).
+  if grep -Eq -- '--[[:space:]]*Bad' "$SKILL_MD" && grep -Eq -- '--[[:space:]]*Good' "$SKILL_MD"; then
+    ok "SKILL.md shows Bad->Good DDL contrasts"
+  else
+    fail "SKILL.md should contrast a Bad vs Good DDL fence"
+  fi
+else
+  fail "SKILL.md not found at $SKILL_MD"
+fi
+
+# ---- 2. Squawk / lint reference is shipped ----
+if [ -d "$REF_DIR" ] && grep -rIlq -- "squawk" "$REF_DIR" 2>/dev/null; then
+  ok "references/ ship a Squawk migration-lint reference"
+elif [ -d "$REF_DIR" ]; then
+  fail "references/ exist but no Squawk lint reference found (the body's CI gate is undocumented)"
+else
+  skip "no references/ dir — nothing to lint-reference yet"
+fi
+
+# ---- 3. Example .sql in references/ is itself safe ----
+SQL_FILES=()
+if [ -d "$REF_DIR" ]; then
+  while IFS= read -r -d '' f; do
+    SQL_FILES+=("$f")
+  done < <(find "$REF_DIR" -type f -name '*.sql' -print0 2>/dev/null)
+fi
+
+# The references ship example DDL inside fenced code blocks, not standalone .sql files. If real .sql
+# files exist, scan them; otherwise this is a clean skip (no false failure on an empty target).
+if [ "${#SQL_FILES[@]}" -eq 0 ]; then
+  skip "no standalone .sql files in references/ to scan (examples live in fenced code blocks)"
+else
+  for f in "${SQL_FILES[@]}"; do
+    # Strip line comments so a "-- Bad: ..." annotation never trips the scanner.
+    body="$(sed -e 's/--.*$//' "$f")"
+
+    # bare CREATE INDEX without CONCURRENTLY
+    if printf '%s' "$body" | grep -Eiq 'create[[:space:]]+(unique[[:space:]]+)?index' \
+       && ! printf '%s' "$body" | grep -Eiq 'create[[:space:]]+(unique[[:space:]]+)?index[[:space:]]+concurrently'; then
+      fail "$f: CREATE INDEX without CONCURRENTLY"
+    fi
+
+    # ADD COLUMN ... NOT NULL in one shot (the multi-step path uses a separate NOT VALID CHECK)
+    if printf '%s' "$body" | grep -Eiq 'add[[:space:]]+column[^;]*not[[:space:]]+null'; then
+      fail "$f: ADD COLUMN ... NOT NULL in a single statement"
+    fi
+
+    # any ALTER TABLE that is not preceded anywhere in the file by a lock_timeout
+    if printf '%s' "$body" | grep -Eiq 'alter[[:space:]]+table' \
+       && ! printf '%s' "$body" | grep -Fiq 'lock_timeout'; then
+      fail "$f: ALTER TABLE without a lock_timeout in the same file"
+    fi
+  done
+  [ "$EXIT" -eq 0 ] && ok "example .sql in references/ is free of forbidden DDL signatures (${#SQL_FILES[@]} files)"
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else fail "verify.sh found inconsistencies"; fi
+exit "$EXIT"

package/skills/debug/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: debug
+description: "Use when something is broken and the impulse is to start patching — a bug, a failing or flaky test, a crash, an exception, a wrong result, a regression, or behavior nobody can explain — and you want the root cause found BEFORE any fix is proposed. The on-demand rsc-sdd diagnosis discipline: reproduce → isolate → hypothesize → fix → verify, callable from inside implement (or any phase) the moment a check fails for a reason you don't understand. Triggers: 'debug this', 'why is this failing', 'this test is flaky', 'find the root cause', 'it works locally but not in CI', 'this used to work', 'track down this bug', 'the fix didn't stick', 'figure out why', 'NullPointer/segfault/500 out of nowhere', 'intermittent failure'. It diagnoses and fixes the ONE confirmed cause, then hands back. NOT writing a planned feature (implement), NOT the lint/test gate (verify), NOT adversarial diff reading (review). Honors the harness accompaniment dial."
+tags: [debug, bug, troubleshoot]
+recommends: []
+profiles: [core, full]
+origin: risco
+---
+
+# debug — find the cause before you touch the fix
+
+`debug` is the on-demand diagnosis discipline of the rsc-sdd chain. Something is broken — a test
+went red, a crash landed, a result is wrong, a regression appeared — and the strongest pull in the
+room is to change code until the symptom disappears. That pull is the enemy. A symptom that vanishes
+under a guessed edit usually moved; it rarely died. This skill replaces guess-and-patch with a
+short, evidence-driven loop that ends only when **one confirmed cause** has been named, fixed, and
+proven gone.
+
+The one rule everything else serves: **no fix before a reproduced, isolated, confirmed cause.** If
+you cannot make the bug happen on demand, you cannot know you fixed it — you can only know the
+symptom stopped showing, which is not the same thing.
+
+This is a process skill. It does not own the test runner, the debugger, or the profiler — the
+**stack skills do** (`../fastapi/SKILL.md`, `../go/SKILL.md`, `../nextjs/SKILL.md`,
+`../flutter/SKILL.md`; data-layer issues `../postgresdb/SKILL.md`; security-shaped failures
+`../secure-coding/SKILL.md`). `debug` owns the *method*; it pulls the *mechanics* from whichever
+stack the failure lives in.
+
+## When to use / when not to
+
+Use when:
+
+- A test fails (or flakes) for a reason you don't fully understand, mid-`implement` or after.
+- A crash, exception, 500, segfault, or wrong output appears and nobody can yet say why.
+- A regression shows up ("this used to work") and you need the commit/change that caused it.
+- A fix was applied and the symptom came back, or a "fix" didn't actually stick.
+- The behavior differs between environments ("works locally, fails in CI").
+
+Do NOT use when:
+
+- You're writing a *planned* feature task and its expected failing test — that's `implement`'s
+  red→green→refactor; no mystery yet.
+- You're running the lint/type/test gate to confirm "done" — that's `verify` (it *reports* failures
+  and hands them here; it doesn't diagnose).
+- You're reading a clean diff adversarially for smells a test can't catch — that's `review`.
+- The "bug" is actually an unclear requirement or contradictory spec — that's `clarify`/`analyze`,
+  not a code defect.
+
+## Read the room first (accompaniment dial)
+
+Before diagnosing, read `02-DOCS/wiki/harness/user-profile.md` for the technical + accompaniment
+level and match it. The *method* never changes with the dial — the volume does.
+
+| Level | While diagnosing you show… | Questions you ask |
+| --- | --- | --- |
+| **L0** terse | the confirmed cause and the one-line fix, once found | none unless you need a missing repro detail |
+| **L1** brief | the cause + one line of *why* it produced this symptom | only what you can't observe yourself (e.g. exact error text) |
+| **L2** decisions | each step's finding (repro, the half that isolated it, the cause) | confirm before a fix that changes behavior beyond the bug |
+| **L3** full | narrate the whole loop, teach the binary-search reasoning aloud | ask to contextualize the environment, recent changes, expectations |
+
+No profile yet → assume non-technical, narrate the reasoning plainly, and never apply a
+behavior-changing fix without a quick confirm.
+
+## The loop — five steps, in order
+
+```text
+REPRODUCE   → make the bug happen on demand. A reliable repro (or a quantified flake rate) is the
+              entry ticket. No repro → you are not debugging yet, you are guessing. Capture the
+              exact command, input, env, and the verbatim error/stack.
+ISOLATE     → binary-search the cause. Halve the surface each step — git bisect across commits,
+              comment/branch to split code paths, remove inputs until the minimal failing case
+              remains. Change ONE variable at a time; note what each change does to the symptom.
+HYPOTHESIZE → from the isolated evidence, state ONE falsifiable cause: "X happens because Y, and if
+              so, changing Z will flip the result." A hypothesis you can't disprove isn't one.
+FIX         → make the smallest change that addresses the *cause* (not the symptom). First, encode
+              the bug as a failing test (it should now go red for the real reason) — then fix until
+              it's green. Treat the test as the proof the cause was real.
+VERIFY      → re-run the repro: symptom gone. Re-run the new test: green. Re-run the surrounding
+              suite: still green (no new red). For a flake, run it enough times to show the rate
+              dropped to zero. Only now is it fixed.
+```
+
+Never skip a step and never reorder. **Reproduce before isolate** — you can't bisect a bug you can't
+trigger. **Hypothesize before fix** — an edit with no stated cause is a guess wearing a commit
+message. **Verify before "fixed"** — the word *fixed* is a claim about the repro no longer firing
+and the test being green, nothing less.
+
+### Reproduce — the entry ticket
+
+A bug you cannot reproduce is not a bug you can fix; it's a rumor. Pin it down:
+
+- The **exact** invocation (command, request, UI steps), the input that triggers it, the environment
+  (OS, versions, env vars, branch/commit), and the **verbatim** error + stack trace — not a
+  paraphrase.
+- For a **flake**, reproduction means a *rate*: run it N times, record `k/N` failures. "Intermittent"
+  is a measurement to take, not a property to accept. A flake almost always means shared state, order
+  dependence, a real race, time/timezone, or network — name which.
+- If you genuinely cannot reproduce, that is the finding. Say so, gather more signal (logs, a failing
+  CI run, the user's exact steps), and do not apply a speculative fix to a bug you can't trigger.
+
+### Isolate — binary-search the surface
+
+The cause is somewhere in a large space; cut it in half, repeatedly, with evidence.
+
+- **Across history:** `git bisect` between a known-good and known-bad commit to land on the exact
+  change that introduced it. Let the repro be the bisect's good/bad oracle.
+- **Across code:** disable/short-circuit half the suspect path; see which half keeps the symptom.
+- **Across inputs/data:** shrink the failing input to the minimal case that still fails.
+- **One variable per step.** Two changes at once and you've learned nothing about either. Write down
+  what each step did to the symptom — the trail *is* the diagnosis.
+
+Delegate the stack-specific tooling (debugger, race detector, profiler, query plan) to the stack
+skill below; `debug` decides *what* to halve, the stack skill provides the instrument.
+
+### Hypothesize → Fix the cause, not the symptom
+
+State the cause as a sentence you could be wrong about, then act on it:
+
+- Fix the **cause**, not the symptom. A `try/except` that swallows the error, a retry that hides a
+  race, a `sleep` that papers over an ordering bug, a bumped timeout — these relocate the symptom and
+  leave the cause armed. If your fix doesn't reference the cause you named, it's a patch on a guess.
+- **Encode the bug as a test first.** The failing test that reproduces the bug is your regression
+  guard; watch it go red for the real reason, then make it green. A fix with no test means the next
+  change can resurrect the bug silently.
+- Keep the change **minimal**. Resist "while I'm here" refactors — they confound the verification and
+  bury the one line that mattered.
+
+### Verify — the symptom and the test, both
+
+The fix is unproven until the original repro no longer fires **and** the new test is green **and**
+the surrounding suite stayed green. For a flake, re-run enough times to show the failure rate is
+zero, not merely lower. Then hand the *whole-gate* re-run (lint/type/full suite/audit) to `verify` —
+that gate, not this skill, is what licenses the word "done".
+
+## Delegating the stack tooling (don't reinvent the instruments)
+
+`debug` owns the loop; the stack skill owns the debugger, the flake mechanics, and the profiler.
+
+| Stack / layer | Where the instruments live | What you pull |
+| --- | --- | --- |
+| FastAPI / async Python | `../fastapi/references/testing.md` | `pytest -x --lf`, `pdb`/`breakpoint()`, async task/race traps, transactional-rollback fixtures to kill state bleed |
+| Go services | `../go/references/testing.md` | `go test -race`, `-run`/`-count=1` to force a flake, `delve`, `pprof`, `errors.Is/As` unwrapping |
+| Next.js / React | `../nextjs/references/testing.md` | Vitest `--no-isolate`/`.only`, Playwright trace viewer, RSC vs client boundary errors, hydration mismatches |
+| Flutter / Dart | `../flutter/references/testing.md` | `flutter test --plain-name`, widget pump/settle timing, DevTools, golden diffs |
+| Postgres / data layer | `../postgresdb/SKILL.md` | `EXPLAIN ANALYZE`, isolation-level/locking races, constraint violations, migration-order bugs |
+| Security-shaped failure | `../secure-coding/SKILL.md` | auth/authz edge cases, injection, secret/leak paths surfacing as "weird" failures |
+
+If the failure spans two stacks (a Next.js call into a FastAPI endpoint), reproduce at the boundary
+first — isolate which side actually fails before you open either stack's debugger.
+
+## Log the diagnosis (the 02-DOCS trail)
+
+When the cause is non-obvious — a race, an order dependency, an environment-only failure, a
+regression a reviewer would otherwise have to rediscover — append a short entry to
+`02-DOCS/wiki/sdd/decisions.md` (append-only; create it if absent and add a row to the root
+`CLAUDE.md` `## Knowledge map` under the `sdd/` topic). One entry:
+
+```text
+## YYYY-MM-DD — bug: <symptom in five words>  (feature: <slug>)
+Repro      — the exact command/input that triggered it
+Cause      — the ONE confirmed root cause (not the symptom)
+Fix        — the minimal change + the regression test that guards it
+Why missed — what let it through, so the class of bug doesn't recur
+```
+
+Skip the trivial ones (a typo'd variable). Log the cause a future debugger would pay to know.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality |
+| --- | --- |
+| "I see the likely line — let me just change it and see." | That's guess-and-patch. Reproduce first; a fix to an untriggered bug proves nothing. |
+| "It's intermittent, you can't really reproduce it." | "Intermittent" is a rate to measure (k/N), not an excuse. Flakes have causes: state, order, races, time. |
+| "Wrapping it in try/except makes the error go away." | You hid the symptom and left the cause armed. Fix the cause, not the crash site. |
+| "Adding a sleep/retry/bigger timeout fixes the flake." | It relocates the race. Name the shared state or ordering bug; fix that. |
+| "I'll fix it now and add a test later if there's time." | The bug-reproducing test IS the fix's proof. No red-for-the-right-reason test = unproven fix. |
+| "I changed three things and now it works." | You can't say which mattered or why. One variable per isolate step; revert the rest. |
+| "The repro's gone, ship it." | Gone how? Re-run the repro AND the new test AND the suite. Symptom-absent ≠ cause-dead. |
+| "It works on my machine, so it's fixed." | Environment IS a variable. Reproduce where it actually fails (CI, prod-like) before claiming done. |
+| "This bug is obvious, skip the loop." | Obvious causes are the ones that turn out to be a second bug masking the first. Run the loop. |
+
+## Red flags — stop and re-route
+
+- **You're editing code and you can't yet reproduce the bug** → stop; you're guessing. Get a repro
+  (or a measured flake rate) first.
+- **The "bug" is a spec contradiction or unclear requirement**, not a defect → route to
+  `clarify` / `analyze`; debugging won't fix an ambiguity.
+- **The fix grows past the cause** (you're refactoring "while you're here") → split it out; keep the
+  fix minimal and verifiable. Improvements go through `implement`.
+- **You're tempted to disable, `skip`, or delete the failing test to make the suite green** → that's
+  the bug winning. Never ship around a red test; diagnose it.
+- **You "fixed" it but can't point to the cause you named** → you patched a symptom. Resume at
+  HYPOTHESIZE.
+- **The cause violates the constitution** (e.g. it only "works" by breaking a quality bar) → surface
+  it; don't smuggle a violation in under the banner of a bugfix.
+
+## Checklist (copy per bug)
+
+```text
+- [ ] REPRODUCE: exact command/input/env + verbatim error captured; repro reliable (or flake rate k/N measured)
+- [ ] ISOLATE: surface halved with evidence (bisect / code split / minimal input); ONE variable per step
+- [ ] HYPOTHESIZE: one falsifiable cause stated ("X because Y; changing Z flips it")
+- [ ] FIX: bug encoded as a failing test (red for the RIGHT reason); smallest change to the CAUSE
+- [ ] VERIFY: repro no longer fires; new test green; surrounding suite still green; flake rate → 0
+- [ ] Non-obvious cause logged to 02-DOCS/wiki/sdd/decisions.md
+- [ ] Handed the whole-gate re-run back to verify; resumed implement where the failure interrupted it
+```
+
+## What this skill is NOT
+
+- **Not the feature builder.** Once the cause is fixed and verified, planned work resumes in
+  `implement` (its red→green→refactor for the *next* task, not this bug).
+- **Not the quality gate.** The lint/type/full-suite/audit run that licenses "done" is `verify`'s
+  job; `debug` proves the one bug dead and hands the gate back.
+- **Not a refactor pass.** Keep the fix minimal; broader cleanups are `implement`/`review` territory,
+  not smuggled into a bugfix.
+
+## Where you are in the chain
+
+`debug` is **on-demand**, callable from any phase — most often pulled in mid-`implement` when a test
+fails for a reason you don't understand, or by `verify` when its gate reports a failure it won't
+diagnose. It is not a fixed step in the line `constitution → specify → clarify → plan → tasks →
+analyze → implement → verify → review → ship`.
+
+**Next:** when the one confirmed cause is fixed and proven gone, hand back. Return to `implement` to
+resume the interrupted task, or to `verify` to re-run the full gate and let evidence — not the relief
+of a quiet terminal — declare the work done.