@damiangilgonzalez/harness 1.3.7

package/skills/rag/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: rag
+
+should_trigger:
+  - prompt: "Build Q&A over our internal handbook so the bot only answers from it and adds citations."
+    why: Core RAG ask — grounded answers from a private corpus with citations is exactly the pipeline rag owns.
+  - prompt: "My RAG returns the right document but the answer is still wrong."
+    why: Non-obvious — the store retrieved correctly, so this is a passage/rerank/grounding problem inside the pipeline, not a vector-db issue.
+  - prompt: "The assistant keeps inventing facts that aren't in our docs — how do I ground it so it stops?"
+    why: Grounding + refusal contract; forcing answer-only-from-context and an explicit refusal is rag's job.
+  - prompt: "How do I measure if my retrieval is any good — context recall vs context precision?"
+    why: RAG-specific evaluation metrics; rag carries faithfulness/recall/precision even though the general harness is agent-eval.
+  - prompt: "Add contextual retrieval — prepend an LLM context blurb to each chunk before embedding to cut failed retrievals."
+    why: Anthropic Contextual Retrieval technique lives in the rag pipeline (contextualize stage), not in embeddings-search.
+  - prompt: "Wire a hybrid search plus rerank flow: dense + BM25 fused, then a cross-encoder before generation."
+    why: The retrieve → rerank → generate funnel is the heart of the rag pipeline.
+  - prompt: "El bot s'inventa coses que no surten als nostres documents i vull respostes amb cites."
+    why: Catalan — grounding + citations over a private corpus is the rag pipeline.
+
+should_not_trigger:
+  - prompt: "Set up a Qdrant collection with binary quantization and tune ef_search for recall."
+    route_to: vector-db
+    why: Store operations — collection schema, quantization, HNSW knobs — are the layer under rag, not the pipeline.
+  - prompt: "Which embedding model and chunk size give the best recall for a code corpus?"
+    route_to: embeddings-search
+    why: Embedding-model choice and chunk-size science are the layer beside rag; rag uses a chunker but does not own the experiments.
+  - prompt: "Extract the tables from these scanned invoice PDFs into clean text."
+    route_to: document-processing
+    why: File-to-text / OCR is pre-RAG ingestion; rag assumes text already exists.
+  - prompt: "Build the chat UI with sessions and channel routing for our support bot."
+    route_to: chatbot
+    why: Product surface (sessions, UI, channels) — chatbot calls the rag brain, it is not the retrieval pipeline itself.
+  - prompt: "Pull the buyer name, total, and due date out of this contract into a fixed JSON schema."
+    route_to: structured-extraction
+    why: Schema-constrained field extraction, not a grounded prose Q&A answer.
+
+capability:
+  - scenario: "Design a grounded RAG pipeline over a 500-PDF policy corpus that currently hallucinates and sometimes answers despite the right document being present."
+    must_include:
+      - Names the full pipeline stages retrieve → rerank → ground → cite → refuse.
+      - Specifies hybrid retrieval (dense + BM25) fused with Reciprocal Rank Fusion (RRF).
+      - Uses a reranker (Cohere Rerank 3.5 or a local cross-encoder) with a top-N → top-K funnel (~150 → ~20).
+      - Grounding prompt forces answer-only-from-context, inline citations of chunk ids, and an explicit refusal on insufficient context.
+      - Defines an eval plan with faithfulness plus context recall/precision and a CI threshold gate.
+      - Routes file-to-text ingestion to document-processing and store operations to vector-db.
+      - Mentions contextual retrieval (prepend context before embedding) as a recall lever for the policy corpus.

package/skills/rag/references/evaluation.md

