diagnose-rag-failurelisted

# Diagnose a RAG Failure "The answer is wrong" has four causes with four different fixes. Find which one before changing anything. ## When this applies - Wrong or incomplete answer to a question the corpus can answer - Hallucinated content despite relevant documents existing - "I cannot find that" when the document exists - Citations pointing at the wrong source - A regression after changing chunking, embeddings, k, or the prompt ## Do not use for - Building a pipeline → `build-rag-pipeline` - Creating the eval set → `build-rag-evalset` ## Inputs to collect first | Input | Why needed | Default if unspecified | |---|---|---| | The failing question | The case | **Blocking** | | The expected answer | Defines "wrong" | **Blocking** | | The document that should answer it | Gives you the gold chunk | **Blocking** — find it manually if needed | | Retrieved chunks with scores | The evidence | Re-run the query with logging | | Recent config changes | Regression candidates | `git log` on the retrieval config | ## Procedure ### Step 1 — Locate the gold chunk Find, by hand, the chunk that *should* answer the question. Note its id. If no chunk contains the answer, the failure is **upstream of retrieval**: either the document was never ingested, or chunking split the answer across two chunks. Check the index for the `doc_id` first — a missing document is the most common "retrieval bug". **Stop condition:** you have a gold chunk id, or you know the document is not indexed. ###