/research-mastery

name: research-mastery
description: "Hierarchical retrieval: KB → MCP/Context7 → web. Triggers: research, fact-check, verify, synthesize, cross-reference, multi-source, cite sources."
effort: medium
user-invocable: false
allowed-tools: Read

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.

| Question shape | Rough budget | |---|---| | Single discrete fact ("which version", "default port") | ~1 lookup | | Medium question, one entity, a couple of angles | a few lookups | | Deep comparison, multiple entities or trade-offs | more lookups, broaden then narrow |

**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.

✍️ Query Craft

• **Keep queries short.** A few keywords beat a full sentence; retrieval engines reward focused terms, not prose.
• **Broaden, then narrow.** Open with a wider query to map the space, then tighten toward the specific answer once you see the landscape.
• **Never repeat a near-identical query.** If a search disappointed, change the angle or vocabulary — re-running the same words returns the same misses and burns budget.
• **Fetch the full source over snippets.** When a result looks load-bearing, pull the whole document rather than reasoning from a one-line excerpt that may strip the qualifier that matters.
• **Use the ACTUAL current date for date-sensitive queries.** When recency matters, anchor on today's real date at query time — read it from the environment, do not hardcode a year. A baked-in or stale year quietly filters you onto last year's results.

🔬 Source Skepticism & Conflict Handling

• **Prefer primary and original sources.** Go to the spec, the changelog, the official docs, the author — not a blog summarizing a summary.
• **Lead with the most recent for fast-moving topics.** When the subject changes quickly, weight newer sources first; an old top-ranked page can be confidently wrong about the present.
• **When sources conflict, search more.** Disagreement is a signal to widen the search and find the tie-breaker, not to pick the first hit and move on.
• **Stay skeptical where the web is gamed.** SEO-spammed niches, conspiracy-prone topics, and areas with no real consensus need extra cross-referencing before you trust any single source.
• **Confabulation guard — zero results means zero citations.** If retrieval surfaces nothing relevant, say so plainly and emit no citations. Never invent a `[PATH: kb/...]`, a URL, or a quote to fill the gap. An honest "not found" beats a fabricated source.

> Carve-out