rag-check-first

rag-check-first — search before you speak

When to use this skill

Trigger this skill before answering whenever the user asks:

• A technical "how" or "why" question (design, implementation, security, ops)
• Something about "our" / "the project" / "the team" / a named component
• A request to write, refactor, review, or debug code
• A question that could plausibly be answered by an ADR, runbook, README, or spec

Trigger keywords / patterns (non-exhaustive):

• "how does X work", "why did we", "what is the pattern for"
• "add a", "implement", "refactor", "fix", "debug"
• Any mention of a file, module, function, feature, or component by name
• Any question about historical decisions ("we used to", "the old way")

Do NOT trigger for:

• Pure conversation / meta requests ("hi", "thanks", "what's your name")
• Requests that are explicitly about the AI itself
• Well-known facts already in training data with no team-specific angle

---

What this skill commits to

Before drafting a single line of the answer, the agent will call search_knowledge at least once with a query derived from the user's message. The results shape the answer — training-data knowledge is only a fallback when RAG returns nothing relevant.

---

Steps

1. Extract the search query from the user's message. Prefer 2–5 keywords, not full sentences. Include domain-specific identifiers (class names, error codes, feature names, ADR IDs).

2. Call search_knowledge:

   search_knowledge(query="<extracted keywords>", max_results=5, snippet_mode=true, min_score=0.15)
   

   • snippet_mode=true keeps token consumption sane
   • min_score=0.15 cuts obvious noise (adjust higher for terse corpora)

3. Read the top 3 results. Pay attention to search_method (hybrid > semantic / keyword alone), score, and reranker_score.

4. Decide the answer strategy based on what came back:

   RAG result	What to do
   ≥1 result with score > 0.5 matching the intent	Answer primarily from the RAG content, quote relevant snippets, cite the source (path:line)
   1–3 results with lower scores (0.2–0.5)	Use as partial context, be explicit that the corpus does not cover this in depth, mix with training-data knowledge
   0 results after 2 attempts with varied phrasing	State it: "Local corpus does not have this. Answering from general knowledge — verify before acting." Optionally chain to rag-web-fallback