Problem Map 2.0 & Semantic Clinic — open-source triage for AI failures
A practical framework for anyone who is debugging retrieval-augmented generation, long-chain reasoning, or agent pipelines in production.
1. What’s new
| Upgrade | Purpose | Link |
|---|---|---|
| Problem Map 2.0 | 16 reproducible failure modes, each with a verified fix path (RAG drift, interpretation collapse, logic dead-ends, etc.) | https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md |
| Semantic Clinic Index | One-page triage table. Describe the symptom → jump straight to the right fix page. | https://github.com/onestardao/WFGY/blob/main/ProblemMap/SemanticClinicIndex.md |
Both are MIT-licensed, copied from real incident logs—not theoretical papers.
2. How to use
- Identify the symptom you’re facing (e.g. “vector store finds the chunk but answer is nonsense”).
- Open the matching row in the Semantic Clinic; it links to the detailed patch in Problem Map 2.0.
- Apply or adapt the patch. Each page includes minimal code, test cases, and fallback notes.
For quick experiments, four Colab sandboxes are provided (ΔS drift check, λ_observe checkpoint, e_resonance domain fit, λ_diverse answer variety). They run with no keys or installs.
3. Why these tools exist
- Most RAG / agent bugs are repeatable. We catalogued the patterns so you don’t waste hours rediscovering them.
- Classic debuggers stop at the API layer. These maps zoom out to the full semantic path: prompt → retrieve → reason → deploy.
- Open access matters. Every fix is MIT and documented; nothing is hidden behind a SaaS paywall.
4. Roadmap
- Additional CLI demos (entropy collapse, long-horizon chaining)
- Public release of the Drunk Transformer safety layer (WRI, WAI, WDT, WTF)
- Community case studies—send PRs if a fix saved your pipeline
If this material cuts your debug time, a GitHub star or field report is appreciated.
Feedback, edge cases, and negative results are all welcome.
