rsc-universal 0.1.1

package/skills/embeddings-search/references/evaluation.md

@@ -0,0 +1,86 @@
+# Retrieval evaluation
+
+Turn "search is bad" into a number you can move. Everything here runs offline against a labeled
+query set — no LLM judge, no network.
+
+## 1. Build the golden query set
+
+The golden set is the asset. Aim for **30–50+** entries; more is better. Each entry is a real
+question plus the doc ids that genuinely answer it.
+
+```json
+[
+  {"query": "how long do refunds take", "relevant": ["doc_412", "doc_77"]},
+  {"query": "SKU AB-9931 specs",        "relevant": ["doc_1290"]},
+  {"query": "puc cancel·lar la subscripció?", "relevant": ["doc_88", "doc_640"]}
+]
+```
+
+Sourcing tips:
+- Pull real queries from logs; don't invent only easy ones — include the exact-match and the
+  multilingual cases that break dense-only retrieval.
+- Label relevance against the **chunk/doc id your retriever returns**, not the source PDF.
+- Keep it in version control. A change to the set invalidates old numbers.
+
+## 2. Metrics — what each one catches
+
+- **recall@k**: fraction of an entry's relevant docs found in the top-k. Catches *the right
+  chunk never came back* (a recall problem no reranker can fix).
+- **nDCG@k**: discounted gain that rewards relevant docs ranked higher (uses `log2(rank+1)`
+  discount). Catches *right docs, wrong order*.
+- **MRR**: mean of `1/rank` of the first relevant doc. Catches *the one answer is buried deep*.
+
+## 3. Runnable skeleton
+
+```python
+import math
+
+def recall_at_k(retrieved, relevant, k):
+    top = set(retrieved[:k])
+    rel = set(relevant)
+    return len(top & rel) / len(rel) if rel else 0.0
+
+def ndcg_at_k(retrieved, relevant, k):
+    rel = set(relevant)
+    dcg = sum(1.0 / math.log2(i + 2) for i, d in enumerate(retrieved[:k]) if d in rel)
+    ideal = sum(1.0 / math.log2(i + 2) for i in range(min(len(rel), k)))
+    return dcg / ideal if ideal else 0.0
+
+def mrr(retrieved, relevant):
+    rel = set(relevant)
+    for i, d in enumerate(retrieved):
+        if d in rel:
+            return 1.0 / (i + 1)
+    return 0.0
+
+def evaluate(golden, search_fn, k=10):
+    rs, ns, ms = [], [], []
+    for row in golden:
+        got = search_fn(row["query"])          # -> ordered list of doc ids
+        rs.append(recall_at_k(got, row["relevant"], k))
+        ns.append(ndcg_at_k(got, row["relevant"], k))
+        ms.append(mrr(got, row["relevant"]))
+    n = len(golden)
+    return {
+        f"recall@{k}": sum(rs) / n,
+        f"ndcg@{k}":   sum(ns) / n,
+        "mrr":         sum(ms) / n,
+    }
+```
+
+## 4. A/B one change at a time
+
+```text
+baseline   = evaluate(golden, search_v0)        # record it
+candidate  = evaluate(golden, search_v1)         # changed ONE thing
+# compare on the SAME golden set; keep the change only if the metric you care about went up
+```
+
+Change exactly one variable per run: the embedding model, OR the chunk size/strategy, OR the
+fusion (`k` in RRF, fan-in), OR the reranker. Stacking changes means you can't attribute the
+delta — and a regression hides inside an improvement.
+
+Typical decision pattern:
+- recall@k low → upstream: model choice, chunking, add sparse/hybrid. A reranker won't help.
+- recall@k high but nDCG/MRR low → ordering: add or tune the reranker.
+- exact-term queries failing while paraphrases pass → add BM25/sparse and re-measure.

package/skills/embeddings-search/references/models.md

