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
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.
Do not weaken permissions to “test” retrieval in production. Use an authorized diagnostic context or a test resource with equivalent structure.
