---
decision_id: decision-hybrid-retrieval-report
decision_status: accepted
decision_scope: hybrid-retrieval
decision_owner: agentops
decision_date: 2026-05-04
source_refs: docs/architecture/hybrid-retrieval-adr.md, docs/evals/hybrid-retrieval-candidate-comparison-poc.md, docs/evals/results/ockp-hybrid-retrieval-candidate-comparison.md
---

# Hybrid Retrieval Promotion Decision

## Decision

Accept `hybrid_retrieval_report` as a promoted read-only action under
`openclerk retrieval`.

The action packages current lexical baseline evidence and candidate-surface
guidance for hybrid/vector retrieval decisions. It does not promote durable
vector storage, external vector databases, OpenAI vector stores, live embedding
API calls, memory writes, or default ranking changes.

Required references:

- docs/architecture/agent-knowledge-plane.md
- https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f#file-llm-wiki-md
- https://mitchellh.com/writing/building-block-economy
- https://developers.openai.com/api/docs/guides/prompt-guidance
- https://openai.com/index/harness-engineering/
- https://developers.openai.com/api/docs/guides/embeddings
- https://developers.openai.com/api/docs/guides/retrieval
- https://docs.mem0.ai/open-source/overview

## Safety Pass

Pass. The implementation stays local-first and runner-only, performs no
durable writes, and rejects missing query input before any retrieval work.
Validation boundaries explicitly forbid direct SQLite, raw vault/file
inspection, source-built runners, HTTP/MCP bypasses, embeddings, vector stores,
and default ranking changes.

## Capability Pass

Pass for decision support. The report returns:

- `query`
- optional `path_prefix`
- `lexical_search`
- `candidate_surfaces`
- `recommendation`
- `safety_pass`
- `capability_pass`
- `ux_quality`
- `performance_posture`
- `evidence_posture`
- `validation_boundaries`
- `authority_limits`
- `evidence_inspected`
- `agent_handoff`

## UX Quality

Pass. The report replaces repeated baseline search plus architecture-policy
recitation with one natural retrieval action. Ordinary source-grounded
retrieval remains plain `search`, so the user-facing surface stays simple.

## Conditional Implementation

Implemented:

- runner JSON action `hybrid_retrieval_report`
- request object `hybrid_retrieval`
- read-only execution path
- result schema and `agent_handoff`
- CLI help text
- skill action index
- README workflow-action summary
- unit coverage for read-only behavior and missing-query rejection

No schema, projection, or storage changes were required because the selected
surface does not store embeddings or vectors.

## Iteration Gate

Before promoting durable hybrid ranking, file or execute follow-up work that
compares local vector storage, hosted vector stores, OpenAI vector stores, and
lexical-only FTS on recall, citation correctness, provenance, freshness,
import cost, reopen cost, and 100 MB/1 GB behavior.

## Follow-up Work

Search performed before close:

- `follow-up search "durable vector retrieval"`: no separate existing work item found.
- `follow-up search "hybrid vector retrieval follow-up"`: no separate existing work item
  found.

Created by this decision: none. This decision promotes the read-only report and
does not assert that durable hybrid/vector retrieval is validated by the
pre-POC lexical scale evidence alone.

Linked existing:

- `oc-tnnw.1.5` for conditional implementation verification of the promoted
  read-only report.
- `oc-tnnw.1.6` for the final iteration/follow-up check before parent closure.
- `oc-9ijx` for the later semantic-recall implementation candidate comparison
  after `oc-rlg7` and `oc-ye6w` found a real paraphrase/synonym recall gap.
