rsc-universal 0.1.1

package/skills/react-native/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: react-native
+
+should_trigger:
+  - prompt: "Scaffold an Expo Router app with auth-gated tabs and typed routes."
+    why: "Project shape + navigation gating is the core app-code surface this skill owns."
+  - prompt: "My product list re-renders every visible row on each keystroke in the search box — how do I stop it?"
+    why: "Non-obvious render-storm symptom; the fix (memoized rows, debounced query, virtualization) lives here, not in expo."
+  - prompt: "Write a native module wrapping the iOS HealthKit / Android Health Connect SDK for my Expo app."
+    why: "Native-module authoring (Expo Modules API vs Turbo Module) is explicitly this skill's territory."
+  - prompt: "La llista de productes pateix lag quan faig scroll en una FlatList de 5000 items."
+    why: "Catalan list-jank phrasing; FlashList migration + getItemType is the answer this skill gives."
+  - prompt: "Deep link opens the app but lands on the wrong screen instead of the nested tab."
+    why: "Deep-link/group-segment mismatch is app-routing, owned here; not a build/OTA concern."
+  - prompt: "My swipe gesture drops mid-drag and the recognizer seems to reset on every render."
+    why: "Gesture-object-in-useMemo issue; UI-thread/worklet reasoning is this skill's animation section."
+
+should_not_trigger:
+  - prompt: "eas build fails with a provisioning profile error."
+    route_to: expo
+    why: "Build pipeline / signing is the expo half of the verb test, not app code."
+  - prompt: "Rebuild the same app in Flutter with the same screens."
+    route_to: flutter
+    why: "Dart/Flutter toolchain, different framework entirely."
+  - prompt: "My Next.js server component won't render the product list."
+    route_to: nextjs
+    why: "Web React / SSR, DOM primitives — not React Native."
+  - prompt: "Cut a 1.4.0 release and tag the CI pipeline for it."
+    route_to: ship
+    why: "Release orchestration / CI, not in-app code."
+  - prompt: "My OTA update isn't showing up on devices after publish."
+    route_to: expo
+    why: "OTA update channels/runtime-version belong to the expo pipeline."
+
+capability:
+  - scenario: "A long product feed janks while scrolling on Android (smooth on iOS). The team is on Expo SDK 54 and wants it back to 60fps."
+    must_include:
+      - "Profile re-renders first (React DevTools Profiler / why-did-you-render) rather than guessing."
+      - "Migrate FlatList to FlashList with getItemType for structurally different rows."
+      - "Memoized row component with a stable keyExtractor (domain id, not index) and no inline closures/styles in renderItem."
+      - "Move scroll-driven animation to a Reanimated worklet on the UI thread, or disable entry animations on initial mount to stop the position flash."
+      - "Confirm the New Architecture is on and that no dependency is forcing the legacy interop path; do not set newArchEnabled:false."
+      - "Note React Compiler (SDK 54) reduces manual memo but does not remove virtualization / list discipline."

package/skills/react-native/references/native-modules.md

