Search and discovery

Use this workflow when you need to locate an implementation, policy, API, or behavior in an unfamiliar repository.

Prerequisites

• Frigg is connected to the MCP client.
• The repository is known to the Frigg runtime.

Choose repository scope

In a normal single-repository session, omit repository_id. Frigg uses the session default or auto-adopts the only sensible repository.

Call workspace when the session is detached, the default is wrong, or several repositories are visible:

{
  "path": "/path/to/repository",
  "set_default": true,
  "resolve_mode": "git_root"
}

Before trusting indexed results after edits, inspect workspace.freshness. See work safely after edits.

Start with the narrowest search

Use exact text when you know a literal or regex:

{
  "query": "STALE_PROOF_ANCHOR",
  "pattern_type": "literal",
  "path_regex": "^crates/cli/src/",
  "context_lines": 2,
  "limit": 20
}

Use symbol search when you know an identifier:

{
  "query": "ResultCompleteness",
  "path_class": "runtime",
  "limit": 20
}

Use hybrid search when the question is conceptual and you do not yet know an exact anchor:

{
  "query": "how stale proof reads are rejected",
  "limit": 10
}

Hybrid rows are candidate pivots. Read ranking_note and best_pivot_path, then move to exact search, symbols, navigation, or a source read before making a claim.

Test several hypotheses together

Use search_batch when the same concept may appear under several identifiers or descriptions:

{
  "probes": [
    {
      "id": "error-code",
      "kind": "text",
      "query": "STALE_PROOF_ANCHOR"
    },
    {
      "id": "handler",
      "kind": "symbol",
      "query": "read_match"
    },
    {
      "id": "behavior",
      "kind": "hybrid",
      "query": "reject a source result after its file changes"
    }
  ],
  "limit": 20
}

Prefer rows with independent agreement, but inspect evidence[].trust and each probe_summary.completeness. Consensus improves prioritization; it does not make ranked hybrid evidence exhaustive.

Narrow by path and shape

Use list_files when the next question is about repository shape rather than content:

{
  "path_regex": "^crates/cli/src/mcp/",
  "language": "rust",
  "limit": 100
}

Use explore after you know a large file:

• probe finds text inside that file.
• zoom reads around a known source span.
• refine searches inside an anchor-derived window.

Use document_symbols to outline a large or overloaded file. Use inspect_syntax_tree before search_structural when you need syntax shape rather than names or text.

Follow continuation truth

For every bounded result, inspect completeness:

1. Confirm the unit matches what you intend to count.
2. Treat total as exact only when it is present.
3. If truncated=true and continuation is present, repeat the identical request with that token.
4. If complete=false without a continuation, read incomplete_reasons; broader paging cannot repair ranked or unavailable coverage.

Do not combine canonical continuation with legacy resume_from.

Turn discovery into proof

When a row has match_id and the response has result_handle, use read_match:

{
  "result_handle": "<RESULT_HANDLE>",
  "match_id": "m1",
  "before": 8,
  "after": 12,
  "presentation_mode": "citation"
}

When a row has target_ref, copy it unchanged into go_to_definition, find_references, or another navigation tool. See evidence and citations and navigation tools.

Recover from empty results

An empty matches[] is not enough to conclude absence. Inspect:

• completeness.complete and total;
• zero_hit_reason;
• applied scope;
• freshness under index;
• canonical next_actions.

Invoke a relevant next_actions[] entry through the ordinary MCP tool surface. Do not invent arguments from the prose hint when an exact action is available. See troubleshoot MCP results.

Verify the investigation

Before presenting a factual conclusion, confirm that:

• broad discovery was followed by exact or source-backed evidence;
• proof reads did not return a stale-handle error;
• counts use the reported completeness unit;
• heuristic or provisional navigation is labeled and independently checked.

Source Anchors

• ../frigg/README.md
• ../frigg/skills/frigg-first-code-search/SKILL.md
• ../frigg/skills/frigg-first-code-search/references/discovery-and-evidence.md
• ../frigg/crates/cli/src/mcp/types/search.rs
• ../frigg/crates/cli/src/mcp/types/completeness.rs
• ../frigg/crates/cli/src/mcp/types/next_action.rs