docs: reference WFGY 16-problem RAG failure map in TROUBLESHOOTING

[onestardao]

This PR adds a small, docs-only section to docs/TROUBLESHOOTING.md that references the WFGY ProblemMap as an optional RAG / LLM failure taxonomy.

Details:

• Introduces an “Optional RAG / LLM failure taxonomy (16 problems)” section under Troubleshooting.
• Explains when it is useful: OmniRoute looks healthy, but answers are still wrong because the downstream RAG or agent stack is misbehaving.
• Describes how teams can tag incidents with No.1 … No.16 from the WFGY ProblemMap and keep those tags next to OmniRoute logs.
• Links to the external WFGY ProblemMap README (MIT license, text only) for full definitions and fix recipes.

Scope:

• English troubleshooting doc only.
• No code or API changes.
• Existing behavior of OmniRoute is unchanged; the section is optional and can be ignored by users who do not run RAG / agent pipelines behind the gateway.

Closes #157.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the documentation by adding a valuable resource for users experiencing issues with RAG or agent stacks behind OmniRoute. It provides a structured approach to diagnosing and categorizing failures that originate downstream, offering a common vocabulary and methodology for identifying root causes when the gateway itself is functioning correctly. This addition aims to improve the troubleshooting experience for users leveraging advanced LLM architectures.

Highlights

• New Troubleshooting Section: Added a new section to docs/TROUBLESHOOTING.md titled "Optional RAG / LLM failure taxonomy (16 problems)".
• RAG/LLM Failure Taxonomy: Introduced the WFGY ProblemMap as an external resource for categorizing RAG/LLM failures, particularly when OmniRoute appears healthy but downstream answers are incorrect.
• Usage Guidance: Provided clear steps on how to use the WFGY ProblemMap to map incidents, store failure numbers, and inform changes to RAG stacks or routing strategies.
• External Link: Included a direct link to the WFGY ProblemMap README for full definitions and fix recipes.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• docs/TROUBLESHOOTING.md
  • Added a new section "Optional RAG / LLM failure taxonomy (16 problems)" to provide guidance on diagnosing RAG/LLM failures.
  • Included an explanation of when to use the WFGY ProblemMap taxonomy, specifically when OmniRoute is healthy but answers are wrong.
  • Detailed a four-step process for users to map incidents to WFGY ProblemMap numbers and use the resource for remediation.
  • Provided a link to the external WFGY ProblemMap README for comprehensive details and solutions.

Activity

• No specific activity (comments, reviews, progress updates) has been recorded for this pull request yet, beyond its initial creation.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds a helpful new section to the troubleshooting documentation regarding a failure taxonomy for RAG/LLM stacks. The content is clear and well-structured. I've suggested a minor formatting improvement to the markdown for better source readability and adherence to common practices.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Overview

This is a documentation-only PR that adds a new section to docs/TROUBLESHOOTING.md titled "Optional RAG / LLM failure taxonomy (16 problems)". The content provides helpful guidance for users running RAG or agent pipelines behind OmniRoute.

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	0

Verification Completed

• ✅ External link to WFGY ProblemMap verified (HTTP 200)
• ✅ MIT license properly attributed
• ✅ Clear "Optional" disclaimer for non-RAG users
• ✅ No security issues (documentation-only)
• ✅ No runtime errors (no code changes)
• ✅ No logic bugs (no code changes)

Files Reviewed (1 file)

• docs/TROUBLESHOOTING.md - Documentation addition only (+35 lines)

[diegosouzapw]

Thanks @onestardao for this thoughtful docs contribution! 🎉 The WFGY ProblemMap reference gives our users who run RAG pipelines behind OmniRoute a great framework for classifying failures. Merged and appreciated! 🙏

[onestardao]

Glad to contribute! Happy to see the WFGY ProblemMap being useful for the OmniRoute community.