@@ -0,0 +1,123 @@
+# Native modules — full walkthrough
+
+When a maintained npm package already bridges the native API, use it and stop. Author a module only when there is no maintained wrapper, you need an API the wrapper doesn't expose, or you're shipping the SDK yourself.
+
+## Decision recap
+
+- **Expo Modules API** — Swift/Kotlin, no codegen, ergonomic DSL. Requires the app to use Expo. Lowest boilerplate; the default for Expo apps.
+- **Turbo Module** — codegen from TypeScript/Flow spec files. The RN-default path; works in bare RN. More boilerplate, fully typed across the boundary.
+- **Nitro Modules** — emerging high-performance option for hot paths. Weigh maturity before betting a shipping feature on it.
+
+## Expo Modules API — full example
+
+A module that exposes a function, a constant, an event, and a native view.
+
+```swift
+// ios/HealthModule.swift
+import ExpoModulesCore
+
+public class HealthModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("HealthModule")
+
+    Constants(["isAvailable": HKHealthStore.isHealthDataAvailable()])
+
+    Events("onStepsUpdate")
+
+    AsyncFunction("readSteps") { (start: Double, end: Double) -> Int in
+      // query HealthKit, return a step count
+      return 0
+    }
+
+    View(HealthChartView.self) {
+      Prop("range") { (view: HealthChartView, range: String) in
+        view.setRange(range)
+      }
+    }
+  }
+}
+```
+
+```kotlin
+// android/src/main/java/com/app/HealthModule.kt
+package com.app
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class HealthModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("HealthModule")
+    Constants("isAvailable" to HealthConnectClient.isAvailable())
+    Events("onStepsUpdate")
+    AsyncFunction("readSteps") { start: Double, end: Double ->
+      // query Health Connect, return a step count
+      0
+    }
+    View(HealthChartView::class) {
+      Prop("range") { view: HealthChartView, range: String -> view.setRange(range) }
+    }
+  }
+}
+```
+
+```ts
+// src/HealthModule.ts — the typed JS surface
+import { requireNativeModule, requireNativeViewManager } from 'expo-modules-core';
+
+type HealthNative = {
+  isAvailable: boolean;
+  readSteps(start: number, end: number): Promise<number>;
+  addListener(event: 'onStepsUpdate', cb: (e: { steps: number }) => void): { remove(): void };
+};
+
+const Native = requireNativeModule<HealthNative>('HealthModule');
+
+export const isHealthAvailable = Native.isAvailable;
+export const readSteps = (start: Date, end: Date) =>
+  Native.readSteps(start.getTime(), end.getTime());
+export const HealthChartView = requireNativeViewManager('HealthModule');
+```
+
+Notes:
+- `AsyncFunction` returns a Promise to JS without blocking the UI thread; use `Function` only for cheap synchronous calls.
+- `Constants` are read once at module init — don't use them for values that change.
+- Events: emit from native with `sendEvent("onStepsUpdate", ...)`; JS subscribes via `addListener`.
+
+## Turbo Module — codegen spec walkthrough
+
+Turbo Modules generate native interfaces from a TS spec. The spec file name must start with `Native`.
+
+```ts
+// specs/NativeHealth.ts
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  readonly isAvailable: () => boolean;
+  readSteps(start: number, end: number): Promise<number>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('Health');
+```
+
+Configure codegen in `package.json`, then `pod install` (iOS) / build (Android) runs codegen and emits the C++/ObjC++/Java interfaces you implement:
+
+```json
+{
+  "codegenConfig": {
+    "name": "RNHealthSpec",
+    "type": "modules",
+    "jsSrcsDir": "specs"
+  }
+}
+```
+
+You then implement the generated protocol in Objective-C++/Swift and the generated abstract class in Java/Kotlin. The contract is enforced at build time — a signature mismatch fails codegen rather than crashing at runtime.
+
+## Packaging & autolinking
+
+- Expo Modules in a library: ship an `expo-module.config.json` so autolinking discovers it; the host app needs no manual linking.
+- Turbo Module in a library: a `react-native.config.js` / podspec drives autolinking.
+- Test on a **real device** for anything touching sensors, permissions, or background work — simulators lie about HealthKit, Bluetooth, and camera.
+- Version-gate native APIs (HealthKit availability, Health Connect install state) before calling; expose the gate as a JS-readable constant so the UI can degrade gracefully.

package/skills/react-native/references/performance-debugging.md

@@ -0,0 +1,46 @@
+# Performance & debugging deep dive
+
+## Re-render profiling
+
+Before optimizing, measure. Don't guess which component re-renders.
+
+1. Open React DevTools Profiler, record, do the slow interaction (scroll, type), stop. Components that flash on every commit are your targets.
+2. Highlight updates / the Profiler's "why did this render" tells you whether props, state, or context changed.
+3. `why-did-you-render` (dev-only) logs the exact prop that changed reference. Useful for the classic "new object/array literal every render" leak.
+
+With React Compiler on (SDK 54+), most manual `useMemo`/`useCallback` are redundant — but the compiler can't memoize across a virtualized list boundary, so list-row discipline still matters.
+
+The keystroke re-render storm: a search box whose `onChangeText` calls `setState` at the screen root re-renders the whole list on each character. Fix by either (a) keeping the input state local to a memoized search component and debouncing the query, or (b) deriving filtered data with a stable selector so only the list body recommits.
+
+## FlashList tuning knobs
+
+- `getItemType` — return a discriminator (`'header' | 'product' | 'ad'`). Recycling happens within a type; mixing types without it forces remeasures.
+- `keyExtractor` — stable domain id, never index.
+- Disable entry/layout animations on the **initial** mount — rows can flash into the wrong position for a split second when mounted while animations run.
+- Keep `renderItem` pure: no inline closures, no inline style objects, memoized row component.
+- For images, use a caching image component and fixed dimensions so layout doesn't thrash during scroll.
+
+## Reanimated thread model
+
+- Worklets run on the **UI thread**; shared values mutate there without a JS round-trip, so motion survives a busy JS thread.
+- A worklet calling a plain JS function crashes — cross back only via `runOnJS(fn)(...args)`, and only at the boundary (gesture end, completion callback).
+- Build gesture objects in `useMemo`; a fresh object each render reattaches the recognizer and drops in-flight touches.
+- Reanimated 4 needs the New Architecture / RN 0.76+. Reanimated 4 CSS animations cover simple declarative motion; reserve worklets for gesture-driven or physics-based animation.
+
+## Hermes crash triage
+
+- Read Hermes stack traces bottom-up; the meaningful JS frame usually sits just above the native bridge frames.
+- Symbolicate release crashes against the matching source map — an un-symbolicated trace is just addresses.
+- A red screen citing the interop layer under Fabric almost always means an old-architecture dependency. Update it or replace it with a New-Arch-ready package. Do not set `newArchEnabled: false` — it is a no-op on RN 0.82+/SDK 55 and only hides the cause.
+
+## Platform-divergence checklist
+
+When something works on one platform and breaks on the other, walk this before guessing:
+
+1. Is there a `.ios.tsx`/`.android.tsx` fork or a `Platform.select` branch diverging behavior?
+2. `KeyboardAvoidingView` behavior prop — `padding` (iOS) vs `height`/none (Android)?
+3. Safe-area insets — hardcoded padding that only fits one device family?
+4. Permissions — declared in `Info.plist` (iOS) and `AndroidManifest.xml` (Android), requested at runtime on both?
+5. A native dependency that ships only one platform's implementation, or differs in New-Arch readiness?
+6. Shadow/elevation — `shadow*` (iOS) vs `elevation` (Android) styled separately?
+7. Default font, line height, and ripple/highlight feedback differ — is the divergence cosmetic and expected, or a real bug?

