> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieval diagnostics

> Why isn't my chunk showing up?

The most common retrieval question: *"I know this document has the answer — why isn't the Agent finding it?"*

The Diagnostics tool walks the pipeline in reverse to find where things went wrong.

## Opening Diagnostics

Two entry points:

* **From a Trace** — click "Diagnose retrieval" on any retrieval step. Loads the exact query and preset used.
* **From a document** — right-click any chunk in your knowledge, "Test retrievability". Simulates queries that should find it.

## What Diagnostics shows

For a given query and expected chunk, Diagnostics answers:

1. **Is the chunk in the index?** — Sanity check. If not, look at the pipeline (was it filtered out during Clean? Chunker skipped it?).
2. **Do filters exclude it?** — Shows the filter set and whether the chunk passes.
3. **What's the vector score?** — Cosine similarity between query and chunk. Low scores (\< 0.2) mean semantic mismatch — the chunk doesn't "mean" what the query means.
4. **What's the keyword score?** — BM25 score. Low scores mean the query has no words in the chunk (maybe worth a synonym).
5. **What's the fused position?** — Where the chunk ranked in the top 50.
6. **Did reranker drop it?** — If reranking was on and it fell out of the top K.
7. **Did grounding drop it?** — If grounding was on and the chunk conflicted with the graph.

## Common failures and fixes

| Symptom                | Likely cause                                        | Fix                                                      |
| ---------------------- | --------------------------------------------------- | -------------------------------------------------------- |
| Not in the index       | Cleaned out, chunker skipped, source filter dropped | Check the Foundry run log for the source item            |
| Excluded by filter     | Metadata mismatch — chunk lacks the tag/field       | Add a tag in the enrichment stage, or loosen the filter  |
| Low vector score       | Query wording is far from chunk wording             | Add an alias in the document, or turn on query expansion |
| Low keyword score      | No literal terms in common                          | Same as above — or accept vector will handle it          |
| Ranked but below top-K | Boosts on another source outweighed it              | Adjust source/tag boosts                                 |
| Reranker dropped       | Cross-encoder judged another chunk more relevant    | Sometimes correct — inspect the winning chunk            |
| Grounding dropped      | Graph has a contradicting fact                      | Reconcile the graph or set grounding action to `demote`  |

## Fixing at scale

If diagnostics keeps pointing to the same root cause across many queries, that's a Signal. The Improvement flow (see [Optimization](/reliable/optimization/proposals)) can turn a recurring retrieval miss into a proposal for a new tag, a preset change, or a chunker adjustment.

## Retrievability tests

Save a set of "expected" chunk-for-query pairs as a **Retrievability test**. Runs in CI (or manually). Fails when your top-K stops including a chunk it used to include.

Good pattern: every time you fix a "why can't I find X" issue, add a retrievability test so the fix doesn't regress.