clarify domain_preamble purpose

CHANGELOG.md

@@ -4,6 +4,11 @@
 ### Fixed
 
 - **Citation formatting**: Replace raw UUIDs (`[doc_id:chunk_id]`) with human-readable identifiers (`[index] title`) in `format_citations()` output, preventing LLMs from hallucinating opaque ID markers in answers
+- **domain_preamble propagation**: `domain_preamble` now flows to skill subagents and the main agent preamble, not just internal agents (QA, research). Fixes ambiguous queries failing when domain context was needed.
+
+### Changed
+
+- **domain_preamble docs**: Clarified that `domain_preamble` is for domain context (subject matter, terminology), not behavioral instructions (tone, response style).
 
 ## [0.36.2] - 2026-03-28
 

docs/configuration/prompts.md

@@ -6,10 +6,11 @@ Customize the prompts used by haiku.rag's AI agents to better match your domain
 
 ```yaml
 prompts:
-  # Prepended to all agent prompts
+  # Domain context prepended to all agent prompts
   domain_preamble: |
-    You are answering questions about our internal documentation.
-    Technical terms like "time travel" refer to database versioning features.
+    This knowledge base contains technical documentation for the Helios solar panel
+    system, including installation manuals, maintenance procedures, and safety guidelines.
+    Questions about "the system" or unqualified specs refer to the Helios panel.
 
   # Full replacement for QA agent prompt (optional)
   qa: null
@@ -23,20 +24,22 @@ prompts:
 
 ## Domain Preamble
 
-The `domain_preamble` field is prepended to **all** agent prompts (QA, research planning, search, evaluation, and synthesis). Use this to:
+The `domain_preamble` field provides **domain context** that is prepended to all agent prompts — the main agent, skill subagents, and internal agents (QA, research planning, search, evaluation, and synthesis). Use this to:
 
-- Add domain context that clarifies terminology
-- Set the tone or personality of responses
-- Specify what the knowledge base contains
+- Describe what the knowledge base contains
+- Clarify domain-specific terminology
+- Provide context that helps agents interpret ambiguous queries
+
+**Important:** `domain_preamble` is for domain context, not behavioral instructions. Descriptions of subject matter, terminology, and content scope belong here. Behavioral guidance (tone, response style, formatting rules) belongs in the agent's system prompt or custom `prompts.qa`.
 
 **Example:**
 
 ```yaml
 prompts:
   domain_preamble: |
-    You are a technical support assistant for Acme Corp products.
-    The knowledge base contains product documentation, FAQs, and troubleshooting guides.
-    Always be helpful and professional.
+    This knowledge base contains product documentation, API references,
+    and troubleshooting guides for Acme Corp's cloud platform.
+    "Deployment" refers to Acme's managed deployment service, not general CI/CD.
 ```
 
 ## Custom QA Prompt
@@ -126,7 +129,7 @@ from haiku.rag.config.models import PromptsConfig
 
 config = AppConfig(
     prompts=PromptsConfig(
-        domain_preamble="You are answering questions about our product documentation.",
+        domain_preamble="This knowledge base contains Acme Corp product documentation and API references.",
         qa=None,  # Use default QA prompt
         synthesis=None,  # Use default synthesis prompt
         picture_description="Describe this image for search indexing.",

docs/tuning.md

@@ -32,7 +32,7 @@ When configured, a cross-encoder reranker re-scores 10x the requested candidates
 
 Model and temperature selection affect answer quality directly — see [Providers](configuration/providers.md#model-settings) for options.
 
-`domain_preamble` prepends domain context to all agent prompts. Use it to clarify terminology, set tone, or describe what the knowledge base contains. For full prompt replacement, set `prompts.qa` directly. See [Prompt Customization](configuration/prompts.md).
+`domain_preamble` prepends domain context to all agent prompts — including the main agent, skill subagents, and internal agents (QA, research). Use it to describe what the knowledge base contains and clarify domain-specific terminology. For full prompt replacement, set `prompts.qa` directly. See [Prompt Customization](configuration/prompts.md).
 
 For automated prompt optimization, see [Prompt Optimization (GEPA)](#prompt-optimization-gepa) below.
 

tests/skills/test_rag.py

@@ -66,12 +66,12 @@ class TestGetAgentPreamble:
 
         config = AppConfig(
             prompts=PromptsConfig(
-                domain_preamble="This knowledge base contains C-146 aircraft documents."
+                domain_preamble="This knowledge base contains Helios solar panel documentation."
             )
         )
         result = get_agent_preamble(config)
         assert result.startswith(
-            "This knowledge base contains C-146 aircraft documents."
+            "This knowledge base contains Helios solar panel documentation."
         )
         assert AGENT_PREAMBLE in result
 
@@ -89,13 +89,13 @@ class TestDomainPreambleInSkillInstructions:
 
         config = AppConfig(
             prompts=PromptsConfig(
-                domain_preamble="This knowledge base contains C-146 aircraft documents."
+                domain_preamble="This knowledge base contains Helios solar panel documentation."
             )
         )
         skill = create_skill(config=config, db_path=temp_db_path)
         assert skill.instructions is not None
         assert skill.instructions.startswith(
-            "This knowledge base contains C-146 aircraft documents."
+            "This knowledge base contains Helios solar panel documentation."
         )
         base_instructions = instructions()
         assert base_instructions is not None

tests/skills/test_rlm.py

@@ -105,13 +105,13 @@ class TestDomainPreambleInRLMSkillInstructions:
 
         config = AppConfig(
             prompts=PromptsConfig(
-                domain_preamble="This knowledge base contains C-146 aircraft documents."
+                domain_preamble="This knowledge base contains Helios solar panel documentation."
             )
         )
         skill = create_skill(config=config, db_path=temp_db_path)
         assert skill.instructions is not None
         assert skill.instructions.startswith(
-            "This knowledge base contains C-146 aircraft documents."
+            "This knowledge base contains Helios solar panel documentation."
         )
         base_instructions = instructions()
         assert base_instructions is not None