@@ -0,0 +1,99 @@
+# references/evaluation.md — measuring a RAG pipeline
+
+Faithfulness is not correctness, and "it looks good" is not a metric. This file gives the golden
+set, the four RAGAS metrics with plain-English formulas and sensible thresholds, the
+failure → metric → fix mapping, and a CI gate that fails the build below threshold.
+
+Sources: RAGAS docs; Cohorte "Evaluating RAG Systems in 2025"; Confident AI / Maxim "RAG
+Evaluation 2025" (accessed 2026-06-02).
+
+## 1. Build a golden set
+
+A golden set is 30–50 questions with known-good answers and, ideally, the ids of the chunks that
+*should* be retrieved.
+
+- Cover the real query distribution: factual lookups, multi-hop, "not in the corpus" (so you can
+  test the refusal path), and paraphrased duplicates.
+- Include at least a few questions whose answer is **not** in the corpus — a good pipeline must
+  refuse these, and you cannot measure refusal without them.
+- Store as a tiny YAML/JSON: `{question, ground_truth_answer, ground_truth_chunk_ids}`.
+
+```yaml
+- question: "How many vacation days do new employees get?"
+  ground_truth_answer: "15 days in the first year."
+  ground_truth_chunk_ids: ["handbook#42"]
+- question: "What is the company's policy on Mars colonization?"
+  ground_truth_answer: null   # not in corpus — must refuse
+  ground_truth_chunk_ids: []
+```
+
+## 2. The four RAGAS metrics
+
+| Metric | Plain-English formula | What it catches |
+|---|---|---|
+| **faithfulness** | decompose the answer into atomic claims; fraction of claims supported by retrieved context. 1.0 = fully grounded | answer states things not in the sources |
+| **answer relevancy** | how directly the answer addresses the question (low if padded/off-topic) | on-topic-but-evasive answers |
+| **context precision** | are the relevant chunks ranked at the top of what was retrieved | relevant chunks exist but rank below junk |
+| **context recall** | fraction of ground-truth chunks that actually got retrieved | the needed chunk never gets retrieved |
+
+Faithfulness specifically decomposes the answer into atomic claims and checks each against the
+retrieved context; a score of 1.0 means every claim is grounded.
+
+## 3. Failure → metric → fix
+
+| Symptom you observe | Metric that drops | Fix, in order |
+|---|---|---|
+| Confident statements absent from sources | faithfulness | tighten grounding prompt; enforce refusal clause |
+| Answer rambles / dodges the question | answer relevancy | query rewriting; tighter prompt |
+| Right chunk present but buried | context precision | add/strengthen reranker; tune RRF k |
+| Right chunk never retrieved | context recall | fix chunking; add contextual retrieval; go hybrid |
+
+Always read **context recall first** — if it is low, every downstream metric is capped, because
+the model cannot ground an answer on a chunk it never saw.
+
+## 4. Suggested thresholds
+
+Start strict and relax only with evidence:
+
+```text
+faithfulness       >= 0.90   # near-zero tolerance for ungrounded claims
+context recall     >= 0.85   # the right chunk must almost always be retrieved
+context precision  >= 0.70
+answer relevancy   >= 0.80
+```
+
+## 5. CI gate
+
+Score the golden set on every change and fail the build below threshold so regressions cannot
+ship silently.
+
+```python
+# eval_gate.py — run in CI; exit non-zero on regression.
+import sys
+from ragas import evaluate
+from ragas.metrics import faithfulness, answer_relevancy, context_precision, context_recall
+
+THRESHOLDS = {"faithfulness": 0.90, "context_recall": 0.85,
+              "context_precision": 0.70, "answer_relevancy": 0.80}
+
+result = evaluate(dataset,                      # built from your golden set + pipeline outputs
+                  metrics=[faithfulness, answer_relevancy,
+                           context_precision, context_recall])
+scores = result.to_pandas().mean(numeric_only=True).to_dict()
+
+failed = {m: scores[m] for m, t in THRESHOLDS.items() if scores.get(m, 0) < t}
+for m, t in THRESHOLDS.items():
+    print(f"{m}: {scores.get(m, 0):.3f} (gate {t})")
+if failed:
+    print("FAIL:", failed); sys.exit(1)
+print("RAG eval gate passed"); sys.exit(0)
+```
+
+```yaml
+# .github/workflows/rag-eval.yml (excerpt)
+- name: RAG eval gate
+  run: python eval_gate.py
+```
+
+The general-purpose eval harness (arbitrary tasks, non-RAG agents) is the `agent-eval` skill;
+these four metrics and this gate are the RAG-specific part that lives with `rag`.

package/skills/rag/references/pipeline.md

