From 61e09d545f82a90306ab72f5323d92cd9a3b5a72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?PSBigBig=20=C3=97=20MiniPS?= Date: Sun, 1 Mar 2026 10:56:51 +0800 Subject: [PATCH 1/2] docs: add optional RAG failure taxonomy to troubleshooting --- docs/TROUBLESHOOTING.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index f05a13ff14..167ed2cb7f 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -210,6 +210,41 @@ When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex --- +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + ## Still Stuck? - **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) From 0488f0536e9eb99a4adece91788161f24747e058 Mon Sep 17 00:00:00 2001 From: Diego Rodrigues de Sa e Souza <8016841+diegosouzapw@users.noreply.github.com> Date: Sun, 1 Mar 2026 06:33:22 -0300 Subject: [PATCH 2/2] Update docs/TROUBLESHOOTING.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/TROUBLESHOOTING.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 167ed2cb7f..7bb8e136c7 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -218,13 +218,13 @@ In practice these incidents usually come from the downstream RAG pipeline, not f If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift - deployment and bootstrap ordering problems The idea is simple: