# get_answer

get_answer is one-call RAG over the wiki: it retrieves, gates on confidence and returns a cited answer with fallback targets. Call it first on code questions.

Collapses **search → read → reason** into one round-trip. The tool
retrieves the most relevant wiki pages, enriches the top hits with
symbol docstrings and source excerpts, hands them to the LLM, and
returns a synthesized answer with citations and a confidence label.
If confidence is low, it returns `best_guesses`, a justified,
per-file candidate list with excerpts, instead of an empty answer,
letting the agent pick one to verify instead of skim the field.
It reads the [generated documentation](https://docs.repowise.dev/intelligence/auto-wiki) and its
search index; see [MCP tools](https://docs.repowise.dev/mcp/overview) for where it fits among the
other tools.

## When to call

- **Always first** on any code question, before `search_codebase` or
  manual file exploration.
- If `confidence` is `"medium"` or `"low"`, follow up with
  `search_codebase` and `get_context` on the `fallback_targets`.
- Works best when the question names explicit identifiers (a class,
  function, or module name).

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `question` | string |  | Required. The developer's question, in natural language. |
| `scope` | string |  | Optional path prefix to restrict retrieval (e.g. "src/auth/"). |
| `repo` | string |  | Repository alias. Usually omitted; pass when the question is about a specific repo in a workspace. "all" is not supported. |
| `include` | string[] |  | ["evidence"] returns the expanded evidence projection (up to 32,000 characters instead of 24,000). ["diagnostics"] adds retrieval_quality. |

## Returns

| Field | Description |
|---|---|
| `answer` | Synthesized answer with inline file citations |
| `citations` | File paths the answer references |
| `confidence` | `"high"`, `"medium"`, or `"low"`, the one trust signal. It is graded from the retrieval and from whether the top hit covers what the question asks. `high` may be cited directly |
| `degraded` | Present when no answer was synthesized: `"no-llm-provider"` or `"synthesis-failed"`. The reply is ranked evidence, never `high` confidence. Retry `synthesis-failed`; with no provider the evidence is the answer |
| `grounding` | How a grounded answer was produced: `"symbol_body"`, `"exact_symbol"` or `"extracted"`. Cite it directly |
| `retrieval_quality` | Only with `include=["diagnostics"]`: `"high"`, `"partial"`, or `"weak"`, the rating of the retrieval alone. It feeds `confidence` |
| `candidate_files` | Ranked file paths the citations do not already name: up to 3 at `high` confidence, 5 otherwise. On `low`, read these before searching again |
| `fallback_targets` | Top file paths from retrieval; agent should `get_context` on these for verification |
| `candidates` | The ranked shortlist of files retrieval resolved, one `{path, lines?}` entry each, up to 5. Present whenever retrieval resolved anything, including high-confidence answers where `retrieval` is deliberately empty. It's where to look next, not evidence the answer is right |
| `retrieval` | Top 5 wiki hits with `title`, `target_path`, `score`, `summary`, and (for top 2 file pages) symbols with docstrings and source excerpts |
| `symbol_bodies` | When the answer names a function/method/class, the full live body of each question-named symbol, inlined so no `get_symbol` follow-up is needed |
| `best_guesses` | On a low-confidence, gated response: a per-file candidate list, each with `file`, `why_relevant`, `score`, and (when available) an `excerpt`, so the agent can pick one to verify instead of skimming several |
| `episodes` | At most one dated fact recorded about this checkout, present only below `high` confidence and when its scope intersects the answer |
| `note` | Context string explaining why synthesis was skipped or hedged |
| `_meta` | Timing, cache hit, answer hint |

## Example

```python
get_answer("how does the authentication flow work?")
get_answer(
    "how are database migrations handled?",
    scope="backend/",
)
```

## Things worth knowing

- **Confidence is checked, not self-reported.** A hedge in the model's own
  answer ("the evidence does not identify") lowers it. So do an answer that
  names none of the question's identifiers, a number the retrieved material
  does not contain, or a mechanism the cited code does not show.
- **Question-aware symbol promotion**: symbols matching identifiers
  extracted from the question get longer docstrings (400 chars) and a
  40-line source body excerpt, so "how does `X` work?" questions can
  be answered without hedging.
- **Intersection retrieval**: relational questions ("how does X talk
  to Y?") are split into two queries; hits appearing in both get a 2×
  boost.
- **Caching**: questions are normalized and hashed; repeat questions
  hit the answer cache instantly. Hedged cached answers are bypassed
  for re-synthesis when the symbol pipeline is updated.
- **No LLM provider configured?** The reply carries
  `degraded: "no-llm-provider"`: ranked hits and snippets at `medium`
  confidence, or `low` when retrieval is weak. Local source,
  symbols and full-text search still answer.
- **`candidates` vs `retrieval`.** `retrieval` is evidence: enriched hits
  to re-read when the prose needs checking, and it shrinks as confidence
  rises. `candidates` is navigation: a flatter, longer shortlist of every
  file retrieval resolved, present even on high-confidence answers.

> **Note**
>
> `get_answer` is the most useful tool in the set. Most "what does
> this codebase do?" or "where is X handled?" questions are answered in
> a single call.