@@ -0,0 +1,73 @@
+# Embedding model matrix (mid-2026)
+
+Read this to pick a model, size its dimensions, and call it with the right `input_type`. Facts
+dated 2026-06-02; re-check provider docs before committing a corpus, since model names and
+prices move.
+
+## Matrix
+
+| Model | Provider | Dims | Matryoshka truncation | Max input | ~Price /1M tok | Query/doc convention |
+|---|---|---|---|---|---|---|
+| `text-embedding-3-small` | OpenAI | 1536 | yes (`dimensions` param) | 8191 tok | ~$0.02 | symmetric (no input_type) |
+| `text-embedding-3-large` | OpenAI | 3072 | yes (`dimensions` param) | 8191 tok | ~$0.13 | symmetric |
+| `embed-v4` | Cohere | up to 1536 | yes | long | API-priced | `input_type=search_query` / `search_document` |
+| `voyage-3-large` | Voyage | model-set | partial | long | API-priced | `input_type="query"` / `"document"` |
+| Gemini Embedding | Google | truncatable | yes | long | API-priced | task type (retrieval query vs document) |
+| `BGE-M3` | open (self-host) | 1024 | no | 8192 tok | infra-only | prefix `query:` / `passage:` |
+| `e5-large` family | open (self-host) | 1024 | no | 512 tok | infra-only | prefix `query:` / `passage:` |
+
+MTEB English-retrieval anchors at the time of writing: Gemini ~68.3, Cohere `embed-v4` ~65.2,
+OpenAI `text-embedding-3-large` ~64.6, `BGE-M3` ~63.0. Voyage models lead retrieval-specific
+task slices.
+
+## How to read MTEB without over-trusting it
+
+- MTEB is an **average across many tasks and domains**. A model two points higher on the
+  overall board can be worse on legal Catalan, code, or your support tickets.
+- The board is **English-weighted**. For multilingual corpora, weight the multilingual slice
+  and confirm your languages are actually covered.
+- Leaderboards get **gamed and contaminated** over time. Treat the top 3–4 as a shortlist, then
+  run your own golden-set eval (see `evaluation.md`) — that number is the only one that decides.
+
+## input_type asymmetry — the silent recall killer
+
+Asymmetric models were trained so the query vector and the passage vector live in compatible
+but differently-prompted spaces. Embedding both sides the same way produces no error and
+quietly worse recall.
+
+```python
+# Cohere
+co.embed(texts=[q], model="embed-v4", input_type="search_query")
+co.embed(texts=[d], model="embed-v4", input_type="search_document")
+
+# Voyage
+vo.embed([q], model="voyage-3-large", input_type="query")
+vo.embed([d], model="voyage-3-large", input_type="document")
+
+# e5 / BGE — textual prefix
+embed("query: " + q)
+embed("passage: " + d)
+
+# OpenAI 3-* — symmetric, no input_type needed
+client.embeddings.create(model="text-embedding-3-small", input=[q])
+```
+
+## Matryoshka: shrink without re-embedding
+
+Matryoshka-trained models pack the most important signal in the leading dimensions, so you can
+slice a vector and keep most of the quality.
+
+```python
+# Ask for fewer dims at embed time…
+client.embeddings.create(model="text-embedding-3-large", input=[d], dimensions=1024)
+# …or truncate + re-normalise an already-stored full vector:
+import numpy as np
+def truncate(vec, n):
+    v = np.asarray(vec[:n], dtype="float32")
+    return (v / np.linalg.norm(v)).tolist()
+```
+
+Storage math: a float32 dim costs 4 bytes. 3072 dims = 12 KB/vector; 1024 dims = 4 KB. At 10M
+docs that is the difference between ~120 GB and ~40 GB. Cut dims first, measure recall on the
+golden set, and only keep the cut if recall holds. Do **not** re-embed the corpus from scratch
+just to change dimension count when the model is Matryoshka-trained.

