ADR-006: Level-1 Deterministic Retrieval
- Status: Accepted
- Date: 2026-08-12
Context & Problem Statement
Vector databases with embedding pipelines (RAG) are frequently introduced into documentation projects prematurely. For moderate corpus sizes (fewer than 1,500 documents), embedding stores introduce non-deterministic retrieval, external SaaS dependencies, embedding version mismatches, and re-indexing lag.
Decision
Adopt Level-1 Deterministic Retrieval:
- Assemble context strictly from:
- Files explicitly targeted by the generation invocation.
- Frontmatter dependency closure (
sourcesrepo paths +relateddocument IDs, 1 hop). - Stable keyword scanning over canonical files with deterministic tie-breaking.
- Impose strict context token budgeting.
- Only escalate to Level 2 (full-text index) or Level 3 (embeddings) if the canonical corpus exceeds ~1,500 pages or measured grounding failures demonstrate that keyword/closure retrieval is insufficient.