SuperBizAgent-java/openspec/changes/archive/2026-07-06-live-diagnosis-skill-observability/specs/rag-knowledge-retrieval/spec.md

ADDED Requirements

Requirement: Lookup knowledge SHALL persist modular RAG trace details

The lookup_knowledge tool SHALL persist modular RAG pipeline details in tool_invocation.retrieval_details for every new lookup invocation.

Scenario: Evidence lookup persists modular detail keys

• WHEN lookup_knowledge returns usable evidence
• THEN retrieval_details SHALL include query_transform
• AND it SHALL include retrieval_trace
• AND it SHALL include context_pack_summary
• AND it SHALL include rerank_trace
• AND it SHALL include evidence_blocks

Scenario: Fallback lookup persists fallback reason

• WHEN lookup_knowledge performs an unfiltered retry after filtered retrieval fails or is low quality
• THEN retrieval_details.retrieval_trace SHALL include the selected attempt
• AND retrieval_details.fallback_reason SHALL preserve the fallback reason

Scenario: No-evidence lookup still preserves trace

• WHEN lookup_knowledge returns no usable evidence
• THEN retrieval_details SHALL still include retrieval trace information for attempted retrieval paths
• AND it SHALL not include full evidence content as duplicated trace data