SuperBizAgent-java/openspec/changes/archive/2026-07-06-modular-rag-pipeline/specs/rag-knowledge-retrieval/spec.md

ADDED Requirements

Requirement: Knowledge retrieval SHALL use a modular RAG pipeline

The lookup_knowledge tool SHALL route each request through explicit query transformation, vector retrieval, post-retrieval processing, context packing, result assembly, and trace recording components.

Scenario: Pipeline components execute in order

• WHEN lookup_knowledge receives a query
• THEN the system SHALL transform the query before retrieval
• AND it SHALL retrieve vector candidates before post-processing
• AND it SHALL build evidence blocks before context packing
• AND it SHALL record trace details after result assembly

Scenario: Tool boundary remains explicit

• WHEN the modular pipeline is used
• THEN the Agent SHALL still call the explicit lookup_knowledge tool with the same query argument
• AND the implementation SHALL NOT require an implicit Advisor to inject knowledge into every chat response

Requirement: Knowledge retrieval SHALL retry without L0 filter when filtered L1 is low quality

The retrieval flow SHALL treat L0-derived category filtering as an optimization, not as a hard dependency for final recall.

Scenario: Filtered retrieval succeeds

• WHEN L0 provides an unambiguous category filter
• AND filtered L1 retrieval returns usable evidence at or above the configured reference threshold
• THEN the tool SHALL use the filtered L1 candidates without running an unfiltered retry

Scenario: Filtered retrieval returns no evidence

• WHEN L0 provides a category filter
• AND filtered L1 retrieval returns no candidates or no final evidence blocks
• THEN the tool SHALL retry L1 retrieval with the raw query and no L0-derived category filter
• AND the retrieval trace SHALL record fallback reason filtered_vector_no_evidence

Scenario: Filtered retrieval is below reference quality

• WHEN L0 provides a category filter
• AND filtered L1 retrieval returns candidates whose top normalized similarity is below the configured reference threshold
• THEN the tool SHALL retry L1 retrieval with the raw query and no L0-derived category filter
• AND the retrieval trace SHALL record fallback reason filtered_vector_low_quality

Scenario: Both retrieval attempts fail

• WHEN filtered L1 retrieval and unfiltered L1 retry both produce no usable evidence
• THEN the tool SHALL return found=false
• AND the tool SHALL set evidence status to no_evidence
• AND the tool SHALL NOT return L0 documents as fact evidence

Requirement: Knowledge retrieval SHALL return an evidence-first result contract

The lookup_knowledge result SHALL expose structured evidence and packed context as the preferred contract.

Scenario: Evidence result contains context and traces

• WHEN lookup_knowledge returns usable evidence
• THEN the result SHALL include evidenceBlocks
• AND it SHALL include contextPack
• AND it SHALL include retrievalTrace
• AND it SHALL include rerankTrace
• AND it SHALL include relevanceLevel and completenessHint

Scenario: No-evidence result keeps traceability

• WHEN lookup_knowledge returns no usable evidence
• THEN the result SHALL include found=false
• AND it SHALL include a message explaining that no knowledge evidence was found
• AND it SHALL include retrieval trace details for attempted retrieval paths

Requirement: Knowledge retrieval SHALL pack evidence context for Agent consumption

The post-retrieval flow SHALL convert final evidence blocks into a compact context package for the Agent.

Scenario: Context pack preserves source metadata

• WHEN evidence blocks are packed
• THEN the packed context SHALL preserve source, title when available, breadcrumb when available, and hit reasons for included evidence

Scenario: Context pack respects budget

• WHEN final evidence content exceeds the configured context budget
• THEN the packer SHALL truncate content rather than source metadata
• AND it SHALL record included and omitted sources in the context pack summary

Requirement: Knowledge retrieval SHALL rerank evidence with traceable rule signals

The post-retrieval flow SHALL rerank vector candidates using deterministic rule-based signals and expose the explanation.

Scenario: Rerank trace records score contributions

• WHEN candidates are reranked
• THEN the rerank trace SHALL record final rank, source, base retrieval score when available, and major boost reasons for top evidence blocks

Scenario: Query hints influence rerank without becoming evidence

• WHEN L0 query hints match candidate metadata or content
• THEN the reranker MAY boost the candidate
• AND the evidence block SHALL record the hint as a hit reason
• AND the system SHALL NOT treat the L0 hint itself as fact evidence

MODIFIED Requirements

Requirement: Knowledge retrieval SHALL keep L0 as a hint provider

The lookup_knowledge retrieval flow SHALL retain L0 keyword/frontmatter matching but use it only as query understanding, filtering, rerank, and explainability hint data rather than as a final evidence retrieval decision.

Scenario: L0 produces traceable hint data

• WHEN L0 matches one or more indexed knowledge entries
• THEN the retrieval flow SHALL expose matched titles, matched keywords, domains or categories, and entity terms as structured hint data

Scenario: L0 does not bypass semantic retrieval

• WHEN L0 returns exactly one match
• THEN the retrieval flow SHALL still attempt semantic L1 retrieval unless L1 is explicitly disabled by configuration

Scenario: L0 hints do not become normal evidence

• WHEN L1 retrieval returns no usable evidence
• THEN L0 matched documents SHALL NOT be returned as fact evidence blocks
• AND L0 hint data MAY still be recorded in retrieval trace details

Requirement: Knowledge retrieval SHALL return structured evidence blocks

The lookup_knowledge retrieval flow SHALL expose retrieved evidence as structured evidence blocks.

Scenario: Evidence block contains source metadata

• WHEN a lookup_knowledge call returns evidence
• THEN each evidence block SHALL include source, title when available, breadcrumb when available, retrieval layer, content, and hit reasons

Scenario: Evidence blocks are the primary evidence contract

• WHEN evidence blocks are returned
• THEN Agent-facing knowledge content SHALL be derived from evidence blocks and context pack
• AND the result SHALL NOT rely on legacy primary or supplement fields for L0/L1 meaning

REMOVED Requirements

Requirement: Knowledge retrieval SHALL preserve fallback evidence

Reason: The new MVP fallback strategy retries unfiltered L1 retrieval when L0-derived filtering appears to suppress usable semantic evidence. Returning L0 documents as fallback fact evidence can let keyword hints masquerade as verified knowledge.

Migration: Use the new requirement "Knowledge retrieval SHALL retry without L0 filter when filtered L1 is low quality". If filtered and unfiltered L1 both fail, return no_evidence while preserving L0 hint data in trace details only.