coding-os 0.3.2__py3-none-any.whl

core/skills/realtime-websockets/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: realtime-websockets
+description: Build production realtime servers over WebSockets and Server-Sent Events — connection lifecycle, the heartbeat/ping-pong + idle-timeout contract, automatic reconnection with exponential backoff and resume tokens, backpressure and per-connection send queues, horizontal scale-out via a Redis/NATS pub-sub fan-out, presence tracking, and auth on the upgrade handshake. Use when adding live updates (chat, notifications, collaborative cursors, live dashboards), choosing WebSocket vs SSE vs long-poll, debugging dropped or zombie connections, or scaling a socket server past one node. Boundary vs api-design — api-design owns request/response HTTP contracts (REST/GraphQL, idempotency, RFC 9457 errors) and stops at the protocol-upgrade boundary; this skill owns the persistent bidirectional connection after upgrade. Carries higher-level subscription protocols (e.g. graphql-ws) as transport but defers their payload schema to graphql.
+tier: cross-cutting
+domain: [backend]
+depends_on:
+  - api-design
+  - clean-code
+  - observability
+last_reviewed: "2026-06-14"
+---
+
+# Realtime — WebSockets + Server-Sent Events
+
+A practical guide to running persistent realtime connections in production. Stack-agnostic; concrete patterns reference `ws`/Socket.IO (Node), `websockets`/Starlette (Python), `gorilla/websocket` + `melody` (Go), and Redis/NATS as the fan-out bus.
+
+## When to Use This Skill
+
+- Adding live updates: chat, notifications, presence, collaborative editing, live dashboards, order/status streams.
+- Choosing between WebSocket, Server-Sent Events (SSE), and long-polling.
+- Debugging dropped connections, zombie sockets, or "the client thinks it's connected but messages stop arriving".
+- Implementing reliable reconnection (backoff, resume, missed-message replay).
+- Scaling a socket server beyond one process/node (fan-out across instances).
+- Authenticating and authorizing a connection at the upgrade handshake.
+
+Skip when: the interaction is request/response (use HTTP — that is api-design), or the question is the *schema* of subscription payloads (that is graphql for `graphql-ws`).
+
+## Boundary — Realtime vs api-design vs graphql
+
+| Concern | Owner |
+|---|---|
+| REST/GraphQL request-response contracts, versioning, idempotency keys, RFC 9457 HTTP errors | **api-design** |
+| The persistent connection after upgrade: lifecycle, heartbeat, reconnect, backpressure, fan-out, presence | **realtime-websockets** (this skill) |
+| The schema/shape of messages flowing over a `graphql-ws` subscription | **graphql** |
+
+api-design governs everything up to (and including) the HTTP request that *opens* the socket — the `Upgrade` handshake is an HTTP request and its auth/error semantics follow api-design. Once the connection is established and bidirectional, this skill takes over. Message *payload schemas* belong to whoever owns the domain (graphql for GraphQL subscriptions, or a plain JSON envelope this skill defines).
+
+## Transport Decision — WebSocket vs SSE vs Long-Poll
+
+| Transport | Direction | Reconnect | Use when | Avoid when |
+|---|---|---|---|---|
+| **SSE** (`text/event-stream`) | server → client only | built-in (`Last-Event-ID`, auto-retry) | server-push only: notifications, live feeds, log tails, LLM token streams | the client must also push frequently |
+| **WebSocket** | full duplex | manual (build it) | chat, collaboration, gaming, anything bidirectional and chatty | a one-way feed where SSE's simplicity wins |
+| **Long-poll** | request/response | n/a | last-resort fallback where WS/SSE are blocked by middleboxes | anything modern can do — it is a fallback, not a default |
+
+**Default: SSE for one-way push, WebSocket for true bidirectional.** SSE rides plain HTTP/2, reconnects itself, and passes proxies cleanly — reach for WebSocket only when the client genuinely needs to push. (LLM token streaming → SSE; see llm-patterns.)
+
+## Connection Lifecycle — The State Machine
+
+Every connection moves through `CONNECTING → OPEN → CLOSING → CLOSED`. Production code must handle all four plus the half-open failure mode where the TCP connection is dead but neither side has noticed.
+
+- **On open:** authenticate (see handshake auth), register the connection in the per-node registry, send any buffered/missed messages if a resume token was presented.
+- **On message:** validate the frame shape before dispatch; never `eval`/trust client input.
+- **On close:** deregister from the registry AND the pub-sub bus, flush presence, cancel timers. A leaked registry entry is a memory leak that compounds per reconnect.
+- **On error:** treat as close — clean up identically. Do not assume `error` fires before `close`.
+
+## Heartbeat — The Zombie-Connection Cure
+
+TCP can silently die (laptop sleeps, NAT drops the mapping) leaving a socket that is `OPEN` on both sides but transports nothing. The cure is an application-level heartbeat, not reliance on TCP keepalive (whose default ~2h timeout is useless).
+
+```js
+// Server: ping every 30s; terminate a socket that missed the prior pong.
+const HEARTBEAT_MS = 30_000;
+function heartbeat(ws) { ws.isAlive = true; }
+const timer = setInterval(() => {
+  for (const ws of wss.clients) {
+    if (ws.isAlive === false) { ws.terminate(); continue; } // missed last pong → zombie
+    ws.isAlive = false;
+    ws.ping();
+  }
+}, HEARTBEAT_MS);
+wss.on("connection", (ws) => { ws.isAlive = true; ws.on("pong", () => heartbeat(ws)); });
+```
+
+**Rules:** ping interval < proxy idle timeout (most LBs/NGINX default 60s — ping at ~30s). A missed pong on the *next* cycle means terminate, not "wait one more". SSE uses a periodic comment line (`: keepalive\n\n`) for the same purpose.
+
+## Reconnection — Client Backoff + Server Resume
+
+Networks drop. The client must reconnect; the server must let it resume without losing or duplicating messages.
+
+- **Exponential backoff with jitter** on the client: `min(cap, base * 2^attempt) ± rand`. Never reconnect in a tight loop — a server restart with 10k clients all retrying at 1s is a self-inflicted DoS (thundering herd).
+- **Resume token / sequence number:** the server tags each message with a monotonic seq; the client sends its last-seen seq on reconnect; the server replays the gap from a short-lived per-connection buffer (or a Redis stream). SSE gives this for free via `Last-Event-ID`.
+- **Idempotent message handling on the client** — at-least-once replay means a message can arrive twice; dedupe by seq/id.
+
+## Backpressure — A Slow Client Must Not OOM the Server
+
+A fast producer + a slow consumer fills the kernel send buffer; unbounded server-side queuing then exhausts memory. This is the realtime equivalent of an unbounded list endpoint.
+
+- **Check the socket's buffered-amount before each send.** Past a threshold (e.g. `ws.bufferedAmount > 1MB`), drop the slowest-tolerable messages (coalesce presence/cursor updates) or disconnect the client with a `1013 Try Again Later`.
+- **Bounded per-connection queue**, newest-wins for ephemeral state (cursor position), oldest-preserved for events that must not be lost (chat). Pick the policy per message class; never an unbounded queue.
+- **Coalesce high-frequency updates** (typing indicators, cursor moves) to a max rate (e.g. 20/s) server-side before they hit the wire.
+
+## Scaling Out — Fan-Out Across Nodes
+
+A WebSocket is stateful: the connection lives on exactly one node. With N nodes behind a load balancer, a message published on node A must reach a subscriber connected to node B. A pub-sub bus is the standard fix.
+
+```
+client ──┐                       ┌── node A ──┐
+         ├─ load balancer ───────┤            ├─ Redis Pub/Sub ─┐
+client ──┘   (sticky sessions)   └── node B ──┘   (or NATS)     │
+                                       ▲                         │
+                                       └──── fan-out ────────────┘
+```
+
+- **Each node subscribes to the bus**; a publish on any node fans out to every node, which forwards to its locally-connected subscribers. Redis Pub/Sub, NATS, or a Kafka topic are all valid — Redis is the common default.
+- **Sticky sessions (or a connection registry)** so reconnects and request-affinity land predictably; the bus removes the *hard* requirement for stickiness but it still simplifies presence.
+- **Presence at scale** lives in a shared store (Redis set/hash with TTL refreshed by the heartbeat), not in per-node memory — otherwise "who is online" is wrong the moment there is more than one node.
+
+## Auth on the Handshake
+
+The `Upgrade` request is a normal HTTP request — authenticate it there, following api-design's auth rules, before the socket opens.
+
+- **Authenticate at upgrade, not after.** Reject with a `401` during the handshake; never accept the socket and then check. A common pattern: short-lived ticket — client gets a one-time token from an authed REST endpoint, presents it on the WS connect, server validates and burns it.
+- **Browsers cannot set custom headers on a WebSocket** — pass the token via the ticket pattern, a `Sec-WebSocket-Protocol` subprotocol value, or a cookie (with CSRF protection); avoid putting long-lived secrets in the URL query string (they leak into access logs).
+- **Re-authorize per message for sensitive actions** — connection-time auth proves identity once; a long-lived socket still needs per-action authorization, exactly as a long-lived session does.
+- **Origin check** the handshake to blunt cross-site WebSocket hijacking; WS does not honor the same-origin policy by default.
+
+## Observability for Realtime
+
+Connection-oriented metrics differ from request metrics — instrument the *fleet of connections*:
+
+- **Gauges:** concurrent connections, connections per node, presence-set size.
+- **Counters:** connects, disconnects (tagged by close code), messages in/out, dropped-for-backpressure.
+- **Histograms:** connection lifetime, message fan-out latency (publish → delivered).
+- **Alert** on a disconnect spike (mass reconnect storm), a climbing per-connection buffer (backpressure), and pub-sub lag. Per-user data goes on logs/traces, never as a metric label (cardinality — see observability).
+
+## Anti-Patterns (reject in review)
+
+1. **No application heartbeat** — zombie half-open connections accumulate; the server thinks thousands are live.
+2. **Relying on TCP keepalive** for liveness — its multi-hour default never fires in time.
+3. **Reconnect with no backoff/jitter** — thundering-herd DoS on every server restart.
+4. **Unbounded per-connection send queue** — one slow client OOMs the node.
+5. **Per-node in-memory presence with >1 node** — "online users" is wrong the instant the fleet scales.
+6. **Auth checked after the socket opens** instead of on the upgrade handshake.
+7. **Secret token in the WS URL query string** — leaks into access logs and proxies.
+8. **WebSocket for a one-way feed** where SSE would auto-reconnect and pass proxies for free.
+9. **Forgetting to deregister on close** — registry/pub-sub leak that grows per reconnect.
+
+## Pairs With
+
+- **api-design** — owns the HTTP handshake's auth/error contract and the request/response side of the API.
+- **graphql** — defines the payload schema for `graphql-ws` subscriptions this transport carries.
+- **observability** — connection-fleet gauges, disconnect/backpressure alerts.
+- **llm-patterns** — SSE is the canonical transport for streaming LLM tokens.
+
+## Source Material
+
+- RFC 6455 — The WebSocket Protocol (handshake, close codes, framing).
+- WHATWG HTML — Server-Sent Events (`EventSource`, `Last-Event-ID`, auto-retry).
+- `graphql-ws` protocol — the modern GraphQL-over-WebSocket subprotocol.
+- Redis Pub/Sub + Redis Streams docs — fan-out and replay buffers.
+- "Scaling WebSockets" (Ably / PubNub engineering write-ups) — fleet-level patterns.

