references/debugging-boundaries.md

# First failing boundary — diagnostic tree
1. Is the desired answer supported by source material? If not, handle as missing evidence/abstention.
2. Is the latest authorized document present in ingestion inventory? If not, check source connector, permission and crawl lag.
3. Did parser preserve passage/table/code? If not, fix extraction and reindex scoped documents.
4. Is expected chunk in current index with correct version/metadata? If not, inspect embedding, upsert and index aliases.
5. Was the needed chunk filtered by policy? If unauthorized, do **not** loosen filters. If policy bug, repair trusted authorization.
6. Did candidate retrieval surface chunk? Test raw search and query rewrite, exact terms and top-k.
7. Did reranking/context packing drop it? Compare IDs and token truncation.
8. If authorized evidence reached model, test prompt/model behavior, source precedence, conflict and abstention.
9. If correct answer but wrong citations, audit post-processing/source ID mapping.
10. Check test oracle/metric correctness before announcing improvement.

For each hypothesis: required evidence, confirm/falsify observation, test scope and rollback impact. Distinguish regression from long-standing error. Never presume access to production.