This PR adds a new RAG tutorial called “WFGY 16 Problem Map RAG Failure Clinic” under rag_tutorials/wfgy_rag_failure_clinic.
The app is a small, self-contained RAG failure clinic.
You paste a real LLM / RAG bug description, and the script:
maps it to one of 16 failure modes from the WFGY Problem Map (No.1–No.16), then
suggests a minimal structural fix, not just a prompt tweak.
All additional knowledge comes from the open source WFGY repo on GitHub (MIT license).
What’s included
A new folder: rag_tutorials/wfgy_rag_failure_clinic
README.md
Full step-by-step tutorial and setup instructions
A compact reference table for all 16 WFGY Problem Map entries, each linking back to the original docs
A sample terminal interaction that shows how the clinic classifies a bug
Notes on how to run the script both locally and in Colab
wfgy_rag_failure_clinic.py
Minimal interactive CLI that:
downloads the WFGY Problem Map README and TXTOS prompt file from GitHub
builds a system prompt that encodes the 16-problem taxonomy
lets the user choose between 3 built-in examples or paste their own bug
calls any OpenAI-compatible chat completion API (OpenAI, Nebius, custom proxy, etc.)
prints the diagnosis and suggested structural fix
requirements.txt
Only two dependencies:
openai>=1.6.0
requests>=2.31.0
How it fits the repo
This tutorial focuses on debugging and failure analysis instead of building a full RAG stack.
It complements the existing rag_tutorials examples by:
showing how to turn a failure taxonomy into a reusable system prompt
encouraging users to paste real production bugs and reason about them structurally
keeping the implementation very small and easy to adapt to other taxonomies or checklists
The script is provider-agnostic and works with any OpenAI-compatible endpoint as long as the environment variables are set:
OPENAI_API_KEY (required)
OPENAI_BASE_URL (optional)
OPENAI_MODEL (optional, defaults to gpt-4o)
How to run
From the repo root:
cd rag_tutorials/wfgy_rag_failure_clinic
pip install -r requirements.txt
exportOPENAI_API_KEY="sk-..."# or set via your preferred method
python wfgy_rag_failure_clinic.py
Then:
choose one of the three built-in examples, or
paste your own RAG / LLM bug description and let the clinic classify it into No.1–No.16.
The README also includes a short note on how to run the same script directly in Colab by pasting it into a single cell.
Original WFGY Problem Map and TXTOS design by the WFGY author.
This tutorial is a small integration example contributed to awesome-llm-apps to demonstrate how a failure taxonomy can be plugged into an LLM debugging tool.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.
## 📋 Pull Request Information
**Original PR:** https://github.com/Shubhamsaboo/awesome-llm-apps/pull/482
**Author:** [@onestardao](https://github.com/onestardao)
**Created:** 2/9/2026
**Status:** ❌ Closed
**Base:** `main` ← **Head:** `main`
---
### 📝 Commits (9)
- [`f0d53c7`](https://github.com/Shubhamsaboo/awesome-llm-apps/commit/f0d53c7d1391cf767ae1d454327e67ac9fca71ba) Create README.md
- [`6e0caeb`](https://github.com/Shubhamsaboo/awesome-llm-apps/commit/6e0caeb6896d17b5a8c19c4049c4814354b9e86d) Update README.md
- [`0d33e77`](https://github.com/Shubhamsaboo/awesome-llm-apps/commit/0d33e77903b3b6fc02fcdb587de7fb38612cccfc) Create wfgy_rag_failure_clinic.py
- [`4decfbb`](https://github.com/Shubhamsaboo/awesome-llm-apps/commit/4decfbbfcdf7a8ebaae03167ae41652450ab4ce4) Update wfgy_rag_failure_clinic.py
- [`97fa6a8`](https://github.com/Shubhamsaboo/awesome-llm-apps/commit/97fa6a8eef0261f02ccaae7217a942784b4c29fa) Update README.md
- [`a13e367`](https://github.com/Shubhamsaboo/awesome-llm-apps/commit/a13e36797faa64595e525519154a73ec38d49ece) Update README.md
- [`69dae50`](https://github.com/Shubhamsaboo/awesome-llm-apps/commit/69dae501cd7fef8bf5caeabe5b46216ae7d0c517) Create requirements.txt
- [`d19b139`](https://github.com/Shubhamsaboo/awesome-llm-apps/commit/d19b139f90eeafd5e99480b8119434963113d505) Update README.md
- [`49a6fd8`](https://github.com/Shubhamsaboo/awesome-llm-apps/commit/49a6fd893370ec302ce5fbd0ce1401c81a2efb7a) Update README.md
### 📊 Changes
**4 files changed** (+700 additions, -0 deletions)
<details>
<summary>View changed files</summary>
📝 `README.md` (+1 -0)
➕ `rag_tutorials/wfgy_rag_failure_clinic/README.md` (+461 -0)
➕ `rag_tutorials/wfgy_rag_failure_clinic/requirements.txt` (+2 -0)
➕ `rag_tutorials/wfgy_rag_failure_clinic/wfgy_rag_failure_clinic.py` (+236 -0)
</details>
### 📄 Description
**Summary**
This PR adds a new RAG tutorial called **“WFGY 16 Problem Map RAG Failure Clinic”** under
`rag_tutorials/wfgy_rag_failure_clinic`.
The app is a small, self-contained **RAG failure clinic**.
You paste a real LLM / RAG bug description, and the script:
- maps it to **one of 16 failure modes** from the WFGY Problem Map (No.1–No.16), then
- suggests a **minimal structural fix**, not just a prompt tweak.
All additional knowledge comes from the open source WFGY repo on GitHub (MIT license).
---
**What’s included**
- A new folder: `rag_tutorials/wfgy_rag_failure_clinic`
- `README.md`
- Full step-by-step tutorial and setup instructions
- A compact reference table for all 16 WFGY Problem Map entries, each linking back to the original docs
- A sample terminal interaction that shows how the clinic classifies a bug
- Notes on how to run the script both locally and in Colab
- `wfgy_rag_failure_clinic.py`
- Minimal interactive CLI that:
- downloads the WFGY Problem Map README and TXTOS prompt file from GitHub
- builds a system prompt that encodes the 16-problem taxonomy
- lets the user choose between 3 built-in examples or paste their own bug
- calls any **OpenAI-compatible** chat completion API (OpenAI, Nebius, custom proxy, etc.)
- prints the diagnosis and suggested structural fix
- `requirements.txt`
- Only two dependencies:
- `openai>=1.6.0`
- `requests>=2.31.0`
---
**How it fits the repo**
This tutorial focuses on **debugging and failure analysis** instead of building a full RAG stack.
It complements the existing `rag_tutorials` examples by:
- showing how to turn a **failure taxonomy** into a reusable system prompt
- encouraging users to paste real production bugs and reason about them structurally
- keeping the implementation very small and easy to adapt to other taxonomies or checklists
The script is provider-agnostic and works with any OpenAI-compatible endpoint as long as the environment variables are set:
- `OPENAI_API_KEY` (required)
- `OPENAI_BASE_URL` (optional)
- `OPENAI_MODEL` (optional, defaults to `gpt-4o`)
---
**How to run**
From the repo root:
```bash
cd rag_tutorials/wfgy_rag_failure_clinic
pip install -r requirements.txt
export OPENAI_API_KEY="sk-..." # or set via your preferred method
python wfgy_rag_failure_clinic.py
````
Then:
* choose one of the three built-in examples, or
* paste your own RAG / LLM bug description and let the clinic classify it into No.1–No.16.
The README also includes a short note on how to run the same script directly in Colab by pasting it into a single cell.
---
**Attribution**
* WFGY project: [https://github.com/onestardao/WFGY](https://github.com/onestardao/WFGY)
* Original WFGY Problem Map and TXTOS design by the WFGY author.
* This tutorial is a small integration example contributed to **awesome-llm-apps** to demonstrate how a failure taxonomy can be plugged into an LLM debugging tool.
---
<sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
📋 Pull Request Information
Original PR: https://github.com/Shubhamsaboo/awesome-llm-apps/pull/482
Author: @onestardao
Created: 2/9/2026
Status: ❌ Closed
Base:
main← Head:main📝 Commits (9)
f0d53c7Create README.md6e0caebUpdate README.md0d33e77Create wfgy_rag_failure_clinic.py4decfbbUpdate wfgy_rag_failure_clinic.py97fa6a8Update README.mda13e367Update README.md69dae50Create requirements.txtd19b139Update README.md49a6fd8Update README.md📊 Changes
4 files changed (+700 additions, -0 deletions)
View changed files
📝
README.md(+1 -0)➕
rag_tutorials/wfgy_rag_failure_clinic/README.md(+461 -0)➕
rag_tutorials/wfgy_rag_failure_clinic/requirements.txt(+2 -0)➕
rag_tutorials/wfgy_rag_failure_clinic/wfgy_rag_failure_clinic.py(+236 -0)📄 Description
Summary
This PR adds a new RAG tutorial called “WFGY 16 Problem Map RAG Failure Clinic” under
rag_tutorials/wfgy_rag_failure_clinic.The app is a small, self-contained RAG failure clinic.
You paste a real LLM / RAG bug description, and the script:
All additional knowledge comes from the open source WFGY repo on GitHub (MIT license).
What’s included
rag_tutorials/wfgy_rag_failure_clinicREADME.mdwfgy_rag_failure_clinic.pyrequirements.txtopenai>=1.6.0requests>=2.31.0How it fits the repo
This tutorial focuses on debugging and failure analysis instead of building a full RAG stack.
It complements the existing
rag_tutorialsexamples by:The script is provider-agnostic and works with any OpenAI-compatible endpoint as long as the environment variables are set:
OPENAI_API_KEY(required)OPENAI_BASE_URL(optional)OPENAI_MODEL(optional, defaults togpt-4o)How to run
From the repo root:
Then:
The README also includes a short note on how to run the same script directly in Colab by pasting it into a single cell.
Attribution
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.