rsc-universal 0.1.1

package/skills/sales-pipeline/references/forecasting-math.md

@@ -0,0 +1,82 @@
+# Forecasting math — worked examples and the column contract
+
+This is the simple stage-weighted roll-up that falls out of a clean pipeline.
+It is **not** statistical forecasting — no scenarios, no time-series, no cohort
+projection. If the ask needs those, route to `forecasting`.
+
+All figures use the load-bearing benchmarks: stage probabilities from the stage
+model, the current **~18% B2B win rate** (down from ~21%, with cycles ~12%
+longer YoY — *Ebsta/Pavilion 2025 B2B Sales Benchmark*), and the segment
+coverage benchmarks below. *(Drivetrain / Coefficient / forecastio.ai; ORM Tech;
+First Page Sage — all accessed 2026-06-02.)*
+
+## 1 — Weighted forecast on a 5-deal list
+
+`weighted_value = value × stage win_prob`, then apply stale decay (no touch
+14+ days → halve; 30+ days → drop from the roll-up).
+
+| id | value | stage | win_prob | last_touch age | adjustment | weighted |
+|---|---|---|---|---|---|---|
+| D-1 | 40,000 | Discovery | 0.30 | 3 d | none | 12,000 |
+| D-2 | 25,000 | Negotiation | 0.65 | 6 d | none | 16,250 |
+| D-3 | 60,000 | Proposal | 0.40 | 18 d | halve (14d+) | 12,000 |
+| D-4 | 30,000 | Qualification | 0.10 | 40 d | **drop** (30d+) | 0 |
+| D-5 | 50,000 | Negotiation | 0.65 | 2 d | none | 32,500 |
+
+- Raw weighted (no decay): 12,000 + 16,250 + 24,000 + 3,000 + 32,500 = **87,750**.
+- Decayed weighted forecast: 12,000 + 16,250 + 12,000 + 0 + 32,500 = **72,750**.
+
+The 15,000 gap is exactly the cost of stale deals — which is why you decay
+before you report, never after.
+
+## 2 — Pipeline coverage by segment
+
+`coverage = Total Qualified Pipeline Value ÷ Revenue Target`. "Qualified"
+excludes stale (30d+) deals.
+
+| segment | win rate | min | target |
+|---|---|---|---|
+| Enterprise ($100K+ ACV) | 15–20% | 5× | 6–7× |
+| Commercial ($25–100K) | 20–30% | 3.5× | 4–5× |
+| SMB (<$25K) | 30–40% | 2.5× | 3–4× |
+
+*(ORM Tech, accessed 2026-06-02.)*
+
+**Worked:** a Commercial team with a $250K quarterly target and $900K of
+qualified (non-stale) pipeline has coverage = 900 / 250 = **3.6×**. That clears
+the 3.5× minimum but sits below the 4–5× target — adequate, not comfortable.
+If coverage drops two weeks running with no closes, escalate; that is the red
+flag, not a single low snapshot.
+
+## 3 — Pipeline velocity
+
+`velocity = (Open opps × Avg deal size × Win rate) ÷ Sales-cycle length (days)`
+→ dollars/day. *(Salesmotion / ORM Tech.)*
+
+**Worked:** 40 open opps × $30,000 avg × 0.18 win ÷ 90-day cycle =
+216,000 / 90 = **$2,400/day**.
+
+Cycle length is the highest-leverage term: cut the 90-day cycle ~20% to 72 days
+and velocity rises to 216,000 / 72 = **$3,000/day** — a ~25% lift from one
+lever. Use your **real, current** cycle length; a shorter historical cycle
+flatters the number the same way an old win rate does.
+
+## 4 — The column contract `verify.sh` enforces
+
+The pipeline artifact (CSV or markdown table) must have a header containing at
+least these columns; `verify.sh` is a structural + arithmetic lint over them,
+not a judgement of deal quality.
+
+| column | check |
+|---|---|
+| `stage` | present in header; each value in the allowed set: Prospecting, Qualification, Discovery, Proposal/Demo (or Proposal / Demo), Negotiation, Closed (Won/Lost) |
+| `value` | present; numeric |
+| `win_prob` | present; `0 ≤ win_prob ≤ 1` |
+| `weighted_value` | present; equals `round(value × win_prob)` within tolerance |
+| `close_date` | present and non-empty on every **open** deal |
+| `next_step` | present and non-empty on every **open** deal |
+| `last_touch` | present and non-empty on every **open** deal |
+
+Plus: at least one **coverage** summary line/row must be present somewhere in
+the file (a line matching `coverage`). An empty or missing-content file is a
+clean pass — the lint never false-fails on nothing.