@@ -0,0 +1,151 @@
+# references/pipeline.md — the reference RAG pipeline
+
+This is the long-form companion to the SKILL body: the full contextual-retrieval prompt, the
+hybrid + RRF fusion, the rerank funnel parameters, the complete grounding system prompt, and a
+minimal runnable retrieve → rerank → answer skeleton. Provider-neutral with concrete Cohere /
+Anthropic examples. Adapt names; keep the contracts.
+
+## 1. Contextual retrieval (full)
+
+Anthropic's technique: before embedding and before BM25 indexing, prepend a 1–2 sentence
+LLM-written blurb that situates each chunk inside its document. Reductions in failed retrieval:
+~35% (contextual embeddings), ~49% (+ contextual BM25), ~67% (+ rerank)
+(anthropic.com/news/contextual-retrieval, 2024-09; accessed 2026-06-02).
+
+Cache the whole-document portion of the prompt so you pay for it once per document, not once per
+chunk — this is what makes the technique affordable at scale.
+
+```text
+<document>
+{{WHOLE_DOCUMENT}}
+</document>
+Here is the chunk we want to situate within the whole document:
+<chunk>
+{{CHUNK_TEXT}}
+</chunk>
+Give a short, standalone context (1–2 sentences) that situates this chunk within the overall
+document, to improve search retrieval of the chunk. Answer ONLY with the succinct context and
+nothing else.
+```
+
+```python
+# Generate context per chunk, then index context + chunk for BOTH dense and BM25.
+def contextualize(client, doc_text, chunk_text):
+    msg = client.messages.create(
+        model="claude-sonnet-4-5",
+        max_tokens=120,
+        system=[{"type": "text",
+                 "text": f"<document>\n{doc_text}\n</document>",
+                 "cache_control": {"type": "ephemeral"}}],  # cache the doc
+        messages=[{"role": "user", "content":
+                   f"Here is the chunk:\n<chunk>{chunk_text}</chunk>\n"
+                   "Give a 1-2 sentence standalone context for retrieval. Context only."}],
+    )
+    return msg.content[0].text.strip()
+
+def indexable(doc_text, chunk):
+    ctx = contextualize(client, doc_text, chunk["text"])
+    chunk["context"] = ctx
+    chunk["embed_input"] = f"{ctx}\n{chunk['text']}"   # embed this
+    chunk["bm25_input"]  = f"{ctx} {chunk['text']}"    # index this for keyword
+    return chunk
+```
+
+## 2. Hybrid retrieval + Reciprocal Rank Fusion
+
+Dense search catches paraphrase; BM25 catches exact tokens. Run both and fuse by rank, not by
+raw score (scores from two systems are not comparable). RRF score for a document is the sum over
+result lists of `1 / (k + rank)`, with `k ≈ 60` a standard constant.
+
+```python
+def rrf(*ranked_lists, k=60, top_n=150):
+    scores = {}
+    seen = {}
+    for lst in ranked_lists:                 # each: list of chunks in rank order
+        for rank, chunk in enumerate(lst):
+            cid = chunk["chunk_id"]
+            scores[cid] = scores.get(cid, 0.0) + 1.0 / (k + rank)
+            seen[cid] = chunk
+    fused = sorted(seen.values(), key=lambda c: scores[c["chunk_id"]], reverse=True)
+    return fused[:top_n]
+
+dense = vector_store.search(query_vec, limit=150)   # ../vector-db owns this call
+keyword = bm25.search(query, limit=150)
+candidates = rrf(dense, keyword, top_n=150)
+```
+
+The actual store-side hybrid (named vectors, sparse-dense, server-side fusion in Qdrant/Weaviate/
+Pinecone) belongs to `../vector-db/SKILL.md`. Use that if your store fuses natively; use the RRF
+above when you fuse two independent indexes yourself.
+
+## 3. Rerank funnel
+
+Funnel parameters (Microsoft Cloud Blog 2025-02-04; StackAI, accessed 2026-06-02):
+
+| Param | Value | Why |
+|---|---|---|
+| retrieve top_n | ~150 | wide enough that the right chunk is almost always present |
+| rerank model | Cohere Rerank 3.5 (ctx 4096) or local cross-encoder | cross-encoder scores query+chunk jointly |
+| keep top_k | ~20 | precise enough for the prompt without diluting it |
+
+```python
+import cohere
+co = cohere.ClientV2()
+
+def rerank(query, candidates, top_k=20):
+    res = co.rerank(model="rerank-v3.5", query=query,
+                    documents=[c["text"] for c in candidates], top_n=top_k)
+    return [candidates[r.index] for r in res.results]   # ids preserved by index
+```
+
+Local alternative: load a `bge-reranker`-class cross-encoder and score each `(query, chunk)`
+pair; sort descending; slice top_k. Use it when data cannot leave the network.
+
+## 4. The grounding system prompt (complete)
+
+Three non-negotiable clauses: answer only from context, cite chunk ids, explicit refusal.
+
+```text
+You are a retrieval-grounded assistant. You answer ONLY using information inside the <context>
+block below. Do not use prior knowledge or make assumptions.
+
+Rules:
+1. Every factual claim MUST cite the chunk id it came from, written inline as [chunk_id].
+   You may cite multiple ids for one claim.
+2. If the <context> does not contain enough information to answer the question, reply EXACTLY:
+   "I don't have enough information in the provided sources to answer that."
+   (For Spanish corpora: "No tengo suficiente información en las fuentes para responder.")
+3. Do not fabricate citations. If you cannot cite it, do not state it.
+
+<context>
+{{#each chunks}}[{{chunk_id}}] {{text}}
+{{/each}}
+</context>
+
+Question: {{question}}
+```
+
+## 5. Minimal runnable skeleton
+
+```python
+# retrieve -> rerank -> ground -> answer. Provider-neutral glue; swap clients as needed.
+def answer(query):
+    qv = embed(query)                                  # same model as the corpus
+    dense   = vector_store.search(qv, limit=150)       # ../vector-db
+    keyword = bm25.search(query, limit=150)
+    fused   = rrf(dense, keyword, top_n=150)
+    top     = rerank(query, fused, top_k=20)           # section 3
+
+    context = "\n".join(f"[{c['chunk_id']}] {c['text']}" for c in top)
+    resp = llm.messages.create(
+        model="claude-sonnet-4-5",
+        max_tokens=1024,
+        system=GROUNDING_PROMPT,                        # section 4, refusal clause included
+        messages=[{"role": "user",
+                   "content": f"<context>\n{context}\n</context>\n\nQuestion: {query}"}],
+    )
+    return resp.content[0].text   # contains [chunk_id] citations or the refusal line
+```
+
+Keep `chunk_id` + `source` on every object from chunking through this function so the cited ids
+in the answer map back to real source pages.

