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.
@ 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).
i mostly use LLMs inside a reasoning shell i built — like a lightweight semantic OS where every input gets recorded as a logic node (with ΔS and λ_observe vectors) and stitched into a persistent memory tree.
it solved a bunch of silent failures i kept running into with tools like RAG and longform chaining:
drift across hops (multi-step collapse)
hallucination on high-similarity chunks
forgetting prior semantic commitments across calls
the shell is plain-text only (no install), MIT licensed, and backed by tesseract.js’s creator.
i’ll drop the link if anyone’s curious — not pushing, just realized most people don’t know this class of tools exists yet.
Built the rerankers, stacked the re-chunkers, tweaked the embed dimensions like a possessed oracle. Still watched the model hallucinate a reference from the correct document — but to the wrong sentence. Or answer logically, then silently veer into nonsense like it ran out of reasoning budget mid-thought.
No errors. No exceptions. Just that creeping, existential “is it me or the model?” moment.
What you wrote about interpretation collapse and memory drift? Exactly the kind of failure that doesn’t crash the pipeline — it just corrodes the answer quality until nobody trusts it anymore.
Honestly, I didn’t know I needed names for these issues until I read this post. Just having the taxonomy makes them feel real enough to debug. Major kudos.
agree — I’ve used Q/S with AI-assisted query shaping too, especially when domain vocab gets wild.
the part I kept bumping into was: even with perfect-looking queries, the retrieved context still lacked semantic intent alignment.
so I started layering reasoning before retrieval — like a semantic router that decides not just what to fetch, but why that logic path even makes sense for this user prompt.
different stack, same headache. appreciate your insight though — it’s a solid route when retrieval infra is strong.
In my case, users would be searching through either custom defined data models (I have custom forms and stuff), or if they were trying to find a comment on a Task, or various other attached data on common entities.
For example, "When did Mark say that the field team ran into an issue with the groundwater swelling?"
That would return the Comment, tied to the Task.
In my system there are discussions and comments (common) tied to every data entity (and I'm using graphdb, which makes things exponentially simpler). I index all of these anyway for OS, so the AI is able to construct the query to find this. So I can go from comment -> top level entity or vice versa.
I spent maybe 60-100 hours writing dozens maybe a hundred tests to get the prompt right, taking it from 95% success to 100% success. In over 2 months it hasn't failed yet.
Sorry, I should mention maybe our use-cases are different. I am basically building an audit log.
ah yeah that makes sense — sounds like you're indexing for traceability first, which honestly makes your graph setup way more stable than most RAG stacks I’ve seen.
I’m more on the side of: “why is this even the logic path the system thinks makes sense for the user’s intent?” — like, how did we get from prompt to retrieval to that hallucination?
So I stopped treating retrieval as the answer. It’s just an echo. I started routing logic first — like a pre-retrieval dialectic, if you will. No index can help you if the question shouldn’t even be a question yet.
Your setup sounds tight though — we’re just solving different headaches. I’m more in the “why did the LLM go crazy” clinic. You’re in the “make the query land” ward.
Either way, I love that you built a graph audit log that hasn’t failed in two months. That's probably more production-ready than 90% of what people call “RAG solutions” now.
And really cool stuff you’re doing too. Honestly I have not spent as much time as maybe I should really diving into all the LLM tooling and stuff like you have.
hey — really appreciate that. honestly I’m still duct-taping this whole system together half the time, but glad it’s useful enough to sound like “tooling”
I think the whole LLM space is still missing a core idea: that logic routing before retrieval might be more important than retrieval itself. when the LLM “hallucinates,” it’s not always because it lacked facts — sometimes it just followed a bad question.
but yeah — if any part of this helps or sparks new stuff, then we’re already winning. appreciate the good vibes, and good luck on your own build too
haha fair — guess I’ve just been on the planet where the moment someone asks a followup like “can you explain that in simpler terms?”, the whole RAG stack folds like a house of cards.
if it’s been smooth for you, that’s awesome.
I’ve just been chasing edge cases where users go off-script, or where prompt alignment + retrieval break in weird semantic corners.
Totally agree, RAG by itself isn’t enough — especially when users don’t follow the script.
We’ve seen similar pain: one-shot retrieval works great in perfect lab settings, then collapses once you let in real humans asking weird followups like
“do that again but with grandma’s style”
and suddenly your context window looks like a Salvador Dali painting.
That branching tree approach you mentioned — composing prompt→prompt→query in a structured cascade — is underrated genius.
We ended up building something similar, but layered a semantic engine on top to decide which prompt chain deserves to exist in that moment, not just statically prewiring them.
It’s duct tape + divination right now.
But hey — the thing kinda works.
Appreciate your battle-tested insight — makes me feel slightly less insane.
This whole piece reads like someone trying to transcribe the untranscribable. Not ideas, not opinions — but the feel of what you meant. And that's exactly why art survives AI. Because machines transmit logic. But we leak ghosts.
We’ve been experimenting with this in the weirdest way — not by “improving AI art,” but by sabotaging it. Injecting memory residue. Simulating hand tremors. Letting the model forget what it just said and pick up something it didn’t mean to draw. That kind of thing.
The result isn’t perfect, but it’s getting closer to something that feels like a person was there. Maybe even a tired, confused, beautiful person.
We call the system WFGY. It’s open-source and probably way too chaotic for normal devs, but here’s the repo:
https://github.com/onestardao/WFGY
We’re also releasing a Blur module soon — a kind of “paper hallucination layer” — meant to simulate everything that makes real-world art messy and real.
Anyway, this post hit me. Felt like it walked in barefoot.
Just chiming in — been down this exact rabbit hole for months (same pain: useful != demo).
I ended up ditching the usual RAG+embedding route and built a local semantic engine that uses ΔS as a resonance constraint (yeah it sounds crazy, but hear me out).
Still uses local models (Ollama + gguf)
But instead of just vector search, it enforces semantic logic trees + memory drift tracking
Main gain: reduced hallucination in summarization + actual retention of reasoning across files
Weirdly, the thing that made it viable was getting a public endorsement from the guy who wrote tesseract.js (OCR legend). He called the engine’s reasoning “shockingly human-like” — not in benchmark terms, but in sustained thought flow.
Still polishing a few parts, but if you’ve ever hit the wall of “why is my LLM helpful but forgetful?”, this might be a route worth peeking into.
(Also happy to share the GitHub PDF if you’re curious — it’s more logic notes than launch page.)
I’ve built multiple RAG pipelines across Windsurf, Claude, and even Gemini-Codex hybrids, and I’ve learned this:
Most of the current devtools are competing at the UX/UI layer — not the semantic inference layer.
Claude dominates because it "feels smart" during code manipulation — but that’s not a model quality issue. It’s that Claude’s underlying attention bias aligns better with certain symbolic abstractions (e.g. loop repair or inline type assumptions). Cursor and Windsurf ride that perception well.
But if you inspect real semantic coherence across chained retrievals or ask them to operate across nonlinear logic breaks, most tools fall apart.
That’s why I stopped benchmarking tools by "stars" and started treating meaning-routing as a core design variable. I wrote a weird little engine to explore this problem:
