SuperBizAgent-java/openspec/specs/rag-knowledge-retrieval/spec.md

rag-knowledge-retrieval Specification

Purpose

Define the runtime contract for the explicit lookup_knowledge Agent tool, including how L0 keyword/frontmatter hints cooperate with L1 semantic retrieval while preserving metadata filters, fallback evidence, and traceable retrieval details.

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 as domain, entity, and explainability hint data rather than as the sole final 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 by default

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

Requirement: Knowledge retrieval SHALL use L0 domain as optional L1 filter

The retrieval flow SHALL use L0 domain/category information as an optional metadata filter for L1 retrieval when the domain is unambiguous.

Scenario: Single domain filter

• WHEN L0 hint data contains exactly one nonblank domain or category
• THEN the L1 retrieval request SHALL include that category as a metadata filter

Scenario: Ambiguous domain fallback

• WHEN L0 hint data contains zero domains or multiple domains
• THEN the L1 retrieval request SHALL run without an L0-derived category filter

Requirement: Knowledge retrieval SHALL preserve fallback evidence

The retrieval flow SHALL still return useful L0 evidence when L1 produces no usable result.

Scenario: L1 has no results

• WHEN L0 has at least one match and L1 returns no candidates
• THEN the tool SHALL return an L0-based primary result
• AND the relevance assessment SHALL not claim semantic support from L1

Scenario: L1 fails

• WHEN L0 has at least one match and L1 retrieval throws or fails
• THEN the tool SHALL return an L0-based primary result
• AND the tool invocation record SHALL preserve the L0 hint details

Requirement: Knowledge retrieval SHALL persist L0 hints

The system SHALL persist L0 hint details in tool_invocation.retrieval_details for lookup_knowledge calls.

Scenario: Retrieval details include L0 hints

• WHEN a lookup_knowledge call records a tool invocation
• THEN retrieval_details SHALL include L0 matched keywords, domains, entities, and titles when available

Scenario: Retrieval layer reflects cooperating retrieval

• WHEN both L0 hint data and L1 candidates participate in a lookup
• THEN the recorded retrieval layer SHALL be L0+L1

Requirement: Knowledge retrieval SHALL return structured evidence blocks

The lookup_knowledge retrieval flow SHALL expose retrieved evidence as structured evidence blocks in addition to the existing compatibility fields.

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: Compatibility fields remain available

• WHEN evidence blocks are returned
• THEN the existing primary and supplement result fields SHALL remain available when their source evidence exists

Requirement: Knowledge retrieval SHALL deduplicate evidence blocks

The retrieval flow SHALL remove duplicate evidence blocks before returning them to the Agent.

Scenario: Duplicate source deduplication

• WHEN L0 and L1 produce evidence with the same source identity
• THEN the retrieval flow SHALL keep a single evidence block for that source
• AND the evidence block SHALL preserve hit reasons from both retrieval paths when available

Scenario: Postprocess count tracking

• WHEN evidence post-processing completes
• THEN the tool invocation details SHALL record candidate count and final evidence block count

Requirement: Knowledge retrieval SHALL persist evidence block summaries

The system SHALL persist compact evidence block summaries in tool_invocation.retrieval_details.

Scenario: Evidence summaries are persisted

• WHEN a lookup_knowledge call records a tool invocation
• THEN retrieval_details SHALL include evidence block summaries containing source, title, retrieval layer, score when available, and hit reasons

Scenario: Full content is not duplicated into retrieval details

• WHEN evidence block summaries are persisted
• THEN full evidence content SHALL be omitted or truncated so the trace record remains compact