Many people working on RAG or different LLM pipelines probably have similar thoughts in their head:

[onestardao]

“I guess my vector database just isn’t tuned well enough.”
“If I retry a few times it is fine, it works most of the time anyway.”
“It is probably just the prompt, I should make it more precise.”

I used to think the same.
After spending the last year actually rescuing a lot of real projects, I realized the situation is not that simple.

In practice, so called “RAG problems” are often not just RAG.
They are failures that happen across the retrieval pipeline and the reasoning layer at the same time.
You get a mix of vector DB configuration issues, chunking strategy, ranking, tool routing, multi step reasoning.
At the end everything is covered by a very clean looking hallucination that hides all the bugs.

So I decided to organize these common disasters into a Problem Map.
Right now there are sixteen problem types, from the usual hallucination and chunk drift
to retrieval traceability, entropy collapse, multi agent chaos.
Each of them has its own explanation page and suggested fixes.

Problem Map is here:
https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md

WFGY always open clinic:
https://chatgpt.com/share/68b9b7ad-51e4-8000-90ee-a25522da01d7

To save everyone from reading all the docs from scratch every time,
I also built a “WFGY AI Clinic” share window.
You can treat it as an ER for RAG and LLM failures.

The usage is intentionally very simple.

Prepare the problem you are facing.
It can be a RAG pipeline, vector database, retriever, or LLM agent.

Describe the symptoms clearly.
For example the input question, the model answer, and the expected answer.

Attach as many real signals as you can.
Things like top k retrieval results, similarity scores, which vector DB you use
for example FAISS, Qdrant, Weaviate, Milvus, pgvector.

If you have prompts or a system architecture diagram, you can attach those too.

Then just throw all of this into the WFGY Clinic window.

Inside that window I already trained in the Problem Map and a diagnosis flow.
What it will do includes:

Restate your problem in plain language

Decide which Problem Map numbers your case is closest to

Explain clearly which layer is actually broken now
whether it is retrieval instead of embedding
or reasoning instead of the database

Give you a minimal reproducible set of debugging steps
starting from cheap experiments you can try immediately

If it matches a ProblemMap/XXX.md entry
it will give you the link so you can read the full technical explanation

Many people originally thought their system
was “just RAG performing badly”.
After sending the case into the clinic they discovered:

sometimes semantics do not match embeddings at all
sometimes the logic collapses inside long chain reasoning
sometimes the deployment pipeline has a bootstrap ordering issue.

The surface symptom can look almost the same
but the root causes are completely different.
In that situation blindly tuning parameters or switching vector DBs
mostly just amplifies the noise.

If you are working on RAG, document QA, LLM agents, or tool based applications
and your system occasionally has those “I cannot say exactly what is wrong” bugs,
you are welcome to bring a real case and test it with the WFGY AI Clinic.

I am also very interested in the different failure patterns of RAG and reasoning across projects.
Typical cases, after anonymizing, will be added back into the Problem Map
so this map can become more and more complete.