rsc-universal 0.1.1

package/skills/rag/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: rag
+description: "Use when building grounded Q&A over your own documents — handbook, support tickets, PDFs, policies — and the answers must come only from the corpus with citations; when retrieval surfaces the right document but the answer is still wrong; when the model invents facts that are not in the sources; when you need to measure whether retrieval is any good; when the right document is found but the wrong passage is used. Triggers: 'build a bot that answers from our docs with citations', 'my RAG returns the right document but the answer is wrong', 'how do I stop the model hallucinating facts not in the corpus', 'context recall vs context precision', 'add contextual retrieval / prepend chunk context before embedding', 'hybrid search plus rerank pipeline', 'respuestas con citas sobre nuestros documentos', 'el bot s'inventa coses que no surten als documents'. NOT operating the vector store itself — collection schema, HNSW ef_search, quantization (that is vector-db)."
+tags: [rag, retrieval-augmented-generation, chunking, hybrid-search, reranking, grounding, citations, faithfulness, contextual-retrieval]
+recommends: [vector-db, embeddings-search, document-processing, chatbot, agent-eval]
+origin: risco
+---
+
+# rag — own the retrieve → rerank → ground → cite → refuse pipeline
+
+You own the **pipeline** that turns a corpus plus a question into a grounded, cited answer.
+You do **not** own the store underneath it (`../vector-db/SKILL.md`) nor the embedding and
+chunk-sizing science beside it (`embeddings-search`). Your job is the glue: chunk, optionally
+contextualize, index, retrieve hybrid, rerank, assemble a grounded prompt, cite the sources,
+and **refuse** when the context does not contain the answer.
+
+You are judged by **retrieval quality and answer faithfulness**, not by raw vector math. If you
+find yourself tuning HNSW parameters, you wandered into `vector-db`. If you are comparing
+embedding models or chunk sizes, that is `embeddings-search`.
+
+## The pipeline, and where each stage hands off
+
+Each stage is a real branch — most failures live in one specific stage, and several stages
+delegate to a sibling skill rather than living here.
+
+| Stage | What you do | Hands off to |
+|---|---|---|
+| Ingest | Get clean text out of PDFs/DOCX/HTML/OCR | `../document-processing/SKILL.md` |
+| Chunk | Heading/semantic-aware splits with overlap, stable ids | chunk-size science → `embeddings-search` |
+| Contextualize | Prepend an LLM-written context blurb per chunk (optional) | stays here |
+| Index | Embed + write dense vectors and a BM25/keyword index | the store → `../vector-db/SKILL.md` |
+| Retrieve | Hybrid dense + BM25, fuse with RRF, top ~150 | hybrid query mechanics → `../vector-db/SKILL.md` |
+| Rerank | Cross-encoder over the 150, keep top ~20 | stays here |
+| Ground + cite | System prompt: answer only from context, cite chunk ids | stays here |
+| Refuse | Output "I don't have enough information" on weak context | stays here |
+| Evaluate | Faithfulness, answer relevancy, context precision/recall | general harness → `agent-eval` |
+
+Surfacing this answer inside a chat product (sessions, channels, UI) is `../chatbot/SKILL.md`;
+pulling schema-constrained fields out of text is `structured-extraction`. `rag` is the
+retrieval brain those products call.
+
+## Retrieval is the bottleneck — measure recall before touching the prompt
+
+Naive RAG pipelines fail at the **retrieval** step in up to ~40% of cases *even when the correct
+document is in the corpus* (StackAI / Lushbinary, 2026-06-02). Why this matters: if the right
+passage never reaches the model, no prompt wording can save the answer. So your first move on a
+broken pipeline is never the prompt — it is measuring whether retrieval delivered the goods.
+
+```text
+Bad   → "answers are wrong, let me lower temperature and reword the system prompt."
+Good  → measure context recall on a golden set; if the right chunk isn't in the top-K,
+         fix chunking + hybrid + rerank first. Only then touch grounding.
+```
+
+Order of attack when answers are wrong: **context recall → context precision → grounding prompt
+→ generation params**. The last item almost never moves the needle.
+
+## Chunking — the highest-leverage single fix
+
+Chunk on structure, not on a blind character count. Why: too-small loses the context a passage
+needs to be interpretable; too-large dilutes the embedding so the relevant sentence gets averaged
+away (StackAI; EdenAI 2025, accessed 2026-06-02).
+
+- Split on headings/sections first, then sub-split long sections to a target window.
+- Keep **overlap** (~10–20% of the window) so a fact spanning a boundary survives in one chunk.
+- Attach a **stable `chunk_id` and `source`** at creation — you will need them end to end for
+  citations (see below). Never embed text and discard where it came from.
+
+```python
+# Heading-aware split sketch; real size tuning belongs in embeddings-search.
+def chunk_markdown(doc_id, text, target=800, overlap=120):
+    sections, buf, head = [], [], None
+    for line in text.splitlines():
+        if line.startswith("#"):
+            if buf: sections.append((head, "\n".join(buf))); buf = []
+            head = line.lstrip("# ").strip()
+        else:
+            buf.append(line)
+    if buf: sections.append((head, "\n".join(buf)))
+    out, i = [], 0
+    for head, body in sections:
+        for start in range(0, max(1, len(body)), target - overlap):
+            piece = body[start:start + target]
+            out.append({"chunk_id": f"{doc_id}#{i}", "source": doc_id,
+                        "heading": head, "text": piece})
+            i += 1
+    return out
+```
+
+For the deep "what window/overlap maximizes recall for *this* corpus" study, that is
+`embeddings-search`. Here you just need structurally sane chunks that keep their ids.
+
+## Contextual retrieval — prepend context before you embed
+
+Anthropic's Contextual Retrieval (Sept 2024) prepends a short LLM-generated blurb to each chunk
+*before* embedding **and** before BM25 indexing, so an isolated chunk knows what document and
+section it belongs to. Why it matters: it cuts failed retrievals by ~35% (contextual embeddings
+alone), ~49% (contextual embeddings + contextual BM25), and ~67% once reranking is added
+(anthropic.com/news/contextual-retrieval, 2024-09; accessed 2026-06-02).
+
+```text
+<document>{{WHOLE_DOC}}</document>
+Here is the chunk we want to situate within the whole document:
+<chunk>{{CHUNK}}</chunk>
+Give a short, standalone context (1–2 sentences) that situates this chunk within the
+document for search retrieval. Answer only with the context, nothing else.
+```
+
+Embed `context + "\n" + chunk_text` (not the bare chunk). The full implementation — caching the
+document prompt, batching, the BM25 side — lives in `references/pipeline.md`.
+
+## Hybrid retrieval + RRF + rerank
+
+Dense vectors miss exact terms (codes, names, error strings); BM25 keyword search catches them
+but misses paraphrase. Combine both, fuse with **Reciprocal Rank Fusion (RRF)**, then rerank
+with a cross-encoder. The default-best quality/cost funnel (Microsoft Cloud Blog 2025-02-04;
+StackAI, accessed 2026-06-02):
+
+```text
+retrieve ~150 candidates (dense + BM25, fused with RRF)
+   → rerank all 150 with a cross-encoder
+   → keep top ~20 for the prompt
+```
+
+The actual hybrid query (named vectors, sparse-dense, server-side fusion) is `vector-db`. Here
+you own the funnel and the reranker choice:
+
+- **Cohere Rerank 3.5** — managed cross-encoder, context length 4096, SOTA on BEIR and
+  multilingual, available via Cohere API, Bedrock, Pinecone, Azure (docs.cohere.com/changelog/
+  rerank-v3.5, accessed 2026-06-02). Use when you want quality without hosting a model.
+- A **local cross-encoder** (e.g. a `bge-reranker`) — use when data cannot leave your network or
+  you need zero per-call cost; you pay in GPU/latency instead.
+
+```python
+# Rerank the fused candidates down to the prompt set; keep ids intact.
+import cohere
+co = cohere.ClientV2()
+ranked = co.rerank(model="rerank-v3.5", query=q,
+                   documents=[c["text"] for c in candidates], top_n=20)
+top = [candidates[r.index] for r in ranked.results]  # each still carries chunk_id + source
+```
+
+## Ground the prompt — answer only from context, cite, refuse
+
+Properly grounded RAG reduces hallucination rates by up to ~71%; poorly grounded pipelines still
+hallucinate in up to ~40% of responses *even with the right doc retrieved* (Confident AI / Maxim
+2025, accessed 2026-06-02). The prompt must do three non-negotiable things: bind the answer to
+the context, force inline citations, and provide an explicit refusal path.
+
+```text
+You answer ONLY using the information inside <context>. Do not use prior knowledge.
+Cite every claim with the chunk id it came from, like [chunk_id]. Multiple ids are fine.
+If the context does not contain enough information to answer, reply exactly:
+"I don't have enough information in the provided sources to answer that."
+(Spanish corpora: "No tengo suficiente información en las fuentes para responder.")
+
+<context>
+[doc12#3] {chunk text...}
+[doc12#4] {chunk text...}
+</context>
+
+Question: {{question}}
+```
+
+A grounding prompt **without a refusal path is a bug** — it converts "missing context" into a
+confident fabrication. The refusal clause is what turns retrieval failures into honest non-answers.
+
+## Citations — carry ids the whole way
+
+The answer can only link back if a stable id survives every stage: chunk → retrieve → rerank →
+prompt → answer. Why: if you embed text and drop the id at index time, there is nothing for a
+citation to point at, and you cannot debug which passage produced a wrong claim.
+
+- Put `chunk_id` and `source` on the chunk at creation; keep them on the object through rerank.
+- Render them into the `<context>` block (`[chunk_id] text`) so the model can quote them.
+- Map cited ids back to source URLs/pages when you render the answer to the user.
+
+## Evaluating it — metrics, not vibes
+
+Faithfulness is **not** correctness: an answer can be faithful to a wrong chunk. Measure four
+RAGAS metrics on a small golden Q/A set (RAGAS docs; Cohorte 2025; Confident AI, accessed
+2026-06-02):
+
+| Failure symptom | Metric that catches it | First fix |
+|---|---|---|
+| Answer states things not in the sources | **faithfulness** (claims supported by context) | grounding prompt + refusal |
+| Answer is on-topic but doesn't address the question | **answer relevancy** | prompt / query rewriting |
+| Relevant chunks exist but rank below junk | **context precision** | reranker, RRF weights |
+| The needed chunk never gets retrieved | **context recall** | chunking, contextual retrieval, hybrid |
+
+Build a 30–50 question golden set with known-good answers, score with RAGAS, and gate CI below a
+threshold (e.g. faithfulness ≥ 0.90, context recall ≥ 0.85). Full formulas, thresholds, and the
+CI snippet are in `references/evaluation.md`. The general-purpose eval harness is `agent-eval`;
+the RAG-specific metrics live here.
+
+## Anti-patterns
+
+| Anti-pattern | Why it breaks | Do instead |
+|---|---|---|
+| Fixed char-count chunking, blind to structure | Splits mid-sentence; dilutes embeddings | Heading/semantic chunks with overlap |
+| Rerank disabled — stuff top-50 raw into prompt | Noise drowns the right passage; cost balloons | Retrieve ~150 → rerank → keep ~20 |
+| No refusal path in the grounding prompt | Missing context becomes confident fabrication | Explicit "I don't have enough information" |
+| Embed text, drop the chunk id | Nothing to cite or debug | Carry `chunk_id`+`source` end to end |
+| "It looks good" eval on vibes | Regressions ship silently | Golden set + RAGAS + CI threshold gate |
+| Embedding the query differently from the corpus | Query and chunks land in different spaces | Same model + same preprocessing both sides |
+| Dense-only, ignoring BM25/keyword | Misses exact codes/names/error strings | Hybrid dense + BM25 fused with RRF |
+| Tuning temperature to fix wrong answers | Generation is rarely the bottleneck | Measure context recall first |
+
+## Wiring map
+
+- **Ingestion (file → text, OCR, tables):** `../document-processing/SKILL.md` — you assume text
+  already exists; send raw PDFs/DOCX/scans there first.
+- **The store (collection, index, hybrid query, quantization):** `../vector-db/SKILL.md` — you
+  call it to upsert and query; it owns the knobs.
+- **Embedding model + chunk-size science:** `embeddings-search` — picking the model, dims,
+  cost, and the semantic-vs-fixed chunking experiments.
+- **Chat product surface (sessions, channels, UI):** `../chatbot/SKILL.md` — wraps the answer
+  you return; it calls you, not the reverse.
+- **Multi-step tool/agent loop with state:** `../building-agents/SKILL.md` — when retrieval is
+  one tool among many in a larger loop.
+- **General eval framework:** `agent-eval` — RAG-specific metrics are here; the harness is there.
+- **Schema-constrained field extraction:** `structured-extraction` — when the goal is fields,
+  not a grounded prose answer.
+
+See `references/pipeline.md` for the full runnable retrieve → rerank → answer skeleton and
+`references/evaluation.md` for the metric formulas, thresholds, and CI gate.

package/skills/rag/evals/README.md

@@ -0,0 +1,13 @@
+# rag evals — how to run
+
+These are routing and capability checks, not unit tests. Run the `should_trigger` prompts against
+your skill router and confirm `rag` fires; run the `should_not_trigger` prompts and confirm the
+router instead defers to the named sibling (`vector-db`, `embeddings-search`, `document-processing`,
+`chatbot`, `structured-extraction`) — a miss there means the boundary in the description needs
+sharpening. For the `capability` case, hand the scenario to the agent with this skill loaded and
+grade the answer against the `must_include` rubric line by line (does it name all five pipeline
+stages, hybrid + RRF, the rerank funnel, the grounding-plus-refusal contract, the eval gate, and
+the two handoffs); each rubric item is pass/fail. You can do this by hand or wire it through the
+`agent-eval` harness for a repeatable score. `scripts/verify.sh` is the static gate on the skill's
+own artifacts (frontmatter, the grounding contract, the references, the RAGAS metric names) and is
+separate from these capability checks.

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"