package/skills/sales-pipeline/references/stage-playbook.md

@@ -0,0 +1,84 @@
+# Stage playbook — the six gated stages in full
+
+The default model is six stages. Five stages with clear exit criteria beat nine
+stages with none. A deal advances **only** when the exit criterion (a verifiable
+buyer action) is met **and** a next step is on the calendar. The stage carries
+the win-probability; the rep never hand-sets it. *(Cirrus Insight / Prospeo,
+accessed 2026-06-02.)*
+
+## The stages
+
+### 1 — Prospecting · default win_prob 0.05
+- **Exit criterion:** the buyer has agreed to a first real conversation — a
+  meeting is on the calendar (not "they opened my email").
+- **Required fields:** `id`, `company`, `owner`, `next_step` (the meeting),
+  `last_touch`.
+- A deal here is barely a deal; do not let Prospecting volume flatter coverage.
+
+### 2 — Qualification · default win_prob 0.10
+- **Exit criterion:** BANT (or MEDDIC above ~$25K ACV) documented as a "yes" —
+  budget exists, you are talking to or have a path to authority, there is a real
+  need, and there is a timeline.
+- **Required fields:** add `value` (first real estimate), `close_date` (first
+  estimate), the qualification notes.
+
+### 3 — Discovery · default win_prob 0.30
+- **Exit criterion:** the buyer has confirmed the problem and their success
+  criteria, and you know the **buying process** — review layers, legal steps,
+  procurement. "If you don't know the criteria, timeline, review layers and
+  legal steps, the close date is a guess." *(Routine / weflow / HubSpot.)*
+- **Required fields:** firmed `value`, firmed `close_date`, the buying-process
+  notes, `next_step`.
+
+### 4 — Proposal/Demo · default win_prob 0.40
+- **Exit criterion:** the proposal or demo has been delivered **and
+  acknowledged**, and the buyer is engaging on it (questions, redlines, internal
+  circulation) — not just "sent and silent."
+- The proposal document itself is written by `proposals`, not here.
+
+### 5 — Negotiation · default win_prob 0.65 (band 0.50–0.80)
+- **Exit criterion:** terms and price are under active discussion, there is
+  verbal intent, and you have a **mutual close plan** with dates.
+- Pick within the 0.50–0.80 band on real signal (legal in motion, MSA in
+  redline → higher end). Never reflexively set 0.80.
+
+### 6 — Closed · win_prob 1.0 (Won) / 0.0 (Lost)
+- **Won:** signed. The deal leaves this skill — handoff/kickoff is
+  `client-onboarding`.
+- **Lost:** formally lost, with a reason. Losing cleanly keeps the win-rate
+  honest; do not let dead deals linger as "open."
+
+## Qualification: BANT vs MEDDIC — pick by deal size
+
+Run **BANT as a ~60-second screen** on every deal; switch to **MEDDIC/SPICED
+above ~$25K ACV** where the buying process is complex enough to need it.
+*(Routine / weflow / HubSpot, accessed 2026-06-02.)*
+
+| | BANT (fast screen, < $25K) | MEDDIC (complex, $25K+ ACV) |
+|---|---|---|
+| B / M | **B**udget | **M**etrics — the quantified business outcome |
+| A / E | **A**uthority | **E**conomic buyer — who signs |
+| N / D | **N**eed | **D**ecision criteria + **D**ecision process |
+| T / I | **T**imeline | **I**dentify pain + **C**hampion |
+
+The exit criterion for Qualification is a documented "yes" across the relevant
+framework **plus** a calendared next step. A "yes" with no next step is not a
+pass.
+
+## Forecast categories — map separately from stages
+
+Categories are a judgement of *confidence to land this period*; stages are
+*where the deal is in the process*. They are not the same axis. *(Gary Smith
+Partnership / Salesforce default categories, accessed 2026-06-02.)*
+
+| category | meaning | rough in-quarter landing |
+|---|---|---|
+| Pipeline | open, qualified, not yet committed | ~25% lands this quarter |
+| Best Case | upside if things go well | ~1/3 to 1/2 lands |
+| Commit | you are willing to put your name on it | near-all lands |
+| Closed | signed (Won) or lost | done |
+| Omitted | excluded from the forecast (e.g. stale 30d+) | not counted |
+
+Rule: a deal's category must match documented evidence. A Discovery-stage deal
+in "Commit" is a defect — demote it. Stale deals (30+ days no touch) move to
+Omitted so they stop flattering the commit number.

