rag-troubleshoot

rag-troubleshoot — RAG-first debugging

When to use this skill

Trigger the moment the user reports:

• A specific error message, stack trace, or exception
• "It broke", "it fails", "not working", "returns null when it shouldn't"
• Unexpected behavior in a component
• Alert / incident triage
• "Why does X do Y" where Y is wrong
• A pasted log line
• A failed CI/CD run

The core insight: many bugs are already solved somewhere in your corpus — runbook, postmortem, incident report, prior fix commit, ADR, chat thread indexed via add_from_url. Search first.

---

What this skill commits to

Before proposing a fix, the agent searches for:

1. The error signature itself — exception name, first line of stack, unique error code
2. The affected component / function — module name, service name, feature
3. Prior incidents with similar symptoms — even if the error message differs

Only after those three come back empty does the agent apply general debugging techniques.

---

Steps

1. Extract error signatures from the user's message:

   • Exception class name (ValueError, ConnectionError, TimeoutError, etc.)
   • Error code (ERR_INVALID_TOKEN, E42_INDEX_MISS, HTTP status)
   • First distinctive line of the stack trace
   • Unique keywords ("segfault at ...", "cannot connect to ...")

2. First search — exact error signature:

   search_knowledge(query="<exception name> <error keyword>", max_results=5, min_score=0.15)
   

   Example: search_knowledge(query="ConnectionError refused chromadb")

3. Second search — affected component + symptom:

   search_knowledge(query="<component name> <what happens>", max_results=5)
   

   Example: search_knowledge(query="reindex fails halfway large corpus")

4. Third search — historical incidents / postmortems:

   search_knowledge(query="incident postmortem <component>", max_results=5)
   

   Or with a category filter if your corpus categorizes by document type:

   search_knowledge(query="<component> failure", category="incidents")