package/skills/react-native/scripts/verify.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static hygiene/currency check for the react-native skill content.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]    # defaults to the skill dir (this script's parent's parent)
+#
+# Greps SKILL.md + references/ for currency and rsc-hygiene violations and prints each hit
+# with a fix hint. Read-only: never edits a file. On a clean tree — or a target with no
+# SKILL.md at all — it prints an ok line and exits 0 (no false failure). Exits 1 only when a
+# violation is present, so it doubles as a non-blocking lint signal.
+#
+# Compatible with stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TARGET="${1:-$(dirname "$SCRIPT_DIR")}"
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+
+if [ ! -e "$TARGET" ]; then
+  printf '%serror:%s target path %s does not exist.\n' "$RED" "$RESET" "$TARGET" >&2
+  exit 2
+fi
+
+SKILL="$TARGET/SKILL.md"
+
+# Empty/clean target with no skill content: nothing to check, succeed.
+if [ ! -f "$SKILL" ]; then
+  printf '%s[ ok ]%s no SKILL.md under %s — nothing to check.\n' "$GREEN" "$RESET" "$TARGET"
+  exit 0
+fi
+
+findings=0
+
+flag() { # message + matching lines
+  findings=1
+  printf '%s[finding]%s %s\n' "$YELLOW" "$RESET" "$1"
+  [ -n "${2:-}" ] && printf '%s\n' "$2" | sed 's/^/    /'
+}
+
+md_files() { # SKILL.md + every references/*.md
+  printf '%s\n' "$SKILL"
+  [ -d "$TARGET/references" ] && find "$TARGET/references" -name '*.md' 2>/dev/null || true
+}
+
+# 1) No currency regression: never recommend disabling the New Architecture.
+hits="$(grep -REn -- 'newArchEnabled:[[:space:]]*false' $(md_files) 2>/dev/null \
+        | grep -Eiv 'no-op|never|do not|don.t|dodge|hides' || true)"
+[ -n "$hits" ] && flag "newArchEnabled:false recommended -> New Arch is mandatory (RN 0.82+/SDK 55); fix the bug instead" "$hits"
+
+# 2) The performance section must not push FlatList without the FlashList threshold.
+if grep -qiE 'FlatList' "$SKILL" 2>/dev/null; then
+  if ! grep -qiE 'FlashList' "$SKILL" 2>/dev/null; then
+    flag "SKILL.md mentions FlatList but never FlashList -> add the FlashList migration threshold"
+  fi
+fi
+
+# 3) Every fenced code block must be language-tagged (no bare ``` opener).
+#    Count fence lines; opener lines (odd occurrences) must carry a language token.
+bare="$(grep -nE '^```[[:space:]]*$' "$SKILL" 2>/dev/null || true)"
+if [ -n "$bare" ]; then
+  # A bare ``` is a violation only if it is an opener. Heuristic: flag any bare fence that
+  # is immediately followed (within the file) by indented/code-looking content is hard in
+  # sh; simplest correct rule for rsc skills: openers must be tagged, closers are bare. So a
+  # bare fence is fine as a CLOSER. We detect unbalanced/untagged openers by checking that
+  # the number of tagged openers + bare closers is consistent. Practical check: ensure no
+  # two consecutive bare fences (which would mean an untagged opener+closer pair).
+  prev_bare=""
+  while IFS= read -r line; do
+    case "$line" in
+      '```'|'``` ') cur_bare="yes" ;;
+      '```'*) cur_bare="no" ;;
+      *) continue ;;
+    esac
+    if [ "$cur_bare" = "yes" ] && [ "$prev_bare" = "yes" ]; then
+      flag "two consecutive bare \`\`\` fences -> the opener is untagged; tag it (e.g. \`\`\`tsx)"
+      break
+    fi
+    prev_bare="$cur_bare"
+  done < "$SKILL"
+fi
+
+# 4) Description must carry the Triggers: label and a NOT-boundary.
+desc="$(grep -m1 -E '^description:' "$SKILL" 2>/dev/null || true)"
+if [ -n "$desc" ]; then
+  printf '%s' "$desc" | grep -q 'Triggers:' || flag "description missing 'Triggers:' label"
+  printf '%s' "$desc" | grep -qE 'NOT ' || flag "description missing a 'NOT <x> (that is <sibling>)' boundary"
+fi
+
+# 5) No cross-ref to a sibling that does not exist on disk next to this skill.
+SKILLS_ROOT="$(dirname "$TARGET")"
+refs="$(grep -hoE '\.\./[a-z0-9-]+/SKILL\.md' $(md_files) 2>/dev/null | sort -u || true)"
+if [ -n "$refs" ]; then
+  OLDIFS="$IFS"; IFS='
+'
+  for r in $refs; do
+    sib="$(printf '%s' "$r" | sed -E 's#\.\./([a-z0-9-]+)/SKILL\.md#\1#')"
+    if [ ! -f "$SKILLS_ROOT/$sib/SKILL.md" ]; then
+      flag "cross-ref to ../$sib/SKILL.md but no such sibling on disk -> remove or fix the link"
+    fi
+  done
+  IFS="$OLDIFS"
+fi
+
+if [ "$findings" -eq 0 ]; then
+  printf '%s[ ok ]%s react-native skill content passes hygiene/currency checks.\n' "$GREEN" "$RESET"
+  exit 0
+fi
+
+printf '%s[note]%s findings above are advisory; fix before shipping the skill.\n' "$RED" "$RESET"
+exit 1

