Diff v1 → v2

- # Skills
+ # Skills — Index
  
- A personal library of reusable engineering techniques, recipes, and "how I do X"
- notes — store once, find later. Each entry leads with **when to use it**.
+ **Routing map for AI agents.** Find the entry whose *"reach for it when"* matches the task in
+ front of you, then fetch that article — append `.md` to any link for the raw markdown source
+ (e.g. `/wiki/push-compute-to-datastore.md`). Every skill leads with when to use it and is dense
+ with copy-paste patterns and "do X not Y because Z" rules.
  
- ## Engineering & code
+ > Keep this index current: whenever a skill article is added, renamed, or re-scoped, update the
+ > matching line here so this stays the single place an agent looks first.
  
- - [Sandi Metz' Rules](/wiki/sandi-metz-rules) — guard-rails that keep objects small,
-   focused, and replaceable (Ruby/Rails; the principles travel).
- - [React: Rules & Project Structure (2026)](/wiki/react-best-practices) — the
-   Sandi-Metz instincts for components, plus the 2026 stack (TanStack, shadcn/Tailwind v4,
-   feature-based structure, useQuery patterns).
- - [Scaling Rails: Vertical & Horizontal](/wiki/scalable-rails) — how and why to scale a
-   Rails app to the next measured bottleneck (Puma/GVL, the database, jobs, caching,
-   Rails 8 stack).
+ ## Databases & backend performance
  
- ## See also
+ **Start at [Push Compute to the Datastore](/wiki/push-compute-to-datastore)** — the hub and
+ decision ladder; the five below are its deep dives.
  
- - [Rails Production Playbook](/wiki/rails-production-playbook) — the broader Rails
-   engineering reference (Engineering category).
+ - [Push Compute to the Datastore](/wiki/push-compute-to-datastore) — **reach for it when**
+   deciding *where computation should live* (app vs Postgres vs Redis), killing an N+1 or an
+   app-side loop, fixing slow `OFFSET` pagination, or adding aggregation / ranking / queues /
+   rate-limiting / caching. The ladder: constraints → indexes → set-based SQL → DB engines →
+   Redis → app code → a specialized store.
+ - [Postgres Full-Text & Fuzzy Search](/wiki/postgres-full-text-search) — **reach for it when**
+   building a search box, autocomplete, typo tolerance, relevance ranking, or hybrid
+   keyword+vector search — or deciding native FTS vs Elasticsearch. Covers tsvector,
+   `websearch_to_tsquery`, `ts_rank_cd`, GIN/GiST/RUM, `pg_trgm`, RRF hybrid search, ParadeDB.
+ - [Postgres Query Planning & EXPLAIN](/wiki/postgres-query-planning) — **reach for it when** a
+   query is slow and you need to know *why*: reading `EXPLAIN (ANALYZE, BUFFERS)`, fixing bad
+   row estimates / extended statistics, `work_mem` spills, the prepared-statement generic-plan
+   trap.
+ - [Postgres Concurrency, MVCC & Throughput](/wiki/postgres-concurrency-and-throughput) —
+   **reach for it when** diagnosing bloat / vacuum, lock waits and deadlocks, "too many
+   connections" / pooling, isolation or race bugs, a slow bulk load (`COPY`/`unnest`), or making
+   a write idempotent.
+ - [Postgres Scale-Out, Replication & Data Movement](/wiki/postgres-scale-out) — **reach for it
+   when** one box isn't enough: read replicas & read-your-writes, Citus sharding, CDC / outbox,
+   partition-detach archival, denormalization, HA / failover.
+ - [Redis Internals & Datastore Selection](/wiki/redis-deep-dive-and-datastore-selection) —
+   **reach for it when** going deeper on Redis (memory/encoding, Cluster, Bloom/Count-Min/Top-K/
+   t-digest) or deciding whether to add a *specialized* store (search engine, ClickHouse/OLAP,
+   Kafka, graph, vector DB) instead of stretching Postgres/Redis.
  
+ ## Deploy & operations
+ 
+ - [Kamal Auto-Versioning](/wiki/kamal-auto-version) — **reach for it when** versioning a
+   Kamal-deployed app: auto-bump semver from Conventional Commits, pre/post-deploy hooks, tag
+   the release on a healthy deploy, embed the version in a Go binary (`svu`, ldflags).
+ - [Rails Production Playbook](/wiki/rails-production-playbook) — **reach for it when** running
+   Rails in production and want boring, explicit, deny-by-default, observable conventions.
+ 
+ ## Language & framework engineering
+ 
+ - [Sandi Metz' Rules](/wiki/sandi-metz-rules) — **reach for it when** you want OO design
+   guard-rails: keep classes/methods small, focused, replaceable (Ruby/Rails; the principles
+   travel).
+ - [React: Rules & Project Structure (2026)](/wiki/react-best-practices) — **reach for it when**
+   starting or structuring a React frontend: the 2026 stack (TanStack, shadcn/Tailwind v4,
+   feature-based layout, query patterns).
+ - [Scaling Rails: Vertical & Horizontal](/wiki/scalable-rails) — **reach for it when** scaling a
+   Rails app to the next *measured* bottleneck (Puma/GVL, the database, jobs, caching).
+ 
+ ## Working with AI agents (methodology)
+ 
+ - [Getting Started with Agentic Engineering](/wiki/getting-started-with-agentic-engineering) —
+   **start here** for how to build software with AI agents on these projects.
+ - [Agentic Engineering](/wiki/agentic-engineering) — the working methodology; **specs are the
+   source of truth, code is a build artifact.**
+ - [The Agentic-Feature Workflow](/wiki/agentic-feature-workflow) — **reach for it when** running
+   a feature through specify → clarify → plan → tasks → implement → verify → retrospective.
+ - [Spec-Driven Workflow](/wiki/spec-driven-workflow) — **reach for it when** you need the plan
+   to be the contract before any code is written.
+ - [Model Routing: Haiku, Sonnet, Opus](/wiki/model-routing-haiku-sonnet-opus) — **reach for it
+   when** deciding which model tier a task should run on.
+ - [Subagents and Context Injection](/wiki/subagents-and-context-injection) — **reach for it
+   when** designing subagent prompts: hand the map down, pre-fetch context, don't let agents
+   rediscover it.
+ - [Trust but Verify](/wiki/trust-but-verify) — **reach for it when** setting up an independent
+   adversarial review gate between implementation and deploy.
+ - [The Compounding Layer](/wiki/the-compounding-layer) — **reach for it when** capturing
+   learnings: feed lessons back as constitution rules + extracted skills.
+ 
+ ## When an agent run goes wrong (failure modes)
+ 
+ - [The Illusion of Speed](/wiki/the-illusion-of-speed) — fast generation, slow discovery/
+   diagnosis/fixing. Fix with decomposition and oversight.
+ - [The One-Shot Problem](/wiki/the-one-shot-problem) — a task too big for one prompt silently
+   drops requirements. Fix by decomposing into one-shottable pieces.
+ - [Losing Control: When the Agent Goes Off-Plan](/wiki/losing-control-when-the-agent-goes-off-plan)
+   — scope creep, hallucination, premature execution. The plan is the contract.
+ 
+ ## Starting a new project
+ 
+ - [New Project — References](/wiki/new-project) — **reach for it when** bootstrapping a new
+   repo: the methodology, skills, and playbooks to pull in and reference.
+