After nine months of chasing weird hallucinations and silent failures in production LLM / RAG systems, we catalogued every failure pattern we could reproduce. The result is an MIT-licensed “Semantic Clinic” with 16 root-cause families and step-by-step fixes.

---

## Why we built it

@ Most bug reports just say “the model lied,” but the cause is almost always deeper: retrieval drift, OCR mangling, prompt contamination, etc.

@ Existing docs mix symptoms and remedies in random blogposts; we wanted one map that shows where the pipeline breaks and why.

@ After fixing the same issues across 11 real stacks we decided to standardise the notes and open-source them.

---

## What’s inside

@ 16 root-cause pages (Hallucination & Chunk Drift, Interpretation Collapse, Entropy Melts, etc.).

@ Quick triage index: find the symptom → jump to the fix page.

@ Each page gives: real-world symptoms, metrics to watch (ΔS semantic tension, λ_observe logic flow), a reproducible notebook, and a “band-aid-to-surgery” list of fixes.

@ Tiny CLI tools: semantic diff viewer, prompt isolator, vector compression checker. All plain bash + markdown so anyone can fork.

---

## Does it help?

@ On our own stacks the average debug session dropped from hours to ~15 min once we tagged the family.

@ The first 4 root causes explain ~80 % of the bugs we see in the wild.

@ Used so far on finance chatbots, doc-QA, multi-agent sims; happy to share war stories.

## Call for help

@ If you’ve hit a failure that isn’t on the list, open an issue or PR. We especially want examples of symbolic prompt contamination or large-scale entropy collapse. @ Long-term goal: turn the clinic into a self-serve triage bot that annotates stack traces automatically.

---

## Why open-source?

Debug knowledge shouldn’t be pay-walled. The faster we share failure modes, the faster the whole field moves (and the fewer 3 a.m. rollbacks we all do).

Cheers – PSBigBig / WFGY team