> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug Knowledge Retrieval

> Diagnose why Starfire AI did not retrieve an expected Knowledge source, chunk, repository file, or citation.

# Debug Knowledge retrieval

When Starfire gives an answer that appears to ignore a known source, first determine whether the problem happened at ingestion, permissions, retrieval, reranking, or model interpretation.

## Diagnostic sequence

```text theme={null}
Source exists?
   ↓
Processing complete?
   ↓
Indexed and ready?
   ↓
Requester has permission?
   ↓
Query retrieved a candidate?
   ↓
Reranker kept it?
   ↓
Context budget included it?
   ↓
Model used it correctly?
```

## 1. Confirm the source is ready

A source that is still processing, indexing, stale, or failed is not a reliable retrieval target.

## 2. Confirm context and ownership

Check that the query is running in a context allowed to access the source. A source in another personal project or restricted organization resource should not be returned merely because it is relevant.

## 3. Test a direct query

Ask for a distinctive phrase, heading, function name, or concept you know appears in the source. If even a direct query cannot retrieve it, focus on ingestion/indexing rather than prompt quality.

## 4. Inspect retrieval candidates

Where retrieval diagnostics are available, inspect whether the expected chunk appeared in candidate results and whether filtering or reranking removed it.

## 5. Check chunk boundaries

A source can be indexed while the important context is split across chunks in an unhelpful way. This is especially common with tables, code, or documents that have weak structural extraction.

## 6. Check context pressure

A request with many sources, tools, or a long conversation can have a tighter effective context budget. Relevant retrieved material can be limited to the highest-ranked candidates.

## 7. Separate retrieval failure from reasoning failure

If the correct source passage was included but the answer still misinterpreted it, the issue is model reasoning or prompt framing—not retrieval.

## Operator actions

Authorized operators can inspect indexing failures, chunk counts, embedding state, retrieval traces, reranking behavior, or worker health when those diagnostics are enabled.

<Warning>
  Do not weaken permissions to “test” retrieval in production. Use an authorized diagnostic context or a test resource with equivalent structure.
</Warning>