core/skills/redis/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: redis
+tier: architecture
+domain: [backend, data, infra]
+description: Use Redis correctly as a cache, queue, rate limiter, and ephemeral store — pick the right data structure, caching pattern, eviction policy, and atomicity model. Use when adding caching, designing a key schema, choosing cache-aside vs write-through, setting TTLs/eviction, building a rate limiter or queue, debugging low hit-rate or evictions, or deciding Redis-vs-Postgres for a use case. Triggers — "cache", "Redis", "rate limit", "session store", "pub/sub", "cache invalidation", "TTL", "hit rate". Pairs with db-design (durable store — Redis is ephemeral), sql-authoring (the source of truth behind the cache), performance (cache as a latency lever).
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+---
+
+# Redis
+
+Redis is fast because it's in-memory and ephemeral — treat it as a cache/derived store, never the source of truth. The craft is choosing the data structure that makes the operation O(1), the caching pattern that stays consistent with the database, and the eviction policy that fails gracefully when memory fills.
+
+> Summarize a verbose `redis-cli INFO` into health + flags:
+> `redis-cli INFO | python3 scripts/analyze_info.py`
+
+## Pick the structure that fits the access
+
+| Need | Structure | Why |
+|---|---|---|
+| cache one value / counter | String (`GET/SET`, `INCR`) | atomic counter for free |
+| object with fields | Hash (`HSET/HGET`) | update one field without re-serializing |
+| queue / recent list | List (`LPUSH/RPOP`) | O(1) ends; `BRPOP` blocks for a worker |
+| unique membership | Set (`SADD/SISMEMBER`) | dedupe, set algebra |
+| leaderboard / time-ordered | Sorted Set (`ZADD/ZRANGE`) | score-ordered, O(log n) rank |
+| event log / fan-out | Stream (`XADD/XREAD`) | durable, consumer groups |
+
+Using a String + JSON where a Hash fits means re-reading and re-writing the whole blob to change one field. Match the structure to the operation.
+
+## Cache-aside — the default pattern
+
+```python
+def get_user(uid):
+    key = f"user:{uid}"                 # namespace:entity:id
+    cached = r.get(key)
+    if cached is not None:
+        return json.loads(cached)       # hit
+    user = db.fetch_user(uid)           # miss → source of truth
+    r.set(key, json.dumps(user), ex=300)  # populate with a TTL — ALWAYS a TTL
+    return user
+```
+
+```python
+# Wrong — no TTL: stale forever, and the key never reclaims memory
+r.set(key, value)
+
+# Correct — every cache key has an expiry; staleness is bounded
+r.set(key, value, ex=300)
+```
+
+On write, **invalidate** (`r.delete(key)`) rather than update the cache — let the
+next read repopulate, so the cache can't drift from the DB. Patterns + write-through
+trade-offs → [references/patterns.md](references/patterns.md).
+
+## Atomicity — don't read-modify-write across round trips
+
+```python
+# Wrong — race: two clients read 5, both write 6; one increment lost
+n = int(r.get("count")); r.set("count", n + 1)
+
+# Correct — server-side atomic
+r.incr("count")
+```
+
+For multi-key atomic logic use a Lua script (`EVAL`) or `MULTI/EXEC` — they run
+without interleaving. A rate limiter is `INCR` + `EXPIRE` in one Lua script so the
+window can't leak. `WATCH` gives optimistic locking when you must read-then-write.
+
+## Eviction — decide what happens when memory fills
+
+```
+maxmemory 2gb
+maxmemory-policy allkeys-lru      # cache: evict least-recently-used
+# vs
+maxmemory-policy noeviction       # source-of-truth data: reject writes (never silently drop)
+```
+
+A cache with `noeviction` (the default) stops accepting writes when full —
+surprising outage. A cache should use `allkeys-lru`/`allkeys-lfu`. Data you can't
+lose shouldn't be in Redis-as-only-store at all. Operations → [references/operations.md](references/operations.md).
+
+## When NOT to use Redis
+
+- As the **only** store for data you can't lose — it's memory-first; durability (AOF/RDB) is best-effort, not ACID.
+- For relational queries / joins / ad-hoc filters → that's [Postgres](../db-design/SKILL.md).
+- For values that don't expire and grow unbounded → you'll OOM. Everything ephemeral gets a TTL.
+- As a message bus needing delivery guarantees → Streams help, but Kafka/SQS may fit better.
+
+## Anti-patterns (reject on sight)
+
+- `KEYS *` in production → O(n) blocking scan; use `SCAN` (cursor, non-blocking).
+- A cache key with no TTL → memory leak + unbounded staleness.
+- Read-modify-write across round trips → race; use `INCR`/Lua/`MULTI`.
+- `maxmemory-policy noeviction` on a pure cache → write outage when full.
+- One giant Hash/Set holding millions of fields ("big key") → blocks on access/expire; shard it.
+- Caching the DB write path (write-through) without invalidation discipline → drift.
+
+## See also
+
+- [references/patterns.md](references/patterns.md) — cache-aside vs write-through, invalidation, rate limiter, locks, queues.
+- [references/operations.md](references/operations.md) — persistence (RDB/AOF), eviction, big-key detection, INFO metrics.
+- [assets/redis-checklist.md](assets/redis-checklist.md) — the ship gate.
+- [db-design](../db-design/SKILL.md) · [performance](../performance/SKILL.md) · [sql-authoring](../sql-authoring/SKILL.md).