package/skills/embeddings-search/scripts/verify.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — embeddings-search skill gate. A HEURISTIC config/eval linter, not a live check.
+#
+# Usage:  scripts/verify.sh [FILE ...]
+#   FILE = a produced artifact (embedding/ingest config, query code, eval harness). With no
+#   args it scans the current directory for *.py / *.json / *.yaml / *.yml / *.md artifacts
+#   that mention an embedding model, chunking, input_type, RRF/rerank, or a retrieval metric.
+#   Read-only; never connects to anything; never writes.
+#
+# Exit code: non-zero ONLY on a hard, unambiguous violation:
+#   - a cosine-style embedding model named alongside an L2-only metric, no cosine metric anywhere;
+#   - an asymmetric provider named but query and document embedded with the SAME input_type.
+# Advisory notes (exit 0): hybrid/rerank with no recall/nDCG/MRR/golden-set mention; chunk size
+# declared with no overlap and no token-accurate counting. An empty or clean target exits 0.
+#
+# Portable to stock macOS bash 3.2: no mapfile, no associative arrays, arrays pre-initialised.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+# ---- collect target files -------------------------------------------------
+FILES=()
+if [ "$#" -gt 0 ]; then
+  for f in "$@"; do
+    [ -f "$f" ] && FILES+=("$f") || note "not a file, skipping: $f"
+  done
+else
+  ROOT="$(pwd)"
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(
+    find "$ROOT" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+      -type f \( -name '*.py' -o -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.md' \) -print0 2>/dev/null
+  )
+fi
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  ok "no artifacts to check — clean"
+  exit 0
+fi
+
+# Keep only files that look like an embeddings/retrieval artifact, so a generic repo scan stays
+# quiet. A clean (non-matching) set still exits 0.
+TARGETS=()
+for f in "${FILES[@]}"; do
+  if grep -Eiq 'text-embedding-3|embed-v4|voyage-|bge-|e5-|gemini.?embedding|input_type|chunk_size|chunk_overlap|rerank|rrf|reciprocal.?rank|recall@|ndcg|mrr|embeddings\.create|\.embed\(' "$f" 2>/dev/null; then
+    TARGETS+=("$f")
+  fi
+done
+
+if [ "${#TARGETS[@]}" -eq 0 ]; then
+  ok "no embeddings/retrieval artifacts detected — nothing to lint"
+  exit 0
+fi
+
+# ---- per-file heuristics --------------------------------------------------
+for f in "${TARGETS[@]}"; do
+  printf -- '--- %s\n' "$f"
+
+  # 1) Metric mismatch: a cosine-style model but only L2 ops named, no cosine anywhere.
+  mentions_cosine_model=$(grep -Eic 'text-embedding-3|cohere|embed-v4|voyage-|bge-|e5-|gemini.?embedding|sentence-transformers|all-minilm|normaliz' "$f" 2>/dev/null || true)
+  has_cosine=$(grep -Eic '<=>|cosine|vector_cosine_ops|distance\.cosine' "$f" 2>/dev/null || true)
+  has_l2=$(grep -Eic '<->|vector_l2_ops|euclidean|distance\.euclid|metric *= *.?l2' "$f" 2>/dev/null || true)
+  if [ "$mentions_cosine_model" -gt 0 ] && [ "$has_l2" -gt 0 ] && [ "$has_cosine" -eq 0 ]; then
+    err "metric mismatch: names a cosine-style embedding model but only L2 distance — ranking is silently wrong. Use cosine (<=> / vector_cosine_ops)."
+  fi
+
+  # 2) Asymmetric provider named but query+document use the SAME input_type. Conservative:
+  #    only flag when an asymmetric provider is named.
+  names_asym=$(grep -Eic 'cohere|embed-v4|voyage-|bge-|e5-|gemini.?embedding' "$f" 2>/dev/null || true)
+  sq=$(grep -Eic 'input_type *= *.?(search_query|query)|"query: ' "$f" 2>/dev/null || true)
+  sd=$(grep -Eic 'input_type *= *.?(search_document|document|passage)|"passage: ' "$f" 2>/dev/null || true)
+  any_input_type=$(grep -Eic 'input_type *=|"query: |"passage: ' "$f" 2>/dev/null || true)
+  if [ "$names_asym" -gt 0 ] && [ "$any_input_type" -gt 0 ] && [ "$sd" -eq 0 ] && [ "$sq" -gt 0 ]; then
+    err "asymmetric model uses the query input_type for both sides (no document/passage type found) — recall silently drops. Embed documents with the document/passage input_type."
+  fi
+
+  # 3) Hybrid / rerank present but no retrieval-quality metric mentioned (advisory).
+  has_hybrid=$(grep -Eic 'rerank|rrf|reciprocal.?rank|bm25|hybrid' "$f" 2>/dev/null || true)
+  has_metric=$(grep -Eic 'recall@|recall_at|ndcg|mrr|golden|relevant' "$f" 2>/dev/null || true)
+  if [ "$has_hybrid" -gt 0 ] && [ "$has_metric" -eq 0 ]; then
+    note "hybrid/rerank present but no recall/nDCG/MRR or golden-set mention — measure relevance before vs after on a fixed query set."
+  fi
+
+  # 4) Chunk size declared with no overlap and no token-accurate counting (advisory).
+  has_chunk_size=$(grep -Eic 'chunk_size' "$f" 2>/dev/null || true)
+  has_overlap=$(grep -Eic 'chunk_overlap|overlap' "$f" 2>/dev/null || true)
+  has_token_count=$(grep -Eic 'tiktoken|tokenizer|encoding_name|token.?accurate|from_tiktoken' "$f" 2>/dev/null || true)
+  if [ "$has_chunk_size" -gt 0 ] && [ "$has_overlap" -eq 0 ] && [ "$has_token_count" -eq 0 ]; then
+    note "chunk_size declared with no overlap and no token-accurate counting — add 10–20% overlap and count tokens (tiktoken/tokenizer), not characters."
+  fi
+done
+
+if [ "$EXIT" -eq 0 ]; then
+  ok "no hard violations"
+fi
+exit "$EXIT"

package/skills/error-handling/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: error-handling
+description: "Use when designing how code recognizes, recovers from, and reports failure — typed error taxonomies, retry/backoff/timeout policy, circuit breakers, React/Next error boundaries, and the user message + operator log line. Triggers: 'add retries with backoff', 'set up an error boundary', 'standardize our error types', 'stop swallowing exceptions', 'this catch block hides the real error', 'degrade gracefully when the payment provider is down', 'why does our retry storm take the database down', 'maneja los errores sin tragarte la excepción', 'afegeix reintents amb backoff i tallacircuits'. NOT finding why one specific thing broke (that is debug), NOT wiring logs/metrics/traces (that is observability), NOT the on-the-wire error envelope contract (that is api-design)."
+tags: [error-handling, resilience, retry, circuit-breaker, error-boundary, typed-errors, fault-tolerance]
+recommends: [debug, observability, monitoring, api-design, secure-coding, testing-web, nextjs]
+origin: risco
+---
+
+# Error handling — classify, contain, surface
+
+You are designing what happens *whenever anything in a class breaks*, not chasing
+one crash (that is [`debug`](../debug/SKILL.md)). The deliverable is a typed error
+taxonomy, a retry policy with caps and jitter, boundary placement, and a
+two-audience message contract — never a pile of `try { … } catch {}`.
+
+## The one rule
+
+**Every failure gets classified, contained, and surfaced — never swallowed.**
+
+- **Classify** — give the failure a type so the right code can react to the right
+  kind. An untyped `catch (e)` cannot decide anything.
+- **Contain** — stop one failing dependency from taking the process (or the DB)
+  with it. No timeout, no cap = unbounded blast radius.
+- **Surface** — emit two things: a human message that never leaks internals, and
+  an operator log with the full cause chain.
+
+The five steps below are those three jobs in order. Do them in order.
+
+## Step 1 — Model failure as a taxonomy
+
+Bucket every failure into one of three kinds. The bucket dictates the reaction;
+get the bucket wrong and every downstream decision is wrong too.
+
+| Bucket | Examples | Retry? | Tell the user | Tell the operator |
+|---|---|---|---|---|
+| **Domain / expected** | insufficient funds, slot taken, validation failed | No | Yes, actionable | info — it is normal |
+| **Infrastructure / transient** | timeout, 503, connection reset, 429 | Yes (capped) | "temporary, retrying" | warn — watch the rate |
+| **Programmer error / bug** | null deref, bad assertion, type error | No | generic "something broke" + id | error — page if frequent |
+
+### Result vs throw
+
+Decide per call site, not per codebase:
+
+- **`Result<T, E>`** for *expected domain* failures the caller must handle. The
+  type checker forces a branch — the failure cannot be ignored by accident.
+- **`throw`** for *exceptional / programmer* errors. These should crash up to the
+  nearest boundary, not be threaded through every signature.
+
+In TypeScript, `neverthrow` (current) is the instrument for the Result path:
+
+```ts
+import { ok, err, Result } from "neverthrow";
+
+type ChargeError = "insufficient_funds" | "card_declined";
+
+// Expected domain failure → Result. The caller MUST handle both arms.
+function charge(cents: number, balance: number): Result<number, ChargeError> {
+  if (cents > balance) return err("insufficient_funds");
+  return ok(balance - cents);
+}
+
+const r = charge(500, 200);
+if (r.isErr()) {
+  // r.error is the typed union — exhaustive, no `any`.
+}
+```
+
+### Stable codes and cause chaining
+
+Every error carries a **stable `code`** (a string the UI and logs key off, never
+the human message) and **never drops the original cause**.
+
+```ts
+// BAD — string error, loses the original, nothing to branch on.
+throw new Error("payment failed");
+
+// GOOD — typed class, stable code, cause preserved.
+class PaymentError extends Error {
+  constructor(public code: "provider_down" | "declined", cause?: unknown) {
+    super(code);
+    this.name = "PaymentError";
+    this.cause = cause; // the original error/stack survives for the log
+  }
+}
+try {
+  await provider.charge();
+} catch (e) {
+  throw new PaymentError("provider_down", e); // wrap, do not erase
+}
+```
+
+Cross-language error-class skeletons (Python, Java, Go, .NET) live in
+[`references/retry-and-resilience.md`](references/retry-and-resilience.md).
+
+## Step 2 — Decide retryability
+
+Retry **only** transient failures, and **only** on idempotent operations. Retrying
+the wrong thing turns one slow dependency into a self-inflicted outage.
+
+| Retry these (transient) | Never retry these (permanent) |
+|---|---|
+| Network error, connection reset | 400 bad request, 422 unprocessable |
+| Timeout | 401 / 403 (auth/permission) |
+| 429 too many requests (honor `Retry-After`) | 404 not found |
+| 503 / 502 / 504 | Any business-rule rejection (insufficient funds) |
+| 500 **on a GET** (idempotent) | 500 on a non-idempotent POST without a key |
+
+**Idempotency is a precondition, not a nicety.** A retried POST that creates a
+charge can double-charge. Retry only operations that are idempotent by nature
+(GET, PUT, DELETE) or that carry an **idempotency key** so the server dedupes.
+Key design itself belongs to [`../api-design/SKILL.md`](../api-design/SKILL.md);
+here you just require one before you retry a mutation.
+
+**Caps (industry-converged — AWS Builders' Library, REL05-BP03):**
+
+- Max **3–5** total attempts.
+- Base delay **100–200ms**, doubling per attempt.
+- Per-delay cap **10–30s**; total retry budget **10–60s** then give up.
+- **Full jitter** to spread load — beats fixed and equal jitter:
+
+```text
+delay = random_between(0, min(cap, base * 2 ** attempt))
+```
+
+Set a **per-attempt timeout first**, then retry — a retry on a call that never
+times out just stacks hung requests.
+
+```ts
+// GOOD — classify before retrying; cap; full jitter; per-attempt timeout.
+async function withRetry<T>(fn: () => Promise<T>, max = 4): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn(); // fn must enforce its own per-attempt timeout
+    } catch (e) {
+      if (!isTransient(e) || attempt >= max - 1) throw e; // permanent or budget spent
+      const cap = 10_000, base = 150;
+      const delay = Math.random() * Math.min(cap, base * 2 ** attempt); // full jitter
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+}
+```
+
+Per-language `withRetry` (Python `tenacity`, Java Resilience4j, .NET Polly) is in
+[`references/retry-and-resilience.md`](references/retry-and-resilience.md).
+
+## Step 3 — Contain blast radius
+
+Retries alone make a struggling dependency worse. Contain it.
+
+- **Timeout every outbound call.** No timeout is a bug, not a default. An
+  un-timed call holds a connection until the OS gives up — minutes you do not have.
+- **Circuit breaker** — stop hammering a dead dependency. Three states:
+  - **Closed**: requests flow; count failures.
+  - **Open**: trip at ~**50% failure** over a ~**20-request** window; reject fast
+    for **30–60s** without calling downstream.
+  - **Half-Open**: after the cooldown, let a probe through; success → Closed,
+    failure → Open again.
+  - Critical services trip tighter (~30%); tolerant ones up to ~70%.
+- **Instruments (current):** Opossum (Node — defaults timeout 3000ms /
+  errorThresholdPercentage 50 / resetTimeout 30000ms), Polly 8.6.6 (.NET fluent
+  pipelines), Resilience4j 2.3.0 (Java 17+ `2.x` line; a `3.x` line targets Java
+  21). The config matrix is in
+  [`references/retry-and-resilience.md`](references/retry-and-resilience.md).
+- **Fallback / graceful degradation** — when the breaker is Open, serve a stale
+  cache, a safe default, or an honest "this feature is temporarily unavailable".
+  Degrade; do not 500 the whole page.
+- **Bulkhead** — isolate resource pools (separate connection pool / worker queue
+  per dependency) so one saturated downstream cannot starve the rest. Sizing in
+  the reference.
+
+## Step 4 — Boundaries
+
+A boundary is where an unhandled failure is *caught and converted* into a
+contained reaction. Place one at each level that can fail independently.
+
+### React / Next.js App Router
+
+- **`error.tsx`** is a **route-segment** boundary. It MUST be a Client Component
+  (`'use client'`) and receives `{ error, reset }`. An error in a segment bubbles
+  to the nearest *parent* `error.tsx`.
+- **`error.tsx` does NOT catch an error thrown in its own segment's `layout.tsx`
+  or `template.tsx`.** Those run *outside* the boundary — move the boundary to the
+  parent segment to cover them.
+- **`global-error.tsx`** wraps the whole app and must render its own `<html>` and
+  `<body>` (it replaces the root layout when the root itself fails).
+- **Boundaries only catch errors during *render*.** Errors in event handlers,
+  `async` callbacks, `setTimeout`, or server-side data fetching are invisible to
+  them — handle those with explicit `try/catch` + state.
+
+```tsx
+"use client"; // app/dashboard/error.tsx — REQUIRED
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  // Log to your telemetry sink (see observability); show the user the digest id.
+  return (
+    <div role="alert">
+      <p>Something went wrong. Quote id {error.digest} to support.</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+The full segment-tree placement map and the `global-error.tsx` skeleton are in
+[`references/boundaries-and-messaging.md`](references/boundaries-and-messaging.md).
+Framework specifics: [`../nextjs/SKILL.md`](../nextjs/SKILL.md).
+
+### Server and process
+
+- **Request boundary** — one error handler / middleware that maps the taxonomy →
+  HTTP status, attaches a correlation id, and emits the operator log. Every route
+  funnels through it instead of formatting errors ad hoc.
+- **Process boundary** — a top-level `unhandledRejection` / `uncaughtException`
+  handler (Node) or equivalent. Log the cause chain, then **exit and let the
+  supervisor restart**. A process that keeps running after an unhandled error is
+  running corrupted.
+
+## Step 5 — Surface it
+
+Two audiences. Never conflate them — that is how stack traces reach end users and
+how logs become useless.
+
+| | User message | Operator log |
+|---|---|---|
+| **Goal** | tell them what to do next | let you reconstruct what happened |
+| **Content** | plain language, one action, a correlation id | code, cause chain, request context, structured fields |
+| **Never** | stack trace, SQL, internal hostnames, PII | a swallowed/lost cause |
+
+**Taxonomy → HTTP status** (the in-process map; the *wire envelope* shape —
+RFC 9457 problem+json — belongs to [`../api-design/SKILL.md`](../api-design/SKILL.md);
+*shipping* the log to a sink belongs to [`../observability/SKILL.md`](../observability/SKILL.md)):
+
+| Bucket / code | Status |
+|---|---|
+| validation / bad input | 400 / 422 |
+| unauthenticated / forbidden | 401 / 403 |
+| not found | 404 |
+| domain conflict (slot taken) | 409 |
+| transient downstream / breaker open | 503 (+ `Retry-After`) |
+| programmer error / unknown | 500 |
+
+```text
+BAD  → alert("TypeError: cannot read 'id' of undefined")
+GOOD → "We couldn't load your orders. Try again in a moment — id a1b2c3."
+
+BAD  → 500 { "error": "ECONNREFUSED 10.0.3.12:5432" }   // leaks topology
+GOOD → 503 { "code": "upstream_unavailable", "correlationId": "a1b2c3" }
+```
+
+More before/after rewrites and the copy contract are in
+[`references/boundaries-and-messaging.md`](references/boundaries-and-messaging.md).
+
+## Decision table
+
+| Situation | Reaction |
+|---|---|
+| Expected domain outcome the caller must handle | `Result<T,E>` |
+| Programmer bug / invariant violation | `throw` → nearest boundary |
+| Transient failure on an idempotent call | retry (capped + full jitter) |
+| Transient failure on a mutation without a key | do **not** retry; require idempotency key first |
+| Dependency failing repeatedly | circuit-break + fallback |
+| Failure during React render | `error.tsx` boundary |
+| Failure in an event handler / async callback | explicit `try/catch` + state |
+| Unhandled at the top of the process | process handler → log + exit |
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Fix |
+|---|---|---|
+| Empty `catch {}` / `except: pass` | failure vanishes; you debug blind later | handle, or rethrow with context |
+| Bare `except:` (Python) | swallows `KeyboardInterrupt`/`SystemExit` too | catch the specific type |
+| Retry everything, including 4xx | retrying a 400 just burns budget; never succeeds | retry only the transient table |
+| Retry a non-idempotent POST without a key | double-charges, duplicate rows | require an idempotency key first |
+| Infinite retry, no cap or jitter | thundering herd; turns a blip into an outage | cap attempts + full jitter + budget |
+| Leak stack trace / SQL to the user | hands attackers your internals | generic message + id; detail to the log |
+| Expect `error.tsx` to catch its own segment's `layout` error | it runs outside the boundary; nothing catches it | move the boundary to the parent |
+| `alert(e.message)` as the handler | blocks the UI, leaks internals, no recovery | render an `error.tsx` with `reset` |
+| Catch-and-rethrow that drops `cause` | the root error is gone; logs are a dead end | wrap, set `cause`, preserve the chain |
+| Log the error **and** rethrow | double-logged at every layer; noise buries signal | log at the boundary, or rethrow — not both |
+| Swallow, then `return null` | callers deref null later, far from the cause | return a typed `Result` error |
+| Outbound call with no timeout | one hung dependency exhausts the pool | timeout every call, then retry |
+| One giant `try` around 200 lines | you cannot tell which call failed | scope `try` to the fallible call |
+| Treat every error as a retryable transient | masks real bugs as "flaky" | classify first (Step 1), then react |
+
+## Verification checklist
+
+Before claiming the failure path is handled:
+
+- [ ] Every failure maps to one of the three buckets (Step 1).
+- [ ] No empty `catch {}` / `except: pass` / bare `except:`.
+- [ ] Retries are capped, jittered, transient-only, and idempotent-only.
+- [ ] Every outbound call has a per-attempt timeout.
+- [ ] Repeatedly-failing dependencies have a circuit breaker + fallback.
+- [ ] `error.tsx` / `global-error.tsx` placed correctly; render-only limits known.
+- [ ] User message has no internals + carries a correlation id; the log has the cause chain.
+- [ ] Cause is preserved on every wrap (no lost root error).
+
+Run `scripts/verify.sh <path>` to scan the working tree for the highest-signal
+anti-patterns above. It is **advisory** (exit 0 with warnings); pass `--strict` to
+make any hit fail. It is heuristic — it flags, you judge.

package/skills/error-handling/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — error-handling
+
+`cases.yaml` is read by the catalog eval runner. `should_trigger` and
+`should_not_trigger` check routing precision: the model should select this skill
+for the trigger prompts and route the negatives to the named sibling id instead
+(`debug`, `observability`, `api-design`, `monitoring`, `testing-web`) — those ids
+are the assertion, so they must be real catalog skills. `capability` is a rubric:
+the model designs error handling for the scenario and is scored on whether its
+answer covers every `must_include` bullet. To run locally, point the repo's eval
+harness at this file (it discovers `skills/*/evals/cases.yaml`); with no harness
+wired up, use the cases as a manual checklist — read each prompt cold, confirm the
+routing decision, and grade a capability answer against the bullets.

package/skills/error-handling/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: error-handling
+
+should_trigger:
+  - prompt: "Add retry with exponential backoff to our payment-provider client — it times out a lot."
+    why: "Core retry-policy request. The skill owns caps, full jitter, transient-vs-permanent classification, and the idempotency precondition for a payment mutation."
+  - prompt: "Our exceptions get swallowed all over the codebase. Give us a real error strategy."
+    why: "Taxonomy + surfacing. 'Swallowed exceptions' is the skill's one rule (classify/contain/surface, never swallow), not a single-bug hunt."
+  - prompt: "Set up error boundaries in our Next.js App Router so a broken widget doesn't blank the page."
+    why: "Step 4 boundary placement: error.tsx / global-error.tsx, what bubbles where, what render-only boundaries don't catch."
+  - prompt: "When Stripe is down the whole checkout 500s. Make it degrade gracefully instead."
+    why: "Non-obvious: the ask sounds like 'fix Stripe' but it is circuit-breaker + fallback design (contain blast radius, serve a degraded path), not debugging Stripe."
+  - prompt: "afegeix reintents amb backoff i un tallacircuits al client de l'API"
+    why: "Catalan trigger ('add retries with backoff and a circuit breaker to the API client') — retry policy + circuit breaker, squarely Steps 2-3."
+  - prompt: "Why does one slow downstream service cause a retry storm that takes our database down?"
+    why: "Non-obvious: this is retry-budget + circuit-breaker design (uncapped retries amplifying load), not 'add more capacity' (scaling) and not 'find the bug' (debug)."
+  - prompt: "This catch block hides the real error — we only ever see 'undefined' in logs. Fix how we handle errors here."
+    why: "Cause-chaining and the log-vs-user split (Step 1 + Step 5). Dropped cause is a named anti-pattern this skill fixes."
+
+should_not_trigger:
+  - prompt: "Find out why this specific endpoint throws a NullPointer intermittently — it only happens under load."
+    route_to: debug
+    why: "Root-causing one specific intermittent crash is debug. error-handling designs the reaction to a CLASS of failure, not the diagnosis of this one."
+  - prompt: "Wire up OpenTelemetry traces so we can see where requests fail across services."
+    route_to: observability
+    why: "Making failures visible after the fact (traces/metrics/logs) is observability. error-handling decides the runtime reaction, not the telemetry pipeline."
+  - prompt: "Define the JSON error envelope every endpoint returns — we want RFC 9457 problem+json."
+    route_to: api-design
+    why: "The on-the-wire error contract (envelope shape, fields, versioning) is api-design. error-handling produces the status/code; api-design decides the bytes."
+  - prompt: "Page me when the API starts returning 5xx for more than two minutes."
+    route_to: monitoring
+    why: "Alerting/paging/on-call is monitoring. error-handling keeps the service from going down; it does not own the alert rule."
+  - prompt: "Write the tests that prove our retry logic gives up after 4 attempts."
+    route_to: testing-web
+    why: "Authoring the tests that prove the error paths is testing-web. error-handling designs the paths; the test skill verifies them."
+
+capability:
+  - scenario: "A Node service calls a flaky third-party API inside a Next.js checkout. Design end-to-end error handling for it."
+    must_include:
+      - "A typed / Result error taxonomy with stable string codes and three buckets (domain / transient / programmer-error)."
+      - "Classification of retryable transient failures (timeout, 429, 503, network) vs permanent (400/401/403/404/business-rule)."
+      - "Capped retry (3-5 attempts) with full jitter and a per-attempt timeout BEFORE the retry."
+      - "An idempotency-key precondition for the retried checkout mutation (no double-charge), deferring key design to api-design."
+      - "A circuit breaker with Closed/Open/Half-Open states and a concrete threshold (~50% over ~20 reqs, Open 30-60s) plus a fallback."
+      - "error.tsx / global-error.tsx boundary placement, and the note that boundaries catch render errors only (event/async/data-fetch need try/catch)."
+      - "A distinct user message (plain, correlation id, no internals) vs a structured operator log carrying the cause chain."
+      - "Explicit hand-offs: envelope shape to api-design, telemetry to observability, alerting to monitoring."