package/skills/sales-pipeline/scripts/verify.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural + arithmetic lint for a pipeline file.
+#
+# WHAT IT DOES (read-only; never edits or writes a file)
+#   Static, network-free checks over ONE pipeline file you point it at — a CSV
+#   (preferred) or a markdown table with the same column names:
+#     1. Header has the required columns: id, value, stage, win_prob,
+#        weighted_value, close_date, next_step, last_touch.  (missing -> FAIL)
+#     2. Each non-Closed (open) deal has non-empty close_date, next_step,
+#        last_touch.                                          (missing -> FAIL)
+#     3. stage is in the allowed set: Prospecting, Qualification, Discovery,
+#        Proposal/Demo (or "Proposal"/"Demo"), Negotiation, Closed
+#        (incl. "Closed Won" / "Closed Lost").                (unknown -> FAIL)
+#     4. win_prob is a number with 0 <= win_prob <= 1.        (out of range -> FAIL)
+#     5. weighted_value == round(value * win_prob) within +/-1 tolerance.
+#                                                             (mismatch -> FAIL)
+#     6. A coverage summary line/row is present somewhere (a line matching
+#        /coverage/i).                                         (absent -> FAIL)
+#
+#   A clean OR empty/missing-content file exits 0 — never a false failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh pipeline.csv          # lint a CSV pipeline
+#   ./verify.sh pipeline.md           # lint a markdown-table pipeline
+#   ./verify.sh pipeline.csv --tol 2  # widen the weighted_value tolerance
+#
+# EXIT CODES
+#   0  clean, or empty/missing-content file
+#   1  one or more structural / arithmetic failures
+#   2  bad usage (no file, file missing, header has no required columns at all)
+#
+# Runs on stock macOS bash 3.2 + awk: no mapfile, no bc, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; NC=''
+fi
+
+fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$NC" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED"   "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+FILE=""
+TOL=1
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --tol) TOL="${2:-1}"; shift 2 ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) if [ -z "$FILE" ]; then FILE="$1"; fi; shift ;;
+  esac
+done
+
+if [ -z "$FILE" ]; then
+  printf '%sno pipeline file given%s\n' "$RED" "$NC" >&2; usage; exit 2
+fi
+if [ ! -f "$FILE" ]; then
+  printf '%sfile not found: %s%s\n' "$RED" "$FILE" "$NC" >&2; exit 2
+fi
+
+# Empty / whitespace-only file: nothing to check, do not false-fail.
+if [ ! -s "$FILE" ] || ! grep -q '[^[:space:]]' "$FILE" 2>/dev/null; then
+  ok "empty file — nothing to check"
+  exit 0
+fi
+
+printf 'sales-pipeline verify — %s (weighted_value tolerance=+/-%s)\n\n' "$FILE" "$TOL"
+
+# All checks run in one awk pass. It auto-detects delimiter: a pipe-table row
+# (markdown) splits on '|'; otherwise CSV splits on ','. Quotes are tolerated
+# (a quoted field with internal commas is rare in these columns; we strip
+# surrounding quotes and trim spaces). The coverage check scans every raw line.
+awk -v tol="$TOL" '
+  function trim(s){ gsub(/^[ \t"]+/,"",s); gsub(/[ \t"]+$/,"",s); return s }
+  function lc(s){ return tolower(s) }
+
+  # detect coverage line anywhere; a coverage summary row is not a deal row
+  tolower($0) ~ /coverage/ { cov=1; next }
+
+  # skip markdown separator rows like |----|----|
+  /^[ \t]*\|?[ \t:-]+\|[ \t:|-]*$/ { next }
+
+  {
+    raw=$0
+    # choose delimiter
+    if (raw ~ /\|/) { sep="|" } else { sep="," }
+    n=split(raw, f, sep)
+    # markdown tables have a leading/trailing pipe -> empty cells; trim all
+    for (i=1;i<=n;i++) f[i]=trim(f[i])
+
+    # locate header row: the first row containing "stage" and "win_prob"
+    if (!have_header) {
+      isheader=0
+      for (i=1;i<=n;i++) {
+        if (lc(f[i])=="stage") s_seen=1
+        if (lc(f[i])=="win_prob") w_seen=1
+      }
+      if (s_seen && w_seen) {
+        have_header=1
+        for (i=1;i<=n;i++) { col[lc(f[i])]=i }
+        next
+      }
+      s_seen=0; w_seen=0
+      next
+    }
+
+    # data row
+    # skip a row that is empty after trimming (markdown edge cells)
+    nonempty=0
+    for (i=1;i<=n;i++) if (f[i]!="") nonempty=1
+    if (!nonempty) next
+
+    rows++
+    id    = (("id" in col)             ? f[col["id"]] : ("row " rows))
+    stg   = (("stage" in col)          ? f[col["stage"]] : "")
+    val   = (("value" in col)          ? f[col["value"]] : "")
+    wp    = (("win_prob" in col)       ? f[col["win_prob"]] : "")
+    wv    = (("weighted_value" in col) ? f[col["weighted_value"]] : "")
+    cd    = (("close_date" in col)     ? f[col["close_date"]] : "")
+    ns    = (("next_step" in col)      ? f[col["next_step"]] : "")
+    lt    = (("last_touch" in col)     ? f[col["last_touch"]] : "")
+
+    lstg = lc(stg)
+    open_deal = (lstg !~ /closed|won|lost/)
+
+    # 2 — required fields on open deals
+    if (open_deal) {
+      if (cd=="") { print "FAIL\t" id ": open deal missing close_date" ; bad++ }
+      if (ns=="") { print "FAIL\t" id ": open deal missing next_step"  ; bad++ }
+      if (lt=="") { print "FAIL\t" id ": open deal missing last_touch" ; bad++ }
+    }
+
+    # 3 — stage in allowed set
+    allowed = (lstg ~ /^(prospecting|qualification|discovery|proposal\/demo|proposal|demo|negotiation|closed|closed won|closed lost)$/)
+    if (stg!="" && !allowed) { print "FAIL\t" id ": unknown stage \"" stg "\"" ; bad++ }
+
+    # 4 — win_prob numeric in [0,1]
+    if (wp ~ /^[0-9]*\.?[0-9]+$/) {
+      if (wp+0 < 0 || wp+0 > 1) { print "FAIL\t" id ": win_prob " wp " out of range [0,1]" ; bad++ }
+    } else if (wp != "") {
+      print "FAIL\t" id ": win_prob \"" wp "\" is not a number" ; bad++
+    }
+
+    # 5 — weighted_value == round(value * win_prob) within tol
+    if (val ~ /^[0-9]*\.?[0-9]+$/ && wp ~ /^[0-9]*\.?[0-9]+$/ && wv ~ /^[0-9]*\.?[0-9]+$/) {
+      expect = val*wp
+      diff = wv - expect; if (diff<0) diff=-diff
+      if (diff > tol) {
+        print "FAIL\t" id ": weighted_value " wv " != value*win_prob (" expect ")"
+        bad++
+      }
+    }
+  }
+  END {
+    if (!have_header) { print "NOHEADER" ; exit 0 }
+    print "META\t" rows "\t" bad+0 "\t" cov+0
+  }
+' "$FILE" > /tmp/sp_verify.$$ 2>/dev/null || true
+
+# Replay awk output into the colored reporter.
+NOHEADER=0; ROWS=0; BAD=0; COV=0
+while IFS=$'\t' read -r kind a b c; do
+  case "$kind" in
+    FAIL) fail "$a" ;;
+    NOHEADER) NOHEADER=1 ;;
+    META) ROWS="$a"; BAD="$b"; COV="$c" ;;
+  esac
+done < /tmp/sp_verify.$$
+rm -f /tmp/sp_verify.$$
+
+if [ "$NOHEADER" -eq 1 ]; then
+  printf '%sno header row with the required columns (need at least stage + win_prob)%s\n' "$RED" "$NC" >&2
+  exit 2
+fi
+
+# 1 — required columns reported only if a deal referenced a missing one is moot;
+# we re-derive column presence cheaply from the header line.
+HEADER_LINE="$(grep -iE 'win_prob' "$FILE" | head -1)"
+for c in id value stage win_prob weighted_value close_date next_step last_touch; do
+  if printf '%s' "$HEADER_LINE" | grep -iqw "$c"; then
+    :
+  else
+    fail "required column missing from header: $c"
+  fi
+done
+
+# 6 — coverage summary present
+if [ "$COV" -eq 1 ]; then
+  ok "coverage summary line present"
+else
+  fail "no coverage summary line found (need a line matching /coverage/)"
+fi
+
+if [ "${ROWS:-0}" -gt 0 ] && [ "${BAD:-0}" -eq 0 ]; then
+  ok "$ROWS deal row(s) — fields, stages, win_prob and weighted_value all valid"
+fi
+
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d failure(s)%s\n' "$RED" "$fail_count" "$NC"
+  exit 1
+fi
+printf '%sall checks passed%s\n' "$GREEN" "$NC"
+exit 0

