Retrieval and ranking

Frigg separates discovery from proof. Exact tools answer bounded lookup questions; hybrid search ranks useful pivots; navigation follows resolved identities; reads return the source evidence used for a claim.

Exact retrieval

Use exact tools when you already know the shape of the question:

list_files for repository-relative paths
search_text for literals, safe regexes, globs, path scopes, counts, and file-containment queries
search_symbol for known identifiers
document_symbols for one file’s outline
search_structural for a known Tree-sitter query shape

These collections report a completeness envelope. An exact total exists only when Frigg proves coverage; a continuation represents the next page of the same normalized request and repository snapshot.

Ranked discovery

search_hybrid is for vague questions that do not yet have an exact string, identifier, or path. It can combine lexical, path, witness, symbol, graph, and optional semantic signals to rank candidate pivots.

Hybrid output is deliberately non-exhaustive. Its completeness reports ranked discovery, does not claim an exact total, and offers no exhaustive continuation. Use the result to extract a path, noun, string, or symbol, then confirm it with search_text, search_symbol, or navigation before answering.

Hybrid graph signals

The hybrid graph channel is ranking evidence, not a navigation call graph. graph_mode and ranking notes describe why a path moved in the result order; they do not prove definitions, references, or calls.

Use go_to_definition, find_references, incoming_calls, or another navigation tool when the relationship itself matters. Treat outgoing_calls as provisional and confirm important edges by reading the callable body.

Semantic acceleration

Semantic retrieval is off by default and never becomes the grounding layer. When enabled, it can improve natural-language recall, but the final proof loop remains hybrid candidate → exact pivot → source read.

If compact hybrid output says lexical_only (semantic not contributing), Frigg still used its non-semantic ranking channels. This is an expected mode when semantic runtime is disabled or produced no evidence, not a reason to abandon exact Frigg tools.

Multi-probe composition

search_batch runs two to eight independent text, symbol, or hybrid probes and merges their rows. It is not one multi-pattern scan. Results rank by consensus, fixed equal-weight reciprocal-rank fusion, derived strength, and stable coordinates.

Read each probe’s trust and completeness separately from aggregate completeness. Row evidence, consensus_count, rrf_score, and match_strength explain the merge; raw scores from different search kinds are not directly comparable.

From candidates to proof

Discover with the narrowest suitable search tool.
Inspect completeness and structured recovery.
Select a row and preserve its target_ref or proof pair.
Navigate the exact target when relationships matter.
Read the source with read_match or read_file.

See Result and recovery contracts for paging, targets, next actions, and stale-proof behavior.

Source Anchors

../frigg/README.md
../frigg/crates/cli/src/searcher/mod.rs
../frigg/crates/cli/src/searcher/retrieval_projection/mod.rs
../frigg/crates/cli/src/mcp/types/search.rs
../frigg/crates/cli/src/mcp/types/completeness.rs
../frigg/docs/operator-runbook.md
../frigg/skills/frigg-first-code-search/SKILL.md