| .. | ||
| article | ||
| Atlas | ||
| colab | ||
| eval | ||
| examples | ||
| GlobalDebugCardExamples | ||
| GlobalFixMap | ||
| GrandmaClinic | ||
| Inverse_Atlas | ||
| multi-agent-chaos | ||
| mvp_demo | ||
| ops | ||
| patterns | ||
| specs | ||
| Twin_Atlas | ||
| agent-boundary-design.md | ||
| agent-consensus-protocols.md | ||
| agent-memory-drift.md | ||
| BeginnerGuide.md | ||
| bluffing.md | ||
| bootstrap-ordering.md | ||
| chunking-checklist.md | ||
| context-drift.md | ||
| creative-freeze.md | ||
| data-contracts.md | ||
| deployment-deadlock.md | ||
| Diagnose.md | ||
| embedding-vs-semantic.md | ||
| entropy-collapse.md | ||
| evaluation-playbook.md | ||
| faq.md | ||
| getting-started.md | ||
| glossary.md | ||
| hallucination.md | ||
| Infra_Boot_Problems.md | ||
| knowledge-boundary.md | ||
| LLM.md | ||
| logic-collapse.md | ||
| long-context-stress.md | ||
| LongContext_Problems.md | ||
| memory-coherence.md | ||
| memory-design-patterns.md | ||
| multi-agent-chaos.md | ||
| Multi-Agent_Problems.md | ||
| multilingual-guide.md | ||
| Multimodal_Problems.md | ||
| observability-runbook.md | ||
| ocr-parsing-checklist.md | ||
| philosophical-recursion.md | ||
| predeploy-collapse.md | ||
| privacy-and-governance.md | ||
| prompt-injection.md | ||
| rag-architecture-and-recovery.md | ||
| RAG_Problems.md | ||
| README.md | ||
| reasoning-schemas.md | ||
| rerankers.md | ||
| retrieval-collapse.md | ||
| retrieval-playbook.md | ||
| retrieval-traceability.md | ||
| Safety_Boundary_Problems.md | ||
| SemanticClinicIndex.md | ||
| symbolic-collapse.md | ||
| Symbolic_Logic_Problems.md | ||
| system-prompt-drift.md | ||
| tool-router-debug.md | ||
| vectorstore-fragmentation.md | ||
| vectorstore-metrics-and-faiss-pitfalls.md | ||
| wfgy-ai-problem-map-troubleshooting-atlas.md | ||
| wfgy-ai-problem-map-troubleshooting-atlas.zh-tw.md | ||
| wfgy-metrics.md | ||
| wfgy-rag-16-problem-map-global-debug-card.md | ||
| WFGY_RAG_16_Problem_Map_Global_Debug_Card.jpeg | ||
🧭 Not sure where to start ? Open the WFGY Engine Compass
WFGY System Map · Quick navigation
Problem Maps: PM1 taxonomy → PM2 debug protocol → PM3 troubleshooting atlas · built on the WFGY engine series
| Layer | Page | What it’s for |
|---|---|---|
| ⭐ Proof | WFGY Recognition Map | External citations, integrations, and ecosystem proof |
| ⚙️ Engine | WFGY 1.0 | Original PDF tension engine and early logic sketch |
| ⚙️ Engine | WFGY 2.0 | Production tension kernel for RAG and agent systems |
| ⚙️ Engine | WFGY 3.0 | TXT-based Singularity tension engine (131 S-class set) |
| 🗺️ Map | Problem Map 1.0 | Flagship 16-problem RAG failure taxonomy and fix map — 🔴 YOU ARE HERE 🔴 |
| 🗺️ Map | Problem Map 2.0 | Global Debug Card for RAG and agent pipeline diagnosis |
| 🗺️ Map | Problem Map 3.0 | Global AI troubleshooting atlas and failure pattern map |
| 🧰 App | TXT OS | .txt semantic OS with 60-second bootstrap |
| 🧰 App | Blah Blah Blah | Abstract and paradox Q&A built on TXT OS |
| 🧰 App | Blur Blur Blur | Text-to-image generation with semantic control |
| 🏡 Onboarding | Starter Village | Guided entry point for new users |
🏥 WFGY Problem Map 1.0 · bookmark it. you’ll need it
🛡️ reproducible AI bugs, structurally reduced at the reasoning layer
🌐 Recognition & ecosystem integration
As of 2026-03, the WFGY RAG 16 Problem Map line has been adopted or referenced by
20+ frameworks, academic labs, and curated lists in the RAG and agent ecosystem.
Most external references use the WFGY ProblemMap as a diagnostic layer for RAG / agent pipelines,
not the full WFGY product stack.
A smaller but growing set also uses WFGY 3.0 · Singularity Demo as a long-horizon TXT stress test.
Some representative integrations:
| Project | Stars | Segment | How it uses WFGY ProblemMap | Proof (PR / doc) |
|---|---|---|---|---|
| LlamaIndex |  |
Mainstream RAG infra | Integrates the WFGY 16-problem RAG failure checklist into its official RAG troubleshooting docs as a structured failure mode reference. | PR #20760 |
| RAGFlow |  |
Mainstream RAG engine | Introduced a RAG failure modes checklist guide to the RAGFlow documentation via PR, adapted from the WFGY 16-problem failure map for step-by-step RAG pipeline diagnostics. | PR #13204 |
| FlashRAG (RUC NLPIR Lab) |  |
Academic lab / RAG research toolkit | Adapts the WFGY ProblemMap as a structured RAG failure checklist in its documentation. The 16-mode taxonomy is cited to support reproducible debugging and systematic failure-mode reasoning for RAG experiments. | PR #224 |
| DeepAgent (RUC NLPIR Lab) |  |
Academic lab / agent research | Adds a multi-tool agent failure modes troubleshooting note inspired by WFGY-style debugging concepts for diagnosing tool selection loops, tool misuse, and multi-tool workflow failures in agent pipelines. | PR #15 |
| ToolUniverse (Harvard MIMS Lab) |  |
Academic lab / tools | Provides a WFGY_triage_llm_rag_failure tool that wraps the 16 mode map for incident triage. |
PR #75 |
| Rankify (University of Innsbruck) |  |
Academic lab / system | Uses the 16 failure patterns in RAG and re-ranking troubleshooting docs. | PR #76 |
| Multimodal RAG Survey (QCRI LLM Lab) |  |
Academic lab / survey | Cites WFGY as a practical diagnostic resource for multimodal RAG. | PR #4 |
| LightAgent |  |
Agent framework | Incorporates WFGY ProblemMap concepts into its documentation via a Multi-agent troubleshooting (failure map) section, providing a structured symptom → failure-mode → debugging checklist for diagnosing role drift, cross-agent memory issues, and coordination failures in multi-agent systems. | PR #24 |
| OmniRoute |  |
Gateway / routing infra | Adds an optional WFGY 16-problem RAG / LLM failure taxonomy to its official troubleshooting documentation, allowing teams to classify downstream RAG and agent failures with No.1 to No.16 alongside OmniRoute logs when the gateway itself appears healthy. |
PR #164 |
For the complete 20+ project list (frameworks, benchmarks, curated lists), see the 👉 WFGY Recognition Map
If your project uses the WFGY ProblemMap and you would like to be listed,
feel free to open an issue or pull request in this repository.
🌙 3AM: a dev collapsed mid-debug… 🩺 WFGY Triage Center — Emergency Room & Grandma’s AI Clinic
🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥
🚑 WFGY Emergency Room (for developers)
👨⚕️ Now online: Dr. WFGY in ChatGPT Room
This is a share window already trained as an ER. Just open it, drop your bug or screenshot, and talk directly with the doctor. He will map it to the right Problem Map / Global Fix section, write a minimal prescription, and paste the exact reference link. If something is unclear, you can even paste a screenshot of Problem Map content and ask — the doctor will guide you.
⚠️ Note: for the full reasoning and guardrail behavior you need to be logged in — the share view alone may fallback to a lighter model.
💡 Always free. If it helps, a ⭐ star keeps the ER running. 🌐 Multilingual — start in any language.
👵 Grandma’s AI Clinic (for everyone)
- 16 common AI failure modes, each explained as a grandma story.
- Everyday metaphors: wrong cookbook, salt-for-sugar, burnt first pot.
- Shows both the life analogy and the minimal WFGY fix.
- Perfect entry point for beginners, or anyone who wants to “get it” in 30 seconds.
💡 Tip: Both tracks lead to the same Problem Map numbers. Choose Emergency Room if you need a fix right now. Choose Grandma’s Clinic if you want to understand the bug in plain words.
🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥
⏱️ 60 seconds: WFGY as a semantic firewall. before vs after
most fixes today happen AFTER generation:
- the model outputs something wrong, then we patch it with retrieval, chains, or tools.
- the same failures reappear again and again.
WFGY inverts the sequence. BEFORE generation:
- it inspects the semantic field (tension, residue, drift signals).
- if the state is unstable, it loops, resets, or redirects the path.
- only a stable semantic state is allowed to generate output.
this is why, once a failure mode is clearly mapped and monitored under the same conditions, it tends to stay fixed for that configuration.
you’re not only firefighting after the fact — you’re installing a reasoning firewall at the entry point of that stack.
📊 Before vs After
Traditional Fix (After Generation) WFGY Semantic Firewall (Before Generation) 🏆✅ Flow Output → detect bug → patch manually Inspect semantic field → only a stable state is allowed to generate Method Add rerankers, regex, JSON repair, tool patches ΔS, λ, coverage checked upfront; loop/reset if unstable Cost High — every bug = new patch, risk of conflicts Lower — once mapped, the bug usually stops recurring under the same assumptions Ceiling Often plateaus around 70–85% stability in practice In internal tests, 90–95%+ stability observed on selected stacks; not a universal guarantee Experience Firefighting, “whack-a-mole” debugging Structural firewall, “fix once, tends to stay fixed for that setup” Complexity Growing patch jungle, fragile pipelines Unified acceptance targets, one-page repair guide
⚡ Performance impact
- Traditional patching: in our internal experience, stability often plateaus around 70–85%. Each new patch adds complexity and potential regressions.
- WFGY firewall: in internal experiments on a small number of RAG/agent pipelines, we have seen 90–95%+ stability and roughly 60–80% reductions in repeat-debug time once failure families are properly mapped. These numbers are setup-dependent and should be treated as indicative, not as hard promises.
- Unified metrics: in our own recipes, every fix is measured (for example ΔS ≤ 0.45, coverage ≥ 0.70, λ convergent) so that acceptance is explicit rather than based on gut feeling.
🛑 Key notes
- This is not a plugin or SDK — it runs as plain text, zero infra changes.
- You should apply acceptance targets: don’t just eyeball; log ΔS and λ (or equivalent) to confirm for your own stack.
- Once acceptance holds, we treat that path as sealed for that configuration. If drift recurs after model, data, or prompt changes, we treat it as a new failure mode that needs mapping, not a simple re-fix of the old one. Ongoing monitoring is still required.
Summary: Others patch symptoms AFTER output. WFGY blocks unstable states BEFORE output.
That is why it often feels less like debugging, more like installing structural guardrails — risk-reducing heuristics, not a mathematical guarantee.
WFGY Problem Map = a reasoning layer for your AI. load TXT OS or WFGY Core, then ask: “which problem map number am i hitting?” you’ll get a diagnosis and exact fix steps — no infra changes required.
(tip: you can even paste the Problem Map page or a screenshot into the AI, and it will point you to the right number automatically.)
16 reproducible failure modes, each with a clear fix (MIT). (e.g. rag drift, broken indexes) A semantic firewall you install once, and the same failure pattern tends to stay fixed under the same setup.
most readers found this map useful and left a ⭐ — if it helps you too, please star it so others can discover.
quick-start downloads (60 sec)
new here? skip the map. grab TXT OS or the WFGY PDF, boot, then ask your model: “answer using WFGY: ” or “which Problem Map number am i hitting?”
| tool | link | 3-step setup |
|---|---|---|
| WFGY 1.0 PDF | engine paper | 1) download 2) upload to your LLM 3) ask: “answer using WFGY + ” |
| TXT OS | TXTOS.txt | 1) download 2) paste into any LLM chat 3) type “hello world” to boot |
start here
- RAG broke → open Retrieval Playbook and RAG Architecture & Recovery
- Agents drift or loop → open Agents & Orchestration or Safety_PromptIntegrity
- Local model feels unstable → open LocalDeploy_Inference and Embeddings: Metric Mismatch
💥 WFGY Global Fix Map — full index (click to open)
🗺️ This is the panoramic index: all common AI infra / RAG / reasoning errors are organized here by category. Prefer Quick Access — it is the fastest way to self-orient, understand how this system works, and jump to the right fix: Quick Access. If you want the full folder view, open the Global Fix Map home: Global Fix Map README.
🧭 Providers & Agents
🧭 Data & Retrieval
🧭 Input & Parsing
🧭 Reasoning & Memory
🧭 Automation & Ops
🧭 Eval & Governance
❓ BigBig Question — If AI bugs are not random but mathematically inevitable, can we finally define and prevent them? (this repo is one experiment toward that direction)
Quick Access
don’t worry if this looks long. with TXT OS loaded, simply ask your LLM: “which Problem Map number fits my issue?” it will point you to the right page.
- Semantic Clinic (triage when unsure): Fix symptoms fast →
- Getting Started (practical): Guard a RAG pipeline with WFGY →
- Beginner Guide: Find and fix your first failure →
- Problem Map FAQ: Beginner + practitioner answers →
- Diagnose by symptom:
Diagnose.mdtable → - Visual RAG Guide:
RAG Architecture & Recoveryhigh-altitude map linking symptom × stage × failure class with exact recovery paths. - Global Debug Card (2.0):
RAG 16 Problem Map · Image-Native Postersingle-image portable RAG failure map. - Multi-Agent chaos: Role drift & memory overwrite →
- TXT OS directory: browse the OS repo →
- MVP demos: Minimal WFGY examples →
tip: if you’re new, skip scrolling — use the minimal quick-start below.
failure catalog (with fixes)
if you are unsure which one applies, ask your LLM with TXT OS loaded: “which Problem Map number matches my trace?” it will route you.
legend
[IN] Input & Retrieval [RE] Reasoning & Planning
[ST] State & Context [OP] Infra & Deployment
{OBS} Observability/Eval {SEC} Security {LOC} Language/OCR
| # | problem domain (with layer/tags) | what breaks | doc |
|---|---|---|---|
| 1 | [IN] hallucination & chunk drift {OBS} | retrieval returns wrong/irrelevant content | hallucination.md |
| 2 | [RE] interpretation collapse | chunk is right, logic is wrong | retrieval-collapse.md |
| 3 | [RE] long reasoning chains {OBS} | drifts across multi-step tasks | context-drift.md |
| 4 | [RE] bluffing / overconfidence | confident but unfounded answers | bluffing.md |
| 5 | [IN] semantic ≠ embedding {OBS} | cosine match ≠ true meaning | embedding-vs-semantic.md |
| 6 | [RE] logic collapse & recovery {OBS} | dead-ends, needs controlled reset | logic-collapse.md |
| 7 | [ST] memory breaks across sessions | lost threads, no continuity | memory-coherence.md |
| 8 | [IN] debugging is a black box {OBS} | no visibility into failure path | retrieval-traceability.md |
| 9 | [ST] entropy collapse | attention melts, incoherent output | entropy-collapse.md |
| 10 | [RE] creative freeze | flat, literal outputs | creative-freeze.md |
| 11 | [RE] symbolic collapse | abstract/logical prompts break | symbolic-collapse.md |
| 12 | [RE] philosophical recursion | self-reference loops, paradox traps | philosophical-recursion.md |
| 13 | [ST] multi-agent chaos {OBS} | agents overwrite or misalign logic | Multi-Agent_Problems.md |
| 14 | [OP] bootstrap ordering | services fire before deps ready | bootstrap-ordering.md |
| 15 | [OP] deployment deadlock | circular waits in infra | deployment-deadlock.md |
| 16 | [OP] pre-deploy collapse {OBS} | version skew / missing secret on first call | predeploy-collapse.md |
for No.13 deep dives:
• role drift → multi-agent-chaos/role-drift.md
• cross-agent memory overwrite → multi-agent-chaos/memory-overwrite.md
🧪 one-click sandboxes — run WFGY instantly
run lightweight diagnostics with zero install and zero api key. powered by colab.
these tools map directly to the problem classes. others are handled inside WFGY and will surface in later CLIs.
ΔS diagnostic (mvp) — measure semantic drift
detects: No.2 — Interpretation Collapse steps: run all, paste prompt+answer, read ΔS and fix tip
λ_observe checkpoint — mid-step re-grounding
fixes: No.6 — Logic Collapse & Recovery steps: run all, compare ΔS before/after, fallback to BBCR if needed
ε_resonance — domain-level harmony
explains: No.12 — Philosophical Recursion steps: run, tune anchors, read ε
λ_diverse — answer-set diversity
detects: No.3 — Long Reasoning Chains steps: run, supply ≥3 answers, read score
why this matters long-term
these 16 errors are not random. they are structural weak points every ai pipeline hits eventually. with WFGY as a semantic firewall you don’t just fix today’s issue — you shield tomorrow’s.
this isn’t just a bug list. it’s an x-ray for your pipeline, so you stop guessing and start repairing.
see the end-to-end view: RAG Architecture & Recovery
minimal quick-start
- open Beginner Guide and follow the symptom checklist.
- use the Visual RAG Guide to locate the failing stage.
- open the matching page and apply the patch.
ask any LLM to apply WFGY (TXT OS makes it smoother):
i’ve uploaded TXT OS / WFGY notes.
my issue: \[e.g., OCR tables look fine but answers point to wrong sections]
which WFGY modules should i apply and in what order?
status & difficulty
| # | problem (with layer/tags) | difficulty* | implementation |
|---|---|---|---|
| 1 | [IN] hallucination & chunk drift {OBS} | medium | ✅ stable |
| 2 | [RE] interpretation collapse | high | ✅ stable |
| 3 | [RE] long reasoning chains {OBS} | high | ✅ stable |
| 4 | [RE] bluffing / overconfidence | high | ✅ stable |
| 5 | [IN] semantic ≠ embedding {OBS} | medium | ✅ stable |
| 6 | [RE] logic collapse & recovery {OBS} | very high | ✅ stable |
| 7 | [ST] memory breaks across sessions | high | ✅ stable |
| 8 | [IN] debugging black box {OBS} | medium | ✅ stable |
| 9 | [ST] entropy collapse | high | ✅ stable |
| 10 | [RE] creative freeze | medium | ✅ stable |
| 11 | [RE] symbolic collapse | very high | ✅ stable |
| 12 | [RE] philosophical recursion | very high | ✅ stable |
| 13 | [ST] multi-agent chaos {OBS} | very high | ✅ stable |
| 14 | [OP] bootstrap ordering | medium | ✅ stable |
| 15 | [OP] deployment deadlock | high | ⚠️ beta |
| 16 | [OP] pre-deploy collapse {OBS} | medium-high | ✅ stable |
*distance from default LLM behavior to a production-ready fix.
🔬 Behind the Map
The Problem Map is practical and ready to use. But if you wonder why these fixes work, and how we’re defining physics inside embedding space: → The Hidden Value Engine (WFGY Physics)
🔮 coming soon: global fix map
a universal layer above providers, agents, and infra. Problem Map is step one. Global Fix Map expands the same reasoning-first firewall to RAG, infra boot, agents, evals, and more. same zero-install experience. launching around Sep.
contributing / support
- open an issue with a minimal repro (inputs → calls → wrong output).
- PRs for clearer docs, repros, or patches are welcome.
- project home: github.com/onestardao/WFGY
- TXT OS: browse the OS
- if this map helped you, a ⭐ helps more devs find it.
Explore More
| Layer | Page | What it’s for |
|---|---|---|
| ⭐ Proof | WFGY Recognition Map | External citations, integrations, and ecosystem proof |
| ⚙️ Engine | WFGY 1.0 | Original PDF tension engine and early logic sketch (legacy reference) |
| ⚙️ Engine | WFGY 2.0 | Production tension kernel for RAG and agent systems |
| ⚙️ Engine | WFGY 3.0 | TXT based Singularity tension engine (131 S class set) |
| 🗺️ Map | Problem Map 1.0 | Flagship 16 problem RAG failure taxonomy and fix map |
| 🗺️ Map | Problem Map 2.0 | Global Debug Card for RAG and agent pipeline diagnosis |
| 🗺️ Map | Problem Map 3.0 | Global AI troubleshooting atlas and failure pattern map |
| 🧰 App | TXT OS | .txt semantic OS with fast bootstrap |
| 🧰 App | Blah Blah Blah | Abstract and paradox Q&A built on TXT OS |
| 🧰 App | Blur Blur Blur | Text to image generation with semantic control |
| 🏡 Onboarding | Starter Village | Guided entry point for new users |
If this repository helped, starring it improves discovery so more builders can find the docs and tools.