core/skills/redis/assets/redis-checklist.md

@@ -0,0 +1,27 @@
+<!-- domain:DB | layer:asset | ssot:false | updated:2026-06-04 -->
+# Redis Review Checklist
+
+Run before shipping anything that touches Redis.
+
+## Correctness
+- [ ] Redis is a cache/ephemeral store, not the only home of must-keep data.
+- [ ] Every cache key has a TTL (`ex=`/`EXPIRE`) — no immortal keys.
+- [ ] Writes invalidate (delete) the cache key, not update it (cache-aside).
+- [ ] Read-modify-write done atomically (`INCR`/Lua/`MULTI`), never across round trips.
+- [ ] Data structure matches the access pattern (Hash for fields, Sorted Set for ranking, …).
+
+## Operations
+- [ ] `maxmemory` set + `maxmemory-policy allkeys-lru`/`lfu` for a cache (not `noeviction`).
+- [ ] No `KEYS *` in app/prod paths — `SCAN` only.
+- [ ] No unbounded big keys; sharded where they'd grow.
+- [ ] Connection pool reused (not a new connection per request).
+- [ ] Persistence mode matches the durability requirement (cache: none/RDB ok).
+
+## Resilience
+- [ ] Stampede protection on hot keys (jittered TTL / lock-on-miss).
+- [ ] Rate limiter / lock uses atomic Lua + a TTL (no deadlock on crash).
+- [ ] App degrades gracefully if Redis is down (fall back to DB, don't 500).
+
+## Verify
+- [ ] `redis-cli INFO | python3 scripts/analyze_info.py` → no flags (hit rate, evictions).
+- [ ] `make skills-check-versions` — Redis version pin current.

core/skills/redis/references/operations.md

@@ -0,0 +1,66 @@
+<!-- domain:DB | layer:reference | ssot:true | updated:2026-06-04 -->
+# Redis Operations — Persistence, Eviction, Big Keys, Metrics
+
+> P: Run Redis safely — what persistence guarantees you have, how memory is reclaimed, and which metrics matter.
+> R: Configuring a Redis instance or debugging memory/latency.
+> S: Application-side patterns — see [patterns.md](patterns.md).
+> N: [SKILL.md](../SKILL.md), [operations.md](operations.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Persistence — know your guarantee
+
+| Mode | Guarantee | Cost |
+|---|---|---|
+| none (default cache) | data lost on restart | fastest |
+| RDB snapshot | point-in-time, lose since last snapshot | periodic fork |
+| AOF (append-only) | every write (or every second) | larger file, replay on start |
+| RDB + AOF | best durability | both costs |
+
+Even AOF `appendfsync everysec` can lose ~1s of writes — Redis is **not** ACID.
+If losing data is unacceptable, the source of truth is Postgres; Redis caches it.
+
+## Eviction policies
+
+| Policy | Behaviour | Use for |
+|---|---|---|
+| `noeviction` (default) | reject writes when full | data you must not drop (but then why Redis-only?) |
+| `allkeys-lru` | evict least-recently-used | general cache |
+| `allkeys-lfu` | evict least-frequently-used | cache with hot/cold skew |
+| `volatile-lru` | LRU among keys with a TTL only | mixed cache + persistent keys |
+
+Set `maxmemory` explicitly — without it Redis grows until the OS OOM-kills it. A
+cache wants `allkeys-lru` + a `maxmemory` ceiling.
+
+## Big keys — the silent latency source
+
+A single key holding millions of elements blocks the event loop on access,
+expire, and migration (Redis is single-threaded for commands). Find them:
+
+```bash
+redis-cli --bigkeys                  # sampled scan, safe in production
+redis-cli --memkeys                  # by memory
+```
+
+Shard a big Hash/Set across many keys (`user:{id}:sessions` per user, not one
+global `sessions` set). Never `KEYS *` to find them — `SCAN` (cursor) or the
+sampled `--bigkeys`.
+
+## Metrics that matter (from INFO)
+
+| Metric | Healthy | Bad signal |
+|---|---|---|
+| `keyspace_hits` / `(hits+misses)` | > 0.8 | low → cache too small / wrong keys |
+| `evicted_keys` | ~0 for a sized cache | rising → undersized or wrong policy |
+| `used_memory` vs `maxmemory` | headroom | at ceiling → evictions or write rejects |
+| `connected_clients` | stable | climbing → connection leak (pool not reused) |
+| `instantaneous_ops_per_sec` | baseline | spikes → stampede / hot key |
+
+`scripts/analyze_info.py` parses `redis-cli INFO` and surfaces exactly these +
+flags (low hit rate, evictions under `noeviction`) — one summary, not the full dump.
+
+## Connection pooling
+
+Open a pool once and reuse it; a new TCP connection per request exhausts
+`connected_clients` and adds handshake latency. Every client library has a pool —
+configure max size to match your worker concurrency, not higher.

core/skills/redis/references/patterns.md

@@ -0,0 +1,62 @@
+<!-- domain:DB | layer:reference | ssot:true | updated:2026-06-04 -->
+# Redis Patterns — Caching, Rate Limiting, Locks, Queues
+
+> P: The concrete recipes for the jobs Redis is actually used for, each with its consistency caveat.
+> R: Adding caching, a rate limiter, a lock, or a queue on Redis.
+> S: Choosing the durable store behind the cache — that's [db-design](../../db-design/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [operations.md](operations.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Cache-aside vs write-through
+
+| | Cache-aside (default) | Write-through |
+|---|---|---|
+| read | check cache → miss → DB → populate | always from cache |
+| write | write DB, **delete** cache key | write cache + DB together |
+| consistency | self-healing (next read repopulates) | tighter, but cache write can fail mid-way |
+| use when | most reads, tolerate brief staleness | read-heavy, must serve from cache |
+
+Default to cache-aside with **delete-on-write** (not update-on-write): deleting
+lets the next read pull fresh from the DB, so the cache can't hold a value the DB
+never had. Updating the cache directly risks writing a value that races the DB.
+
+## Stampede protection
+
+When a hot key expires, every request misses at once and hammers the DB. Cures:
+- **Jittered TTL** — `ex = base + random(0, spread)` so keys don't expire together.
+- **Lock-on-miss** — first misser takes a short `SET NX` lock, recomputes, others
+  briefly serve stale or wait.
+- **Early recompute** — refresh at 90% of TTL in the background.
+
+## Rate limiter (fixed window, atomic)
+
+```lua
+-- EVAL with KEYS[1]=bucket, ARGV[1]=limit, ARGV[2]=window_seconds
+local n = redis.call('INCR', KEYS[1])
+if n == 1 then redis.call('EXPIRE', KEYS[1], ARGV[2]) end
+return n <= tonumber(ARGV[1]) and 1 or 0
+```
+
+`INCR` + `EXPIRE` in one Lua script is atomic — a separate `INCR` then `EXPIRE`
+leaks a window if the client dies between them. Sliding-window needs a Sorted Set
+of timestamps (`ZADD` + `ZREMRANGEBYSCORE`).
+
+## Distributed lock (use with care)
+
+```
+SET lock:resource <token> NX EX 10        # acquire: only if absent, auto-expire
+# release: Lua compare-and-delete so you only free YOUR lock
+```
+
+Always `NX` + a TTL (never a lock without expiry → deadlock on crash) and a unique
+token released via a compare-and-delete Lua script. For correctness-critical locks
+across nodes, Redlock or a real coordinator (etcd/Zookeeper) — a single-instance
+lock is best-effort.
+
+## Queue / worker
+
+`LPUSH` to enqueue, `BRPOP` (blocking) in the worker. For at-least-once delivery
+and consumer groups use **Streams** (`XADD` / `XREADGROUP` / `XACK`) — a plain
+List drops the job if the worker crashes mid-process. Match the durability to the
+cost of a lost job.

core/skills/redis/scripts/analyze_info.py

@@ -0,0 +1,101 @@
+"""Summarize `redis-cli INFO` output into health metrics + flags.
+
+PURPOSE:      Collapse a 200-line INFO dump into the few numbers that matter
+              (hit rate, memory, evictions, eviction policy) and flag problems,
+              so the agent reads a summary instead of scrolling INFO.
+INPUT:        `redis-cli INFO` text on stdin, or --file <path>.
+              [--min-hit-rate R] flag below this (default 0.80). [--json]
+OUTPUT:       Metrics + flags on stderr; result on stdout ("clean"/"N finding(s)").
+              Exit 0 clean, 1 if findings, 2 usage.
+DEPENDENCIES: stdlib only. Offline — you pipe INFO in.
+NOTES:        Pure parse/analyze layer is unit-testable without a server.
+              Spec: docs/playbooks/skill-authoring.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def parse_info(text: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        fields[key.strip()] = value.strip()
+    return fields
+
+
+def _hit_rate(fields: dict[str, str]) -> float | None:
+    try:
+        hits = int(fields["keyspace_hits"])
+        misses = int(fields["keyspace_misses"])
+    except (KeyError, ValueError):
+        return None
+    total = hits + misses
+    return hits / total if total else None
+
+
+def analyze(fields: dict[str, str], min_hit_rate: float) -> tuple[dict, list[str]]:
+    metrics: dict[str, object] = {
+        "used_memory_human": fields.get("used_memory_human", "?"),
+        "maxmemory_policy": fields.get("maxmemory_policy", "?"),
+        "evicted_keys": int(fields.get("evicted_keys", 0) or 0),
+        "connected_clients": fields.get("connected_clients", "?"),
+        "hit_rate": _hit_rate(fields),
+    }
+    flags: list[str] = []
+
+    hr = metrics["hit_rate"]
+    if hr is not None and hr < min_hit_rate:
+        flags.append(
+            f"low hit rate {hr:.0%} (<{min_hit_rate:.0%}) — cache too small, "
+            "wrong TTLs, or caching the wrong keys"
+        )
+    if metrics["evicted_keys"] and metrics["maxmemory_policy"] == "noeviction":
+        flags.append(
+            "evictions with noeviction policy — writes are being rejected; "
+            "set allkeys-lru for a cache"
+        )
+    if metrics["maxmemory_policy"] == "noeviction" and fields.get("maxmemory", "0") not in (
+        "0",
+        "",
+    ):
+        flags.append(
+            "maxmemory set with noeviction — Redis rejects writes when full "
+            "(outage); use allkeys-lru/lfu for a cache"
+        )
+    return metrics, flags
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--file", default=None)
+    parser.add_argument("--min-hit-rate", default=0.80, type=float)
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    raw = Path(args.file).read_text(encoding="utf-8") if args.file else sys.stdin.read()
+    if not raw.strip():
+        print("error: no INFO text on stdin (or --file)", file=sys.stderr)
+        return 2
+
+    metrics, flags = analyze(parse_info(raw), args.min_hit_rate)
+    for k, v in metrics.items():
+        print(f"  {k}: {v}", file=sys.stderr)
+    for f in flags:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"metrics": metrics, "flags": flags, "count": len(flags)}))
+    else:
+        print("clean" if not flags else f"{len(flags)} finding(s)")
+    return 1 if flags else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

core/skills/redis/versions.json

@@ -0,0 +1,9 @@
+{
+  "redis": {
+    "ecosystem": "github",
+    "package": "redis/redis",
+    "version": "8.8.0",
+    "source": "https://github.com/redis/redis/releases",
+    "checked": "2026-06-05"
+  }
+}

core/skills/search/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: search
+tier: exploration
+domain: [universal]
+description: 'Use for ANY search, find, replace, or rename operation across a codebase — text literals, code symbols, semantic concepts, docs, or tasks. INVOKE BEFORE grep, before rename, before "find all X", before any cross-cutting edit. Enforces ground-truth counting before edits so nothing gets missed. Triggers — "find all", "rename X to Y", "replace everywhere", "where is X used", "update all references", "search for", "grep for", "change X to Y in all files", refactor, rename, cross-cutting edits.'
+last_reviewed: "2026-05-11"
+
+---
+
+# search
+
+Purpose: Route every search task to the correct layer, establish a ground-truth count before any edit, and verify zero remaining matches after. Prevents: agent edits some matches, declares done, but 20+ remain.
+
+Read when: Anything involving finding or replacing something — in files, code, memory, docs, tasks.
+
+Skip when: You already have the exact file:line from a search earlier in this session and are doing a single-file targeted edit.
+
+## Step 0 — Decision Gate
+
+| Target | Layer | Tools |
+|---|---|---|
+| Literal text / string in files | **File** | `grep -rnF` → see `references/grep.md` |
+| Code symbol — function, class, import, MCP tool | **Graph** | → use `graph-explorer` skill |
+| Semantic concept / "how did we solve X" | **Memory** | `cos_search` |
+| Spec / doc by meaning | **Docs** | `cos_doc_search` |
+| Task / ticket by topic | **Tasks** | `cos_task_search` |
+
+**Composition:** For a symbol rename, run Graph first (graph-explorer gives you call-sites + doc refs), then File verify to catch comments and unindexed strings. Never rely on a single layer for cross-cutting renames.
+
+## Step 1 — INVENTORY (mandatory before any edit)
+
+```bash
+# Get ground truth count — this number must reach 0 after editing
+grep -rnF "OLD_STRING" . $EXCL | wc -l   # N = ground truth
+
+# List affected files
+grep -rlF "OLD_STRING" . $EXCL
+```
+
+N is your contract. You are not done until the same command returns 0.
+
+**Never edit before knowing N.** This is the root cause of the "declared done but 20 remain" failure.
+
+## Step 2 — VARIANT SCAN
+
+Run a multi-variant search before editing. Same string appears in multiple forms.
+
+```bash
+grep -rnF -e "MyClass" -e "my_class" -e "MY_CLASS" -e '"MyClass"' . $EXCL
+```
+
+→ Full variant families and flag reference: `references/grep.md`
+
+## Step 3 — EDIT
+
+For small counts (< 10 files): use `Edit` per file.
+For bulk: use `grep -rlZF ... | xargs -0 sed ...` or Python replace.
+
+→ Replace options with NUL-safe pipelines: `references/grep.md`
+
+**Skip generated / lock / migration files** — note them, regenerate via `make` instead.
+
+## Step 4 — VERIFY (no exceptions)
+
+```bash
+# Must return 0 lines — if not, return to Step 2
+grep -rnF "OLD_STRING" . $EXCL
+
+# Confirm replacement landed
+grep -rnF "NEW_STRING" . $EXCL | wc -l
+
+git diff --stat
+```
+
+## Existing hook coverage
+
+`verify-rename-callers.sh` fires automatically on every `Edit` and warns if the old identifier still appears in other files. Coverage: identifier-shaped strings ≥ 4 chars only. **This hook is a safety net — it does not replace the ground-truth protocol above**, which covers non-identifier strings, YAML, docs, and bulk bash operations.
+
+## Required report (end of every search/replace task)
+
+```
+Pattern(s): <what was searched>
+Variants checked: <all forms>
+Ground truth count: N
+Files changed: X | Files skipped: Y (reason)
+Matches remaining: 0  (verify grep: empty ✓)
+Layers used: File / Graph / Memory / Docs / Tasks
+Risks: <public API, DB migration, generated files, etc.>
+```
+
+"Done" without this report is not done.