FAQ Short-circuit

The FAQ cache returns an SME-vetted answer for a known question, bypassing the LLM, the fact store, and the retriever entirely. It is a latency and cost optimization — and a high-risk layer, because it sits in front of the anti-fabrication guard. A wrong short-circuit would skip every downstream safety check.

Where it sits

In the /v1/ask route (service/api/routes.py), the FAQ lookup runs first:

# 1) FAQ short-circuit — on hit, never touches provider / fact store / retriever
hit = faq_cache.lookup(req.question, reference_date=ref)
if hit is not None:
    return AskResponse(..., route="faq", answer=hit.answer, sources=[...])

# 2) miss -> normal workflow (anti-fabrication guard, dual channel, ...)
result = answer_question(req.question, store, provider, ...)

lookup is a pure function (service/faq/faq_cache.py): it consults parse_intent / clarify_scope for boundary decisions but never reaches the LLM, fact store, or retriever. Matching is normalized exact / alias match only (NFKC + casefold + whitespace fold + trailing-punctuation strip) — no fuzzy or embedding matching.

The conservative exclusions

lookup returns a miss (None) if any of these hold — the exclusions are checked before the cache index is consulted:

An FAQ item

Items are SME-vetted and version-tracked; the hit carries its own provenance (FAQHit.source):

{
  "id": "what-is-ragspine",
  "question": "RAGSpine 是什么？",
  "aliases": ["What is RAGSpine?"],
  "answer": "RAGSpine 是一个无框架的后端 RAG 引擎……",
  "source": "internal/faq-handbook.md",
  "version": 3,
  "enabled": true,
  "valid_from": "2026-01-01",
  "valid_until": null,
  "sensitivity": "INTERNAL"
}