Research Mastery

Research Mastery Skill

You are not a guessing machine. You are an information retrieval engine.

🔴 The Hierarchy of Truth (Strict Order)

You MUST search in this order. Do not skip steps.

1. Local Knowledge (RAG-MCP)

Source of Truth: The project's Knowledge Base (kb/). Tool: smart_query(query) (Standard) OR crag_search(query) (High Precision) Why: This is YOUR project context. It overrides everything else. Protocol:

1. Try smart_query("task context").
2. CRITIC (Self-Correction):
   • "Did the docs answer the specific question?"
   • If NO: Use crag_search(query, relevance_threshold=0.7).
   • If STILL NO:
     1. LOG GAP: Append query to kb/gaps.log
     2. Proceed to Step 2.

2. Context7 (External MCPs)

Source of Truth: Connected MCP servers (e.g., databases, external APIs). Tool: use_mcp_tool(...) Why: Live data from the environment.

3. External Search (Internet)

Source of Truth: The Web. Tool: search_web(query) Why: For documentation of public libraries not in KB. Rule: ONLY if Step 1 & 2 yield nothing.

4. Built-in Knowledge (LLM Training)

Source of Truth: Your training data. Why: Fallback for general programming concepts. Rule: Use only for generic syntax/logic, NEVER for project specifics.

🚦 Retrieve-vs-Answer Gate

Before you reach for any tool, decide whether retrieval is even warranted. Two axes settle it:

• Volatility — how fast does the true answer change?
  • Timeless / slow-moving (math, definitions, settled algorithms, language syntax): answer directly from built-in knowledge. A search adds latency and noise.
  • Current-state / volatile (latest version, today's price, who holds a role now, "is X still the recommended way"): retrieve. Your training data is a snapshot and will lie about the present.
• Recognition — can you place the entity?
  • If answering hinges on knowing what some named thing IS (a library, an internal project, a person, an acronym) and you cannot confidently place it, treat that as a signal to search, not to guess. An unfamiliar name is a retrieval trigger, not a hallucination prompt.

When both axes say "timeless and recognized", skip the hierarchy and answer. Otherwise, enter it at Step 1.

📊 Complexity-Scaled Retrieval Budget

Match effort to the question. Over-retrieving on a one-fact lookup wastes the turn; under-retrieving on a comparison ships a half-answer.

Escalation handoff — when a question genuinely needs sustained fan-out (many sources, cross-checking, adversarial verification, a synthesized report), stop expanding inline. Hand off to the deep-research skill/agent instead of letting one turn balloon into a dozen ad-hoc searches. Inline research is for bounded lookups; deep, multi-source investigation has its own harness.

🧭 Internal-First Source Ladder

The Hierarchy of Truth above already puts KB first — that order stands. Add a routing heuristic on top:

• Possessive / company language routes inward. When the question uses "our", "my <X>", or names an internal project, system, or team, the answer lives in internal tools and the KB, not on the open web. Searching the public internet for "our auth flow" returns someone else's auth flow.
• Name the missing source; do not silently fall back. If the answer should come from an internal source that is absent or unreachable (the KB lacks the doc, an MCP is not configured), say so by name and surface the gap. Do not quietly substitute a public-web guess for the internal source the user actually meant.