package/skills/rag/scripts/verify.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — rag skill gate. Read-only, idempotent, no network.
+#
+# Checks the skill's own checkable artifacts (the grounding prompt-contract + eval rubric),
+# NOT model output:
+#   1. SKILL.md frontmatter keys exactly = {name, description, tags, recommends, origin}.
+#   2. `recommends` is a subset of the KNOWN catalog ids.
+#   3. The grounding section contains the contract markers: answer-only-from-context,
+#      an explicit refusal phrase, and a citation requirement (banlist guard so a grounding
+#      prompt missing refusal fails).
+#   4. references/pipeline.md and references/evaluation.md exist and are non-empty.
+#   5. The four RAGAS metric names all appear in references/evaluation.md.
+#   6. Every code fence in SKILL.md is language-tagged.
+#
+# Resolves the skill dir relative to this script, so it runs from anywhere. If SKILL.md is
+# absent (empty/clean target) it exits 0 with a skip — no false failure.
+
+GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(dirname "$SCRIPT_DIR")"
+SKILL="$SKILL_DIR/SKILL.md"
+PIPELINE="$SKILL_DIR/references/pipeline.md"
+EVALDOC="$SKILL_DIR/references/evaluation.md"
+
+if [ ! -f "$SKILL" ]; then
+  skip "no SKILL.md at $SKILL_DIR — nothing to verify"
+  ok "verify.sh passed (empty target)"
+  exit 0
+fi
+
+# --- 1. frontmatter keys ---
+fm="$(awk 'NR==1 && $0=="---"{f=1;next} f&&$0=="---"{exit} f{print}' "$SKILL")"
+keys="$(printf '%s\n' "$fm" | grep -E '^[a-z_]+:' | sed -E 's/^([a-z_]+):.*/\1/' | sort | tr '\n' ' ' | sed 's/ $//')"
+expected="description name origin recommends tags"
+if [ "$keys" = "$expected" ]; then
+  ok "frontmatter keys exact: $keys"
+else
+  err "frontmatter keys mismatch — got [$keys], want [$expected]"
+fi
+
+# --- 2. recommends subset of KNOWN ids ---
+KNOWN="analyze author-skill building-agents clarify constitution course-storytelling debug deployment design fastapi flutter go harness implement init marketing nextjs parallel plan postgresdb presentations review sdd secure-coding ship specify suggest tasks verify worktrees finance-ops invoicing bookkeeping pricing sales-pipeline lead-gen cold-outreach proposals contracts customer-support client-onboarding retention hiring people-ops inventory logistics-ops procurement meeting-notes sop-builder project-ops seo-geo content-engine social-publisher brand-voice brand-identity newsletter landing-copy ads article-writing case-studies video-shorts podcast market-research competitor-watch press-kit community webinar review-management pitch-deck investor-materials financial-model fundraising unit-economics grants gdpr-privacy terms-conditions compliance data-policy ip-trademark stripe email-connector google-workspace notion-connector whatsapp-telegram automation-flows api-connector-builder webhooks data-scraper spreadsheet-ops calendar-scheduling document-processing e-signature analytics dashboard kpi-framework reporting ab-testing forecasting data-cleaning business-intelligence rag embeddings-search prompt-engineering llm-pipeline agent-eval chatbot ai-media replicate-images structured-extraction agent-safety cost-tracking react react-native vue-nuxt nodejs django laravel rails swift-ios kotlin-android rust api-design wordpress shopify no-code-app chrome-extension mysql redis prisma-orm db-migrations backups clickhouse-analytics code-review security-scan testing-py testing-web testing-go e2e-testing accessibility performance error-handling observability docker github-actions git-workflow domains-dns monitoring email-deliverability scaling knowledge-ops codebase-onboarding research-ops decision-records continuous-learning skill-scout context-budget course-builder technical-writing translation-l10n youtube-api youtube-strategy youtube-ideation youtube-thumbnails youtube-packaging remotion-video tiktok-api instagram-api shortform-strategy shortform-ideation shortform-packaging shortform-editing linkedin-api linkedin-strategy linkedin-content linkedin-carousels linkedin-outreach medium-writing medium-publishing medium-strategy typescript python java csharp-dotnet php ruby cpp elixir bash-scripting sql angular svelte astro solid-js htmx nestjs spring-boot phoenix tauri electron expo compose-multiplatform mongodb supabase neon planetscale sqlite-turso drizzle-orm firebase dynamodb vector-db duckdb vercel netlify cloudflare railway render fly-io coolify hetzner digitalocean aws-essentials gcp-essentials replicate runpod modal huggingface ollama together-fireworks fal"
+rec_line="$(printf '%s\n' "$fm" | grep -E '^recommends:' | sed -E 's/^recommends:[[:space:]]*\[?//; s/\]//')"
+rec_ids="$(printf '%s' "$rec_line" | tr ',' ' ')"
+bad=""
+for id in $rec_ids; do
+  id="$(printf '%s' "$id" | tr -d ' ')"
+  [ -z "$id" ] && continue
+  case " $KNOWN " in *" $id "*) ;; *) bad="$bad $id";; esac
+done
+if [ -z "$bad" ]; then ok "recommends are all known ids"; else err "recommends not in KNOWN:$bad"; fi
+
+# --- 3. grounding contract markers ---
+if grep -qi 'ONLY using' "$SKILL" || grep -qi 'answer ONLY' "$SKILL"; then
+  ok "grounding: answer-only-from-context present"
+else
+  err "grounding: missing answer-only-from-context clause"
+fi
+if grep -qi "don't have enough information" "$SKILL" || grep -qi 'No tengo suficiente' "$SKILL"; then
+  ok "grounding: explicit refusal phrase present"
+else
+  err "grounding: missing explicit refusal phrase (banlist guard)"
+fi
+if grep -qi 'cite' "$SKILL" && grep -q 'chunk_id' "$SKILL"; then
+  ok "grounding: citation requirement present"
+else
+  err "grounding: missing citation requirement"
+fi
+
+# --- 4. references exist and non-empty ---
+for f in "$PIPELINE" "$EVALDOC"; do
+  if [ -s "$f" ]; then ok "reference present: ${f#$SKILL_DIR/}"; else err "missing/empty reference: ${f#$SKILL_DIR/}"; fi
+done
+
+# --- 5. four RAGAS metric names in evaluation.md ---
+if [ -f "$EVALDOC" ]; then
+  for m in "faithfulness" "answer relevancy" "context precision" "context recall"; do
+    if grep -qi "$m" "$EVALDOC"; then ok "metric present: $m"; else err "metric missing in evaluation.md: $m"; fi
+  done
+fi
+
+# --- 6. every code fence in SKILL.md is language-tagged ---
+untagged="$(awk '/^```/{n++; if(n%2==1 && $0=="```") print NR}' "$SKILL")"
+if [ -z "$untagged" ]; then
+  ok "all code fences language-tagged"
+else
+  err "untagged code fence(s) at SKILL.md line(s): $(printf '%s' "$untagged" | tr '\n' ' ')"
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"

package/skills/rails/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: rails
+description: "Use when building or maintaining a Ruby on Rails app — models, controllers, views, routes and migrations; ActiveRecord associations, scopes and query performance; Hotwire (Turbo and Stimulus) UI; Active Job or Solid Queue background work; and Rails tests. Covers N+1 queries, migration safety on live tables, and flaky system tests around Turbo Frames. NOT plain Ruby scripts, gems or CLIs with no Rails loaded (that is `ruby`)."
+tags: [rails, activerecord, hotwire, turbo, stimulus, solid-queue, minitest]
+recommends: [ruby, postgresdb, testing-web, deployment, db-migrations]
+profiles: []
+origin: risco
+---
+
+# Build Rails the omakase way
+
+Write Rails the way a core-adjacent senior would: fat-enough models, skinny
+controllers, zero N+1, strong parameters, migrations that are reversible and safe on a
+live table, and tests that exercise the request rather than the implementation. Lean
+into the Rails 8 "omakase" defaults instead of fighting them — the framework already
+made the boring choices for you.
+
+This is **Rails the framework**: the MVC request cycle, ActiveRecord, Hotwire, Active
+Job, the Rails test stack. The moment code stops loading Rails — a plain script, a gem,
+an `Enumerable` refactor with no `ActiveRecord` in sight — it is no longer this skill.
+That is `ruby` (see `../ruby/SKILL.md`).
+
+## Target versions
+
+```text
+Rails        8.1   (stable line, released 2025-10-22; 8.0 shipped 2024-11-07)
+Ruby         3.4+  (floor for current Rails)
+Jobs/queue   Solid Queue   (default Active Job backend — database-backed, no Redis)
+Cache        Solid Cache   (default cache store — database-backed)
+WebSockets   Solid Cable   (default Action Cable adapter — database-backed)
+Assets       Propshaft     (default; Sprockets is legacy)
+JS           Importmaps    (default; no Node build step required)
+Deploy       Kamal 2 + Thruster
+Front-end    Hotwire = Turbo 8 + Stimulus
+Auth         `rails generate authentication`  (built in; no Devise for basic auth)
+```
+
+A fresh Rails 8 app needs **no Redis and no Node**. Stop reaching for Sidekiq/Redis or
+a JS bundler by reflex — the Solid trifecta and Importmaps already cover the default
+case. Rails 8.1 adds Active Job Continuations (resumable long jobs), Structured Event
+Reporting, local CI via `config/ci.rb`, and Markdown rendering.
+
+## When to use
+
+- Generating/editing anything under `app/` (models, controllers, views, jobs, mailers,
+  channels), `config/routes.rb`, or `db/migrate/`.
+- ActiveRecord work: associations, scopes, validations, callbacks, `includes`/`preload`/
+  `eager_load`, query objects, migrations.
+- Hotwire UI: Turbo Frames/Streams, morphing, Stimulus controllers, broadcasts.
+- Background work via Active Job / Solid Queue; fragment caching via Solid Cache.
+- Rails testing: Minitest model/integration/system tests, fixtures, RSpec + Capybara,
+  debugging flaky Turbo system tests.
+- Upgrading a Rails app or migrating off Redis/Sidekiq onto the Solid stack.
+
+## When NOT to use
+
+- Plain Ruby with no Rails loaded — scripts, gems, CLIs, Bundler packaging → `ruby`.
+- PHP/Laravel → `laravel`. Python/Django → `django`. (Route by the language/framework
+  the file actually uses.)
+- Pure engine-level schema/index/locking depth not expressed as an AR migration →
+  `postgresdb` / `mysql` / `db-migrations`.
+- Host/container/CI provisioning (Kamal host setup, Docker, runners) → `deployment` /
+  `docker` / `github-actions`. This skill writes the Rails-side glue, then hands off.
+
+## The request cycle — where logic lives
+
+Route → controller → model → view. Keep each layer doing one job.
+
+- **Controllers stay skinny.** A controller action finds/builds objects, calls one
+  domain method, and renders/redirects. Why: a controller fat with business rules is
+  untestable except through the full HTTP stack and impossible to reuse.
+- **Domain logic lives on the model.** Validations, scopes, state transitions, and
+  computed attributes belong on the AR class. Why: that is where the data and its
+  invariants already are.
+- **Extract a PORO/service object only when** a method spans 2+ models or does external
+  IO (payment, email, third-party API). Don't pre-extract — a one-model method is just
+  a model method. Why: premature service objects scatter logic that AR would hold fine.
+
+```ruby
+# Good: skinny controller, domain logic on the model.
+class PostsController < ApplicationController
+  def create
+    @post = Current.user.posts.build(post_params)
+    if @post.publish   # model method owns the rule
+      redirect_to @post, notice: "Published"
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def post_params
+    params.expect(post: [:title, :body])   # Rails 8 strong params
+  end
+end
+```
+
+## ActiveRecord
+
+Associations, validations, and scopes are the vocabulary — use them before writing raw
+SQL or manual loops.
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :author, class_name: "User"
+  has_many :comments, dependent: :destroy
+
+  validates :title, presence: true, length: { maximum: 120 }
+  scope :published, -> { where.not(published_at: nil) }
+
+  def publish
+    update(published_at: Time.current)
+  end
+end
+```
+
+**Kill N+1 with eager loading.** The classic footgun is touching an association inside
+a loop, firing one query per row.
+
+```ruby
+# Bad: 1 query for posts + 1 per post for its author (N+1).
+Post.published.each { |p| puts p.author.name }
+
+# Good: 2 queries total — posts, then all authors in one IN(...).
+Post.published.includes(:author).each { |p| puts p.author.name }
+```
+
+Gate it: add the `bullet` gem in development, or mark a hot association
+`strict_loading` so an accidental lazy load raises instead of silently degrading.
+
+**Migrations must be reversible and safe on a live table.** A migration that locks a
+large table blocks every reader and writer for its duration.
+
+```ruby
+# Good: a Postgres index built without an exclusive table lock.
+class AddIndexToPostsOnAuthor < ActiveRecord::Migration[8.1]
+  disable_ddl_transaction!   # required — concurrent index can't run in a txn
+  def change
+    add_index :posts, :author_id, algorithm: :concurrently
+  end
+end
+```
+
+Rules: never `add_column ..., default:` on a huge legacy table without checking your
+Rails/Postgres version handles it without a full rewrite; backfill data in batches with
+`find_each` or `update_all`, not one giant `UPDATE` in the migration; add the
+`strong_migrations` gem so unsafe operations fail in review, not in production.
+
+Deeper AR — query objects, `strict_loading`, counter caches, composite primary keys,
+advisory locks, per-operation safe-migration recipes (add column, rename, backfill in
+batches) — is in `references/activerecord.md`.
+
+## Hotwire
+
+Hotwire is the default front-end: Turbo for navigation/updates, Stimulus for behavior.
+Reach for the lightest tool that does the job.
+
+| Need | Use | Why |
+|------|-----|-----|
+| Faster full-page navigation, no code | Turbo Drive (on by default) | Free; intercepts links/forms |
+| Replace one bounded region after an action | Turbo **Frame** | Scoped DOM swap, no JS |
+| Update several elements / push from server | Turbo **Stream** | Targeted append/replace/remove + broadcasts |
+| Re-render a whole page and keep scroll/focus | **Morphing** (Turbo 8) | Diffs the DOM; kills most custom Stream choreography |
+| Client behavior (toggle, copy, debounce) | Stimulus controller | Sprinkle, not a SPA |
+
+Default to Turbo Drive and morphing; only hand-write a Turbo Stream when you need to
+touch elements that morphing can't infer (e.g. prepend to a list from a broadcast).
+
+```javascript
+// app/javascript/controllers/clipboard_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["source"]
+  static values = { successText: { type: String, default: "Copied!" } }
+
+  copy() {
+    navigator.clipboard.writeText(this.sourceTarget.value)
+  }
+}
+```
+
+Worked Frame/Stream/morph examples, model broadcasting (`broadcasts_to`), Stimulus
+values/targets/outlets, and how to system-test Turbo are in `references/hotwire.md`.
+
+## Background jobs & caching
+
+Use Active Job over **Solid Queue** (the Rails 8 default). Two non-negotiable rules:
+
+- **Jobs take serializable arguments — pass IDs, not records.** Why: a serialized AR
+  object goes stale between enqueue and run; an ID is re-fetched fresh.
+- **Jobs must be idempotent.** Why: retries and at-least-once delivery mean a job can
+  run twice; design so the second run is a no-op.
+
+```ruby
+class CommentNotificationJob < ApplicationJob
+  queue_as :default
+
+  def perform(comment_id)
+    comment = Comment.find_by(id: comment_id)
+    return unless comment   # idempotent: nothing to do if it's gone
+    CommentMailer.posted(comment).deliver_now
+  end
+end
+```
+
+For genuinely long work (large backfills, bulk exports) use **Active Job Continuations**
+(Rails 8.1) so a job can checkpoint and resume instead of restarting from zero. Cache
+expensive view fragments with the `cache` helper backed by Solid Cache:
+
+```erb
+<% cache @post do %>
+  <%= render @post.comments %>
+<% end %>
+```
+
+Do **not** add Sidekiq/Redis to a Rails 8 app unless a real, stated throughput or
+latency requirement justifies the extra moving part. Solid Queue covers the default
+case on the database you already run.
+
+## Testing
+
+Minitest + fixtures is the framework default; parallel execution is on by default.
+RSpec-rails (8.x) is the popular alternative. Pick one and exercise behavior through the
+request, never private methods.
+
+| Test type | Base class | Tests |
+|-----------|-----------|-------|
+| Model / unit | `ActiveSupport::TestCase` | validations, scopes, domain methods |
+| Integration | `ActionDispatch::IntegrationTest` | a request → response, status, redirects |
+| System (browser) | `ApplicationSystemTestCase` | end-to-end UI incl. Turbo/Stimulus |
+| Job | `ActiveJob::TestCase` | enqueue + `perform` behavior |
+
+Fixtures (default) are fast and load once; reach for factories (FactoryBot) only when
+per-test object variation gets unwieldy. **Flaky Turbo system test?** It's almost always
+a timing race: never `sleep`. Use Capybara's auto-waiting matchers (`assert_selector`,
+`assert_text`, `assert_no_selector`) which retry until the DOM settles, and swap the
+default Selenium driver for **Cuprite or Playwright** to cut Turbo-timing flake.
+
+Minitest vs RSpec layout, fixtures gotchas, driver config, parallelization, and
+request-spec / broadcast-testing patterns are in `references/testing.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|--------------|--------------|------------|
+| Business logic in the controller | Untestable except through HTTP; not reusable | Push it onto the model; service object only for cross-model/IO |
+| Callback soup (`after_save` chains for business rules) | Hidden order-dependent side effects, brutal to test | Explicit method called from the action; reserve callbacks for data hygiene |
+| Touching an association in a loop | N+1 — one query per row, silent in dev | `includes`/`preload`/`eager_load`; gate with `bullet`/`strict_loading` |
+| Blocking DDL on a big live table | Locks readers + writers for the whole migration | `disable_ddl_transaction!` + `algorithm: :concurrently`; `strong_migrations` |
+| Passing AR records into jobs | Stale serialized state; fails on retry | Pass IDs, re-`find` inside `perform` |
+| Adding Sidekiq/Redis to a Rails 8 app by reflex | A new daemon + dependency for nothing | Solid Queue is the default; add Sidekiq only for a stated need |
+| Queries or business logic in views | N+1 + logic you can't test | Prepare in controller/model; views only render |
+| Testing private methods | Locks tests to internals; refactors break green tests | Test observable behavior through the request |
+| Hand-rolled `fetch`/JS for live updates | Reinvents what Turbo gives free | Turbo Stream or morphing |
+
+## Verify
+
+Run `scripts/verify.sh` inside a Rails app for a read-only static gate: it runs RuboCop
+(if rubocop-rails is configured) and `bin/rails zeitwerk:check`, and greps for the
+statically-detectable anti-patterns above (Sidekiq/Redis in a default app, `.all.each`
+mass loads, a concurrent `add_index` missing `disable_ddl_transaction!`). It skips any
+check whose tooling is absent and exits non-zero only on a hard violation.