package/skills/redis/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: redis
+description: "Use when using Redis (or Valkey/ElastiCache/Upstash/Dragonfly/Memorystore — any Redis-protocol store) as a cache, queue, rate limiter, or distributed lock and you need it CORRECT, not just connected: stampede-proof caching, locks that don't release someone else's hold, race-free rate limits, jobs that survive a worker crash. Triggers: 'cache stampede', 'thundering herd', 'distributed lock', 'SET NX PX', 'Redlock', 'fencing token', 'rate limiter race', 'INCR then EXPIRE', 'BullMQ stalled jobs', 'XREADGROUP / XAUTOCLAIM', 'maxmemory-policy', 'KEYS * in prod', 'lock released by the wrong owner', 'limitador de peticiones', 'bloqueig distribuït', 'la cau s'invalida malament'. NOT durable SQL queues with SELECT FOR UPDATE SKIP LOCKED (that is postgresdb), NOT vector similarity search over embeddings (that is vector-db)."
+tags: [redis, valkey, cache, rate-limiting, distributed-locks, queues, bullmq, streams, lua, data-infra]
+recommends: [postgresdb, vector-db, clickhouse-analytics, scaling, nodejs, fly-io]
+profiles: []
+origin: risco
+---
+
+# Redis — cache, lock, rate limiter, queue done correctly
+
+Redis is four primitives wearing one server: a **cache**, a **distributed lock**, a **rate
+limiter**, and a **job queue**. Each has a correctness contract that has nothing to do with
+whether `SET` returns `OK`. You almost certainly already "have Redis working" — a value goes
+in, a value comes out. What you do not yet have is a cache that won't stampede your database, a
+lock that won't release someone else's hold, a rate limiter that survives concurrent requests,
+and a queue whose jobs aren't silently lost when a worker dies. This skill is engine- and
+pattern-level, **client-SDK-agnostic**: examples are `redis-cli` and Lua, so they hold across
+node-redis, ioredis, redis-py, go-redis, and Lettuce. Every pattern applies unchanged to Valkey
+and any Redis-protocol store, since Valkey is a BSD fork of Redis 7.2 and stays protocol-compatible.
+
+## When to use / When NOT
+
+**Use when you are:**
+
+- Adding or reviewing a **cache**: TTL strategy, cache-aside vs write-through, key naming,
+  stampede/thundering-herd prevention, negative caching, invalidation.
+- Building a **distributed lock**: "only one worker does X", cron de-duplication, leader-ish
+  mutual exclusion — the `SET NX PX` + Lua-release + fencing-token contract, and the Redlock call.
+- Building a **rate limiter**: per-user/IP/API-key throttling (fixed window, sliding-window log,
+  sliding-window counter, token bucket) and why naive `INCR`+`EXPIRE` is a race.
+- Running a **queue / background jobs on Redis**: Lists vs Streams vs a library (BullMQ, Sidekiq,
+  RQ, Celery), at-least-once delivery, acks, stalled-job recovery, idempotency.
+- Deciding **eviction & persistence**: `maxmemory-policy`, RDB vs AOF, cache mode vs database mode.
+- Reviewing Redis code for foot-guns: `KEYS *`, unbounded keys, non-atomic read-modify-write,
+  missing TTL, a lock released by the wrong owner.
+
+**NOT for (route instead):**
+
+- Durable SQL queue (`SELECT … FOR UPDATE SKIP LOCKED`), engine-level SQL caching →
+  [`../postgresdb/SKILL.md`](../postgresdb/SKILL.md). Boundary: if the *durable store* is the
+  queue, that's postgresdb; if *Redis* is the queue, you're here.
+- Vector similarity / semantic search as the primary job →
+  [`../vector-db/SKILL.md`](../vector-db/SKILL.md). Redis 8 vector sets are only *noted* here.
+- Analytical / clickstream event store → [`../clickhouse-analytics/SKILL.md`](../clickhouse-analytics/SKILL.md).
+- System-level capacity / load strategy, and app/CDN/HTTP-layer caching (Cache-Control, ISR, edge) →
+  [`../scaling/SKILL.md`](../scaling/SKILL.md). This skill owns the Redis-specific data contract underneath.
+- Provisioning a managed Redis (cluster sizing, dashboards) →
+  [`../fly-io/SKILL.md`](../fly-io/SKILL.md) / [`../aws-essentials/SKILL.md`](../aws-essentials/SKILL.md).
+  This skill gives the client-side contract, not console clicks.
+- Language-runtime async/job concepts unrelated to Redis → [`../nodejs/SKILL.md`](../nodejs/SKILL.md)
+  or your language skill.
+
+## Non-negotiables
+
+1. **Every cache key has a TTL.** No TTL in a cache = a memory leak that eventually evicts or 500s.
+2. **Never `KEYS *` in production — use `SCAN`.** `KEYS` is O(N) and blocks the single thread;
+   one bad pattern freezes every client.
+3. **Read-modify-write must be atomic.** App-side `GET` then `SET`/`INCR` races under concurrency.
+   Use one Lua `EVAL`, a single atomic command, or `WATCH`/`MULTI`.
+4. **A lock = random token + `PX` + Lua compare-and-delete.** Plain `DEL` releases whoever holds it
+   now (maybe not you); a lock with no `PX` is held forever if the owner crashes.
+5. **Pick `maxmemory-policy` deliberately.** The default `noeviction` makes a full cache fail every
+   write — correct for a database, fatal for a cache.
+6. **A queue must ack and recover.** `RPOP` straight into a worker loses the job if the worker dies
+   mid-task; use a processing list or Streams consumer groups.
+7. **Cap unbounded structures.** Lists grow forever without `LTRIM`; streams without `MAXLEN ~`.
+8. **One Lua = one short atomic step.** Redis is single-threaded; a long script or huge `MULTI/EXEC`
+   blocks *all* clients, not just yours.
+9. **Namespace keys** as `svc:entity:id` (e.g. `cart:user:42`) so scans, eviction, and humans can reason.
+10. **Know cache vs database durability before choosing persistence.** Cache = lose-it-and-rebuild;
+    database = RDB/AOF and `noeviction`. Decide which Redis is *before* you tune it.
+
+## Decision table — which primitive, which structure
+
+| Need | Structure | Canonical commands | The one gotcha |
+| --- | --- | --- | --- |
+| Cache | string / hash + TTL | `SET k v EX 300` / `GETEX` / `HSET`+`EXPIRE` | stampede on expiry |
+| Lock | string + random token | `SET k tok NX PX 30000` + Lua compare-and-`DEL` | wrong-owner release |
+| Rate limit | string / zset / hash | one atomic `EVAL` (window/log/bucket) | lost `EXPIRE` → immortal counter |
+| Queue (simple) | list | `LMOVE src proc LEFT RIGHT` / `BRPOPLPUSH` | job loss on crash without a processing copy |
+| Queue (reliable) | stream | `XADD` / `XREADGROUP` / `XACK` / `XAUTOCLAIM` | unacked PEL grows unbounded |
+
+## Caching
+
+**Namespace + TTL with jitter.** A fixed TTL on a batch of keys written together synchronizes their
+expiry — they all die in the same second and stampede the origin at once. Add jitter.
+
+```bash
+# Bad: 1000 keys warmed in a loop with the same TTL all expire together
+SET product:42 "$json" EX 300
+# Good: spread expiry with per-key jitter (300s ± up to 60s)
+SET product:42 "$json" EX $(( 300 + RANDOM % 60 ))
+```
+
+**Cache-aside (read path).** *Why:* it is the default for read-heavy data; the trap is forgetting
+the TTL and forgetting to cache the miss.
+
+```text
+# Bad: cache only hits, never the miss → every request for an absent id hits the DB
+val = GET product:42
+if val == nil: val = db.fetch(42); SET product:42 val EX 300   # absent rows still hammer the DB
+
+# Good: cache-aside with negative caching
+val = GET product:42
+if val == "__MISS__": return null                              # cached miss, no DB call
+if val == nil:
+    val = db.fetch(42)
+    if val == null: SET product:42 "__MISS__" EX 30            # short negative TTL
+    else:           SET product:42 val EX 300
+```
+
+**Stampede prevention.** When a hot key expires, N concurrent requests all miss and hammer the
+origin. Two mitigations:
+
+- **Recompute lock** — one request rebuilds, the rest briefly serve stale or wait. *The lock TTL
+  must exceed worst-case origin latency*, or two requests rebuild anyway.
+
+  ```bash
+  # On miss, try to claim the rebuild; only the winner recomputes
+  SET product:42:lock 1 NX PX 5000   # 5s > slowest DB rebuild
+  # winner: rebuild, SET product:42, then DEL product:42:lock
+  # losers: serve last-known value or retry after a short sleep
+  ```
+
+- **Probabilistic early expiration (XFetch)** — refresh *before* TTL with rising probability so one
+  request renews early while others still hit a warm key. Math + write-through/read-through/
+  write-behind in [`references/caching.md`](references/caching.md).
+
+**Invalidation:** on write, either delete the key (next read rebuilds) or write-through. Never rely on
+manual invalidation *instead of* a TTL — you will miss a path and serve stale forever.
+
+## Distributed locks
+
+```bash
+# Bad: GET-then-DEL races — between your GET and DEL the lock can expire and a NEW owner takes it,
+#      and your DEL frees THEIR lock.
+GET resource:lock        # == my token?
+DEL resource:lock        # ← may delete someone else's lock
+
+# Good: claim with a random token + PX, release only if the token is still mine (atomic Lua).
+SET resource:lock "$TOKEN" NX PX 30000     # NX = only if absent; PX = auto-expire so a crash frees it
+```
+
+Release **must** be a compare-and-delete in one Lua step:
+
+```lua
+-- KEYS[1] = lock key, ARGV[1] = my token. Returns 1 if I held and released it, else 0.
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+else
+  return 0
+end
+```
+
+**TTL vs work duration.** If the protected work can outlast `PX`, the lock expires mid-task and a
+second worker starts. Either size `PX` above the worst case, or run a watchdog that renews the TTL
+(again via a token-checked Lua `PEXPIRE`) while work continues — never blindly `PEXPIRE`.
+
+**Fencing tokens.** A GC pause or a long syscall can freeze the lock holder *past* expiry; another
+worker acquires, then the paused one wakes and writes — both think they hold the lock. The only fix
+is a **fencing token**: a monotonically increasing number issued with the lock and checked by the
+protected resource, which rejects any write carrying a stale token. No Redis lock alone provides this.
+
+> **Redlock decision.** Single-instance `SET NX PX` is fine when occasional double-execution is
+> *tolerable* (idempotent work, best-effort cron de-dup). For *hard* mutual exclusion, a single
+> Redis lock is not enough and multi-instance Redlock is contested (it assumes bounded clock drift
+> and no long pauses) — **fence the resource or use a lease/consensus system**. Full Redlock
+> walk-through and critique in [`references/locks-and-rate-limiting.md`](references/locks-and-rate-limiting.md).
+
+## Rate limiting
+
+```text
+# Bad: GET/INCR then EXPIRE as two steps. If the process dies (or loses the race) between INCR and
+#      EXPIRE, the key has NO TTL and counts forever — the user is throttled permanently.
+n = INCR rl:user:42
+if n == 1: EXPIRE rl:user:42 60     # ← may never run
+```
+
+Fixed window, done atomically in one `EVAL`:
+
+```lua
+-- KEYS[1] = counter, ARGV[1] = limit, ARGV[2] = window seconds. Returns 1 = allow, 0 = deny.
+local n = redis.call('INCR', KEYS[1])
+if n == 1 then redis.call('EXPIRE', KEYS[1], ARGV[2]) end   -- TTL set atomically with the first hit
+if n > tonumber(ARGV[1]) then return 0 end
+return 1
+```
+
+Fixed window allows up to 2× the limit across a boundary. For smoother limits:
+
+- **Sliding-window log** — a sorted set scored by timestamp, pruned and counted in one Lua:
+  `ZREMRANGEBYSCORE` (drop entries older than the window) → `ZCARD` (count) → `ZADD` (record now) →
+  `EXPIRE`. Exact, but O(requests) memory per key.
+- **Token bucket** — a hash holding `{tokens, last_refill}`; refill by elapsed time and decrement,
+  all in one Lua. Allows bursts up to bucket size, then a steady rate. Smallest memory.
+
+Choose by accuracy-vs-memory; full Lua for all four in
+[`references/locks-and-rate-limiting.md`](references/locks-and-rate-limiting.md).
+
+## Queues
+
+| Option | When | Acks / recovery |
+| --- | --- | --- |
+| **List** | simplest at-least-once, low volume | manual: processing list + requeue stalled |
+| **Stream** | reliable jobs, consumer groups, native acks | `XACK` + `XAUTOCLAIM` for stalled/pending |
+| **Library** (BullMQ/Sidekiq/RQ/Celery) | you want retries, scheduling, a dashboard | built-in; don't hand-roll |
+
+**Reliable list:** never `RPOP` straight into the worker — a crash mid-task loses the job. Move it to
+a per-worker processing list atomically, then ack by removing it.
+
+```bash
+job=$(redis-cli LMOVE jobs jobs:proc:w1 LEFT RIGHT)   # atomic: pop from jobs, push to processing
+# ... do work (idempotently) ...
+redis-cli LREM jobs:proc:w1 1 "$job"                  # ack: remove from processing
+# a reaper requeues anything left in jobs:proc:* after a worker dies
+```
+
+**Streams (preferred for reliable jobs):** consumer groups give per-message acks and a Pending
+Entries List for recovery.
+
+```bash
+redis-cli XGROUP CREATE jobs g1 '$' MKSTREAM
+redis-cli XREADGROUP GROUP g1 worker1 COUNT 10 BLOCK 5000 STREAMS jobs '>'
+# ... process ...
+redis-cli XACK jobs g1 "$id"                          # ack a done message
+redis-cli XAUTOCLAIM jobs g1 worker2 60000 0          # reclaim messages idle > 60s (stalled worker)
+```
+
+Delivery is **at-least-once**: a message can be reprocessed after a crash, so make handlers
+idempotent (dedupe on a job id / idempotency key). Reach for **BullMQ** (TypeScript; stalled-job lock
+renewal via `lockDuration`/`lockRenewTime`), **Sidekiq** (Ruby), or **RQ**/**Celery** (Python) when
+you want retries, delays, and a dashboard — don't reinvent them. Full implementations, DLQ, and the
+library comparison in [`references/queues.md`](references/queues.md).
+
+## Eviction & persistence
+
+| `maxmemory-policy` | Behavior | Use for |
+| --- | --- | --- |
+| `noeviction` (default) | writes fail when full | Redis-as-database (durable data you can't drop) |
+| `allkeys-lru` / `allkeys-lfu` | evict any key by recency / frequency | a pure cache (every key is disposable) |
+| `volatile-lru` / `volatile-ttl` / `volatile-lfu` | evict **only keys that have a TTL** | mixed: durable keys without TTL stay |
+
+A "cache" running `noeviction` with no TTLs is a memory leak that starts 500ing writes when full —
+the single most common Redis incident. Set `maxmemory` *and* an `allkeys-*` policy for a cache.
+
+**Persistence:** RDB = periodic point-in-time snapshots (fast restart, can lose the last interval);
+AOF = append every write (durable, slower, larger). A pure cache often needs *neither* — losing it
+just rebuilds from the origin. Decide cache-mode vs database-mode first, then persistence follows.
+
+## Anti-patterns → STOP
+
+| Rationalization | What actually happens | Do instead |
+| --- | --- | --- |
+| "`INCR` then `EXPIRE` is fine" | a lost `EXPIRE` leaves a TTL-less counter → immortal throttle | one atomic `EVAL` (set TTL when `n == 1`) |
+| "I'll `GET` then `DEL` the lock" | races; frees a *different* owner's lock | random token + Lua compare-and-delete |
+| "`KEYS user:*` to find my keys" | O(N), blocks the single thread, freezes all clients | `SCAN MATCH user:* COUNT 100` |
+| "No TTL, I'll invalidate manually" | you miss a path → stale forever + unbounded memory | TTL on every cache key, always |
+| "Redlock means the lock is safe" | a GC pause double-acquires; clock-drift assumptions | fence the resource, or accept double-run on idempotent work |
+| "`RPOP` the job into the worker" | worker dies mid-task → job vanishes | `LMOVE` to a processing list, or Streams + `XACK` |
+| "Big `MULTI` / long Lua = throughput" | single thread blocks every client for the duration | keep each atomic step short; chunk the work |
+| "Fixed-window limiter is exact" | allows ~2× the limit across the window boundary | sliding-window log or token bucket if exactness matters |
+
+## Quick reference
+
+```bash
+# Cache:      SET k v EX 300 | GETEX k EX 300 | DEL k | SCAN 0 MATCH 'product:*' COUNT 100
+# Lock:       SET k tok NX PX 30000  (release via the Lua compare-and-delete above)
+# Rate limit: EVAL "<lua>" 1 rl:user:42 100 60   (limit 100 / 60s)
+# Queue:      LMOVE jobs jobs:proc LEFT RIGHT | LREM jobs:proc 1 "$job"
+#             XADD jobs '*' field v | XREADGROUP ... | XACK | XAUTOCLAIM
+
+# Diagnostics (read-only):
+redis-cli INFO memory          # used_memory, maxmemory, evicted_keys
+redis-cli --bigkeys            # find the keys eating your memory
+redis-cli SLOWLOG GET 10       # slowest recent commands
+redis-cli OBJECT FREQ mykey    # access frequency (needs allkeys-lfu)
+redis-cli MEMORY USAGE mykey   # bytes for one key
+redis-cli SCAN 0 MATCH 'sess:*' COUNT 100   # never KEYS in prod
+```
+
+`scripts/verify.sh` scans your project for the high-confidence foot-guns (`KEYS *` in source,
+lock release without a token compare, `INCR` with no `EXPIRE`, `maxmemory` with no policy). It is
+read-only, never connects to a server, and exits 0 when no Redis usage is found.
+
+## Project grounding
+
+Record this project's Redis decisions in `02-DOCS/wiki/stack/redis.md` (recorded, not gated — same
+convention `postgresdb` uses): which primitive(s) you run, the `maxmemory-policy`, persistence
+(RDB/AOF/none), the client library, and any lock/rate-limit Lua you depend on. Future agents read
+this before touching the cache.
+
+## See Also
+
+- [`references/caching.md`](references/caching.md) — read/write-through, write-behind, XFetch math, negative caching, hot/big keys.
+- [`references/locks-and-rate-limiting.md`](references/locks-and-rate-limiting.md) — full Redlock + critique + fencing, watchdog renewal, all four rate-limit algorithms with Lua.
+- [`references/queues.md`](references/queues.md) — full reliable-list + Streams implementations, `XAUTOCLAIM` recovery, DLQ, BullMQ/Sidekiq/RQ/Celery detail, idempotency.
+- Siblings: [`../postgresdb/SKILL.md`](../postgresdb/SKILL.md) · [`../vector-db/SKILL.md`](../vector-db/SKILL.md) · [`../scaling/SKILL.md`](../scaling/SKILL.md) · [`../clickhouse-analytics/SKILL.md`](../clickhouse-analytics/SKILL.md).

package/skills/redis/evals/README.md

@@ -0,0 +1,10 @@
+# redis — evals
+
+`cases.yaml` holds the routing and capability checks for this skill. `should_trigger` are prompts
+that must select `redis` (including the non-obvious lost-EXPIRE race and the `KEYS *` review trigger);
+`should_not_trigger` are near-neighbours that must route to a named sibling (`postgresdb`, `vector-db`,
+`fly-io`, `nextjs`, `clickhouse-analytics`) so the boundary is exercised, not just the centre. The
+`capability` case is a three-bug scenario (stampede + lock + rate limiter) graded against the
+`must_include` rubric. There is no automated runner here — feed each prompt to the skill-router under
+test and confirm the selection, then judge the capability answer against its rubric by hand (or with an
+LLM judge). Keep prompts phrased like a real developer would ask, not as keyword bait.