package/skills/scaling/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: scaling
+description: "Use when traffic is growing or about to spike and the system bends under concurrency — deciding what to add and in what order (cache, connection pool, async queue, read replica, more instances) and proving it with a load test instead of guessing. Triggers: 'will we survive the launch spike', 'fine for me but dies under load', 'too many clients already', 'add caching or a read replica?', 'set RPS and p95 targets and load-test before go-live', the non-obvious 'DB connections are maxed out', and Catalan/Spanish 'aguantarem el pic de trànsit del llançament' / 'prepara un test de carga con objetivos de p95'. NOT making one slow request faster or profiling an N+1 (that is performance), NOT race-free Redis caches/locks/queue semantics (that is redis)."
+tags: [scaling, capacity, load-testing, caching, read-replicas, pgbouncer, k6, devops]
+recommends: [performance, redis, postgresdb, monitoring, deployment, backups, fly-io]
+profiles: []
+origin: risco
+---
+
+# Scaling: survive many requests at once
+
+Performance makes one request faster. Scaling makes many requests survive at the same time. Different problem, different toolbox — don't reach for this one when a single endpoint is slow for a single user (that is `../performance/SKILL.md`).
+
+The whole job in one line: **diagnose the bottleneck, apply the cheapest lever that moves it, re-measure under load.** Repeat until the next bottleneck appears or you hit your target.
+
+**Prime directive: never add infrastructure without a measurement first.** A replica, a queue, or a third app instance you bought on a hunch costs money every month and usually moves the wrong tier. Measure, then add.
+
+## Start here — order of operations
+
+Levers are ordered by payoff per dollar. Caching is nearly free and wins biggest; replicas and autoscaling cost forever. Climb the ladder in order; stop the moment the symptom clears.
+
+| Symptom | Likely bottleneck tier | First lever | Sibling that wires it |
+|---|---|---|---|
+| Slow *only* under load, fine solo | unknown — measure first | USE-method triage (Step 0) | `../monitoring/SKILL.md` |
+| Same reads recomputed for everyone | app/DB doing repeat work | Lever 1 — cache | `../redis/SKILL.md` |
+| `too many clients already` | DB connection slots | Lever 2 — pooler | `../postgresdb/SKILL.md` |
+| Spiky writes time out / drop | synchronous write path | Lever 2 — async queue | `../redis/SKILL.md` |
+| Reads dominate, primary CPU hot | DB read capacity | Lever 3 — read replica | `../postgresdb/SKILL.md` |
+| All tiers healthy, just need throughput | app instance count | Lever 4 — horizontal / autoscale | `../deployment/SKILL.md` |
+
+## Step 0 — find the bottleneck before you add anything
+
+Use the **USE method** (Utilization, Saturation, Errors) on every resource — CPU, memory, disk, network, and the DB connection pool. For each one ask: how busy (U), how much is queued/waiting (S), and any errors (E).
+
+- **Saturation predicts collapse earlier than utilization.** A CPU at 70% util with a growing run-queue is closer to falling over than one at 90% with no queue. Watch queue depth, run-queue length, and connection-pool wait time — those spike before throughput craters.
+- **Read p95/p99, never the mean.** The mean hides the tail your users actually feel; if p50 is 80 ms and p95 is 4 s, a meaningful slice of traffic is having a bad time and the average lies about it.
+- The dashboards, alerts, and SLOs that produce these numbers are `../monitoring/SKILL.md` / observability's job. Scaling *consumes* USE signals; it doesn't build the collectors.
+
+Output of Step 0 is one sentence: "the bottleneck is the DB connection pool / app CPU / origin cache-miss rate." Don't proceed without it.
+
+## Lever 1 — Caching (cheapest, do first)
+
+Cache layers, outermost to innermost — each one removes work the layer behind it would have done:
+
+| Layer | Removes | Typical TTL |
+|---|---|---|
+| CDN / edge | origin round-trip for static + cacheable HTML | minutes–hours |
+| HTTP cache headers (`Cache-Control`, `ETag`) | re-downloads; enables 304s | per-resource |
+| App cache (in-proc / Redis) | recomputed views, serialized payloads | seconds–minutes |
+| Query-result cache | repeated identical DB reads | seconds |
+
+- **Cache the expensive read, not the cheap one.** Caching a 2 ms lookup adds a network hop and an invalidation bug for nothing; cache the 400 ms aggregate everyone hits.
+- **Target >80% hit ratio for general traffic** (static-heavy/CDN routinely hits 95%+). A ratio consistently **<60%** means a broken strategy — wrong cache keys, TTL too low, or churny data that shouldn't be cached.
+- **Beware the cold-cache miss storm.** On deploy or cache flush, every request misses at once and stampedes the origin — the cache that was protecting you now amplifies the load. Mitigating that (stampede protection, single-flight, request coalescing) is cache *correctness* → `../redis/SKILL.md`.
+- If the underlying query is just slow, caching only hides it. Fix the query — N+1, missing index — via `../performance/SKILL.md` before papering over it with TTL.
+
+## Lever 2 — Connection pooling + queues
+
+**Pool DB connections.** Each Postgres connection is a backend process with real memory cost; apps that open a connection per request exhaust `max_connections` fast.
+
+```text
+Bad:  app → opens a fresh DB connection per request → "too many clients already"
+Good: app → PgBouncer (transaction mode) → small pool of reused server connections
+```
+
+- Use **transaction pooling** for stateless web apps: a server connection is held only for the duration of a transaction and released on COMMIT/ROLLBACK — reported real-world effect is roughly 100× effective connection capacity.
+- **Sizing rule:** keep `(number_of_pools × default_pool_size) < max_connections − ~15` (leave headroom for superuser/admin slots). Set `default_pool_size ≈ 1.5–2× vCores` for CPU-bound OLTP — more connections than cores just adds context-switch contention, not throughput.
+- **Gotcha — transaction pooling breaks session-scoped features:** prepared statements (pre-PG14 protocol), `SET` / session GUCs, advisory *session* locks, and `LISTEN/NOTIFY`. Route those to a session-pooling pool or refactor them out. Don't discover this in production.
+
+**Shed spiky writes into a queue.** Queue-based load leveling puts a queue between a bursty producer and a constrained consumer so the consumer drains at its own steady rate; the queue absorbs the spike instead of the synchronous tier melting.
+
+- Move anything that doesn't need a synchronous answer — emails, webhooks, thumbnails, exports — off the request path.
+- Queue *semantics* (race-free rate limits, stalled-job recovery, fencing tokens, durable `SKIP LOCKED` queues) belong to `../redis/SKILL.md` and `../postgresdb/SKILL.md`. Scaling decides *that* you defer work; those decide it's done correctly.
+
+## Lever 3 — Read replicas
+
+Reach for a replica only when Step 0 says **reads dominate and the primary is read-saturated** — not as a reflex.
+
+- **Replicas serve reads, never the source of truth for read-after-write.** Async streaming replication lags; a user who just wrote and immediately reads from a replica may see stale data. Route post-write reads (or that user's whole session for a window) to the primary, or use replica-lag-aware routing.
+- A replica is **not** a write-scaling story and **not**, by itself, an HA/backup story. Writes still all hit one primary; durability and recovery are `../backups/SKILL.md`.
+- Wiring the replication itself — `primary_conninfo`, slots, promotion — is `../postgresdb/SKILL.md`. Scaling decides *add a replica and route reads to it*; postgresdb makes it real.
+
+## Lever 4 — Horizontal scaling & autoscaling
+
+- **Make the app stateless first.** You can't horizontally scale what holds local state — in-memory sessions, sticky uploads on local disk, per-instance caches that must agree. Push session/state to Redis or the DB, then add instances freely.
+- **Autoscale on the saturation metric that actually binds, not CPU alone.** If the real limit is DB connections, scaling app instances on CPU just opens *more* connections and topples the DB faster. Scale on the bottleneck Step 0 found.
+- Choosing a host, rolling deploys, and the autoscaling dials are `../deployment/SKILL.md` plus the platform skill (`../fly-io/SKILL.md`, and siblings for railway/render/vercel). Scaling gives the strategy — how many and triggered by what; the platform gives the knobs.
+
+## Prove it — load testing with k6
+
+Don't claim the system survives. Measure that it does. **k6** (Go core, JS test scripts) reached v1.0.0 on 2025-04-28 under SemVer and is the default OSS load-test tool; the current v1 line is v1.7.x and v2.0.0 shipped in May 2026 (GrafanaCON 2026).
+
+- **Thresholds are the test's pass/fail SLO** — codify the target so the run goes red on its own instead of you eyeballing a graph.
+- **Test a prod-like target, never localhost.** Localhost has no network latency, no real DB, no CDN — it measures your laptop, not your system.
+- Run a ladder, not one shot: **smoke → load → stress → spike → soak** (find the *knee* where latency turns vertical).
+
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 },   // ramp up to 50 virtual users
+    { duration: '3m', target: 50 },   // hold (steady-state load test)
+    { duration: '1m', target: 0 },    // ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500'], // SLO gate: 95% of requests under 500 ms
+    http_req_failed: ['rate<0.01'],   // SLO gate: under 1% errors
+  },
+};
+
+export default function () {
+  const res = http.get(`${__ENV.TARGET_URL}/api/health`);
+  check(res, { 'status is 200': (r) => r.status === 200 });
+  sleep(1);
+}
+```
+
+Full ladder (stage configs for each test type), CI gate snippet, and how to read the summary (p95/p99, `http_req_failed`, spotting the knee) are in **`references/load-testing-k6.md`**.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Scaling before measuring | You spend on the wrong tier; symptom persists | Step 0 USE triage, name the bottleneck first |
+| Scaling a stateful app horizontally | Instances disagree; sessions vanish on routing | Make it stateless, externalize state, then scale |
+| Caching cheap work / no TTL strategy | Adds a hop + invalidation bugs for no gain | Cache the expensive read; set deliberate TTLs |
+| Load-testing localhost | Measures your laptop, not production | Test a prod-like target over the network |
+| Reporting mean latency | Hides the tail users actually feel | Gate on p95/p99 |
+| Read replica to absorb writes | Writes still hit one primary; you gain nothing | Replica is read-only; queue/shard writes |
+| DB with no connection pooler | `too many clients already` under any spike | PgBouncer transaction mode + the sizing rule |
+| Autoscaling on CPU while DB connections saturate | More instances = more connections = faster DB death | Autoscale on the binding saturation metric |
+
+## Stop rule & cost
+
+Scale to the *next* bottleneck, then re-measure — don't pre-buy capacity for traffic you don't have. Every lever has a price: caching is ~free, a pooler is cheap, a read replica and autoscaling cost every month and add operational surface. Climb one rung, re-run the load test, and stop when you clear the target. Survived, proven, no further — that's done.

package/skills/scaling/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — scaling
+
+These cases are routing and trigger fixtures, not an automated test harness. `should_trigger` lists prompts the `scaling` description and body must claim (including non-obvious and Catalan/Spanish phrasings); `should_not_trigger` lists near-miss prompts that belong to a real sibling, each tagged with the `route_to` id it should defer to (`performance`, `redis`, `postgresdb`, `monitoring`, `deployment`); `capability` is one launch-readiness scenario with a `must_include` rubric. To run them, read each prompt against `../SKILL.md` and confirm by hand that triggers fire, non-triggers route to the named sibling, and a real answer to the capability scenario covers every rubric line — or feed this file to the repo's eval runner if one is present. The k6 artifacts themselves are checked separately by `../scripts/verify.sh`.

package/skills/scaling/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: scaling
+
+should_trigger:
+  - prompt: "We're launching on Product Hunt Monday — will our app survive the traffic?"
+    why: "Core spike-survival / capacity question; the canonical reason to reach for scaling."
+  - prompt: "Postgres is throwing `too many clients already` in production."
+    why: "Connection-pool exhaustion under concurrency — the pooler lever (Lever 2), a non-obvious surface that reads like a DB error but is a capacity decision."
+  - prompt: "Should I add caching or a read replica to handle our growth?"
+    why: "Direct lever-choice between Lever 1 and Lever 3; scaling exists to order these."
+  - prompt: "The site is snappy when I test it but crawls once real users hit it at the same time."
+    why: "Non-obvious: sounds like latency but it's a concurrency bottleneck — performance for one user, scaling for many at once."
+  - prompt: "Prepara un test de carga con objetivos de p95 antes del lanzamiento."
+    why: "Spanish — load testing with p95 SLO targets to prove capacity before go-live (k6 + thresholds)."
+  - prompt: "Aguantarem el pic de trànsit del llançament o cau el servidor?"
+    why: "Catalan — explicit traffic-spike survival question, the heart of the skill."
+
+should_not_trigger:
+  - prompt: "This one endpoint takes 3s — find the N+1 and make it fast."
+    route_to: performance
+    why: "Single-request latency / profiling for one user, not concurrency capacity."
+  - prompt: "Make my Redis rate limiter race-free and fix the cache stampede."
+    route_to: redis
+    why: "Cache/queue *correctness* and concurrency semantics, not the whether/where decision scaling makes."
+  - prompt: "Set up streaming replication and the archive_command on Postgres."
+    route_to: postgresdb
+    why: "DB-internal wiring of the replica; scaling decides to add one, postgresdb implements it."
+  - prompt: "Build a Grafana dashboard and p95 alerts for our API."
+    route_to: monitoring
+    why: "Observability / dashboards. Scaling consumes USE signals but doesn't build the collectors."
+  - prompt: "Write the Dockerfile and rolling-deploy config to ship the service."
+    route_to: deployment
+    why: "Packaging and shipping instances; scaling decides how many and when to autoscale, deployment ships them."
+
+capability:
+  - scenario: "Our SaaS expects ~10x traffic next week after a press feature. Stack is a Node API on two small instances behind a load balancer, a single Postgres primary (no pooler), and a CDN for static assets only. Sessions live in app memory. What do we do, in what order, to be ready — and how do we know it'll hold?"
+    must_include:
+      - "Measure first via the USE method (utilization/saturation/errors per tier) and read p95/p99 not the mean before adding anything."
+      - "Caching as the first lever — cache the expensive repeated reads, target >80% hit ratio, and warn about the cold-cache miss storm hitting the origin."
+      - "Put PgBouncer in transaction mode in front of the single primary, with the sizing constraint (pools × default_pool_size < max_connections − ~15; pool ≈ 1.5–2× vCores) — directly addresses the no-pooler risk under 10x."
+      - "Add a read replica ONLY if measurement shows reads dominate and the primary is read-saturated, with the read-after-write/replica-lag caveat (route post-write reads to primary)."
+      - "Make the app stateless (move in-memory sessions out) before scaling instances horizontally, and autoscale on the binding saturation metric, not CPU alone."
+      - "Prove the target with a k6 load test against a prod-like / staging environment (not localhost), gated on thresholds like http_req_duration p(95)<500 and http_req_failed rate<0.01, climbing the smoke→load→stress→spike ladder to find the knee."