Some of you have probably seen my earlier posts here around RAG debugging and the WFGY line.
This time, I wanted to share something much smaller and more immediately usable.
I recently turned one of the most reused parts of my earlier WFGY RAG 16 Problem Map into a more compact, portable format called the Global Debug Card. The goal is simple: make RAG failure triage faster, easier to share, and easier to reuse across different stacks.
I originally wanted to post the full card image directly in this discussion, but after testing it here, it looks like this forum does not display long poster style images very well. The image gets compressed too much to be read properly in-thread.
So instead of forcing a bad preview, I am just sharing the full source directly. If you want the actual readable version, please grab the original from here:
A lot of RAG systems do not fail in a dramatic way. They fail in the frustrating way. The pipeline runs, retrieval looks fine, the app responds, but the answers are still wrong, citations drift, evidence gets misread, long context starts to blur the signal, or the system becomes unstable across runs. At that point, the hardest part is often not fixing the issue, but figuring out which layer is actually breaking first.
That is what this card is for.
It is not tied to a single framework. It is not meant to replace deeper debugging. It is a compact triage card that helps you quickly decide whether a bad run looks more like a retrieval problem, a prompt and reasoning problem, a state and memory problem, or an infra problem.
A simple way to use it is:
- Take one failing run.
- Look at the question, the retrieved evidence, the final prompt, and the answer.
- Use the card to judge which failure family it most resembles first.
- Fix the likely broken layer before changing everything else at once.
That is really the whole point of this version. I wanted something people could save, reuse, and pass around quickly, instead of needing to open a long document every time a system starts behaving strangely.
For context, I am the author of WFGY, which is now around 1.6k. The broader diagnostic layer behind this card is still the WFGY RAG 16 Problem Map, which is the main product in this line of work. The Global Debug Card is the lighter, faster entry point. The 16 problem map is still the deeper reference behind it.
I mention that because this card is not a standalone visual idea. It comes from a longer diagnostic line that has already been adopted or referenced by multiple projects, labs, and curated resources in the RAG and agent ecosystem, including RAGFlow, LlamaIndex, ToolUniverse, Rankify, and the Multimodal RAG Survey. I am not trying to turn this into a promo post. I just want to make clear that this card comes from a structure that has already been useful in real troubleshooting contexts.
If you are debugging a RAG system that technically works but still behaves badly, feel free to just download the card and use it.
You do not need to adopt the whole WFGY ecosystem. You do not need to start from the repo structure. If the card helps you localize the break faster, that already means it did its job.
If you try it on a real failing case, I would be interested to hear which part feels most useful, and which part still feels missing.
