retrieval-router

name	retrieval-router
description	Decide per task whether to RETRIEVE targeted slices (grep/embeddings, read only what's relevant) or LOAD broad context (whole files/dirs), instead of always dumping the codebase. Use on large repos or long docs when deciding what to put in context. Trigger with /retrieval-router or "rag or long-context", "how much should I load", "what context for this".
version	0.1.0
user-invocable	true
metadata	{"emoji":"🧭"}

retrieval-router

On a big repo, the question before any task is: pull the few relevant slices, or load broad context? Defaulting to "load everything" is slow, expensive, and triggers context rot. This skill routes the choice per task.

Why this exists (evidence)

• RAG vs long-context comparative study + Self-Route (arXiv:2407.16833): long-context wins on average WHEN fully resourced, but RAG is far cheaper; Self-Route (let the model decide per query which to use) recovers most of the accuracy at a fraction of the cost.
• Naive broad loading also degrades via context rot (accuracy drops as irrelevant tokens grow). So "more context" is not free or always better.

The routing decision

Per task, pick:

RETRIEVE (targeted) when:

• The task is localized: a specific function, bug, symbol, endpoint, config key.
• The repo is large; only a few files matter.
• You can name what to look for (grep terms, symbol, file pattern). -> Use targeted reads: grep/symbol search, then read only those slices (offset/limit), follow references on demand.

LOAD BROAD (more context) when:

• The task needs global/architectural reasoning (cross-module refactor, "how does X flow end to end").
• The relevant set is small enough to fit and genuinely interrelated. -> Load the cohesive set, but still drop irrelevant parts (compose with context-warden).

DEFAULT = retrieve first, escalate to broad only if retrieval misses. (This is Self-Route applied by hand: cheap path first, expand only when needed.)

The method

1. Classify the task: localized vs global.
2. If localized: list the search terms / symbols, retrieve those slices, act. Do not read whole files when a slice answers it.
3. If retrieval is insufficient (you keep chasing references), widen to the cohesive module, not the whole repo.
4. State what you loaded and why, so the context stays auditable and lean.

Composes with

• context-warden: once you've decided WHAT to pull, warden keeps the pulled set masked/compacted.
• multi-repo-context: routes retrieval across repos in scope.
• run-cost: broad loading is the big cost driver; estimate before dumping.

Honest limits

• Retrieval can miss (bad search terms -> missed file). When unsure and the task is high-stakes, widen rather than risk an uninformed answer.
• This is a routing discipline, not a vector DB. For heavy semantic retrieval over a huge corpus, pair with a real index (e.g. the recall MCP or a code-search tool).
• The cited results are on mixed benchmarks; code-specific transfer is plausible but measure your own.