Merge branch 'developing' into dev

skills/autoload/onprem/rag-retrieve/hooks/retrieval-policy.md

@@ -37,26 +37,37 @@ Execute **sequentially, one at a time**. Do NOT run in parallel. Do NOT probe fi
 
 ## 4. Retrieval Breadth (`top_k`)
 
-- Apply `top_k` only to `rag_retrieve`. Use smallest sufficient value, expand if insufficient.
-- `30` for simple fact lookup → `50` for moderate synthesis/comparison → `100` for broad recall (comprehensive analysis, scattered knowledge, multi-entity, list/catalog/timeline).
-- Expansion order: `30 → 50 → 100`. If unsure, use `100`.
+- Apply `top_k` only to `rag_retrieve`. Choose the appropriate value upfront to maximize first-call success.
+- Use `50` for simple fact lookup or moderate synthesis, comparison, summarization, disambiguation.
+- Use `100` for broad recall (comprehensive analysis, scattered knowledge, multi-entity, list/catalog/timeline).
+- If unsure, use `50`. Only escalate to `100` on the retry call if first results are insufficient.
 
 ## 5. Result Evaluation
 
-Treat as insufficient if: empty, `Error:`, `no excel files found`, off-topic, missing core entity/scope, no usable evidence, partial coverage, or truncated results.
+**Maximum 3 retrieval calls per question.** After each call, evaluate immediately:
+
+### Sufficient — answer now
+- The core entity/topic in the user's question has been hit.
+- There is direct evidence supporting the main intent of the question.
+- Partial but usable coverage is sufficient — you do NOT need exhaustive or perfect coverage to answer.
+- **When results are sufficient, compose the answer immediately. Do NOT call retrieval again to "double-check" or "get more context".**
+
+### Insufficient — retry
+- Empty, `Error:`, `no excel files found`, off-topic, missing core entity/scope, no usable evidence at all.
 
 ## 6. Fallback and Sequential Retry
 
-On insufficient results, follow this sequence:
+On insufficient results, you may retry **up to 2 more times** (3 calls total):
 
-1. Rewrite query, retry same tool (once)
-2. Switch to next retrieval source in default order
-3. For `rag_retrieve`, expand `top_k`: `30 → 50 → 100`
-4. `table_rag_retrieve` insufficient → try `rag_retrieve`; `rag_retrieve` insufficient → try `table_rag_retrieve`
+1. Rewrite query, retry same tool.
+2. Switch to next retrieval source in default order.
+3. For `rag_retrieve`, escalate `top_k` to `100` on retry.
+4. `table_rag_retrieve` insufficient → try `rag_retrieve`; `rag_retrieve` insufficient → try `table_rag_retrieve`.
 
 - `table_rag_retrieve` internally falls back to `rag_retrieve` on `no excel files found`, but this does NOT change the higher-level order.
 - Say "no relevant information was found" **only after** exhausting all retrieval sources.
 - Do NOT switch to local filesystem inspection at any point.
+- Do NOT call any retrieval tool more than 3 times in total.
 
 ## 7. Table RAG Result Handling
 
@@ -99,7 +110,8 @@ This section applies only when self-knowledge is enabled.
 
 Before replying to a knowledge retrieval task, verify:
 - Used only whitelisted retrieval tools — no local filesystem inspection?
-- Exhausted retrieval flow before concluding "not found"?
+- Called retrieval at most 3 times total (not more)?
+- Answered immediately when results were sufficient (did NOT call again unnecessarily)?
 - Citations placed immediately after each relevant paragraph?
 - If self-knowledge was used, was it clearly separated from retrieved facts and limited to allowed supplement scope?
 

skills/autoload/support/rag-retrieve/hooks/retrieval-policy.md

@@ -37,26 +37,37 @@ Execute **sequentially, one at a time**. Do NOT run in parallel. Do NOT probe fi
 
 ## 4. Retrieval Breadth (`top_k`)
 
-- Apply `top_k` only to `rag_retrieve`. Use smallest sufficient value, expand if insufficient.
-- `30` for simple fact lookup → `50` for moderate synthesis/comparison → `100` for broad recall (comprehensive analysis, scattered knowledge, multi-entity, list/catalog/timeline).
-- Expansion order: `30 → 50 → 100`. If unsure, use `100`.
+- Apply `top_k` only to `rag_retrieve`. Choose the appropriate value upfront to maximize first-call success.
+- Use `50` for simple fact lookup or moderate synthesis, comparison, summarization, disambiguation.
+- Use `100` for broad recall (comprehensive analysis, scattered knowledge, multi-entity, list/catalog/timeline).
+- If unsure, use `50`. Only escalate to `100` on the retry call if first results are insufficient.
 
 ## 5. Result Evaluation
 
-Treat as insufficient if: empty, `Error:`, `no excel files found`, off-topic, missing core entity/scope, no usable evidence, partial coverage, or truncated results.
+**Maximum 3 retrieval calls per question.** After each call, evaluate immediately:
+
+### Sufficient — answer now
+- The core entity/topic in the user's question has been hit.
+- There is direct evidence supporting the main intent of the question.
+- Partial but usable coverage is sufficient — you do NOT need exhaustive or perfect coverage to answer.
+- **When results are sufficient, compose the answer immediately. Do NOT call retrieval again to "double-check" or "get more context".**
+
+### Insufficient — retry
+- Empty, `Error:`, `no excel files found`, off-topic, missing core entity/scope, no usable evidence at all.
 
 ## 6. Fallback and Sequential Retry
 
-On insufficient results, follow this sequence:
+On insufficient results, you may retry **up to 2 more times** (3 calls total):
 
-1. Rewrite query, retry same tool (once)
-2. Switch to next retrieval source in default order
-3. For `rag_retrieve`, expand `top_k`: `30 → 50 → 100`
-4. `table_rag_retrieve` insufficient → try `rag_retrieve`; `rag_retrieve` insufficient → try `table_rag_retrieve`
+1. Rewrite query, retry same tool.
+2. Switch to next retrieval source in default order.
+3. For `rag_retrieve`, escalate `top_k` to `100` on retry.
+4. `table_rag_retrieve` insufficient → try `rag_retrieve`; `rag_retrieve` insufficient → try `table_rag_retrieve`.
 
 - `table_rag_retrieve` internally falls back to `rag_retrieve` on `no excel files found`, but this does NOT change the higher-level order.
 - Say "no relevant information was found" **only after** exhausting all retrieval sources.
 - Do NOT switch to local filesystem inspection at any point.
+- Do NOT call any retrieval tool more than 3 times in total.
 
 ## 7. Table RAG Result Handling
 
@@ -99,7 +110,8 @@ This section applies only when self-knowledge is enabled.
 
 Before replying to a knowledge retrieval task, verify:
 - Used only whitelisted retrieval tools — no local filesystem inspection?
-- Exhausted retrieval flow before concluding "not found"?
+- Called retrieval at most 3 times total (not more)?
+- Answered immediately when results were sufficient (did NOT call again unnecessarily)?
 - Citations placed immediately after each relevant paragraph?
 - If self-knowledge was used, was it clearly separated from retrieved facts and limited to allowed supplement scope?
 

skills/onprem/rag-retrieve-only/hooks/retrieval-policy.md

@@ -35,24 +35,35 @@ Execute **sequentially, one at a time**. Do NOT run in parallel. Do NOT probe fi
 
 ## 4. Retrieval Breadth (`top_k`)
 
-- Apply `top_k` only to `rag_retrieve`. Use smallest sufficient value, expand if insufficient.
-- `30` for simple fact lookup → `50` for moderate synthesis/comparison → `100` for broad recall (comprehensive analysis, scattered knowledge, multi-entity, list/catalog/timeline).
-- Expansion order: `30 → 50 → 100`. If unsure, use `100`.
+- Apply `top_k` only to `rag_retrieve`. Choose the appropriate value upfront to maximize first-call success.
+- Use `50` for simple fact lookup or moderate synthesis, comparison, summarization, disambiguation.
+- Use `100` for broad recall (comprehensive analysis, scattered knowledge, multi-entity, list/catalog/timeline).
+- If unsure, use `50`. Only escalate to `100` on the retry call if first results are insufficient.
 
 ## 5. Result Evaluation
 
-Treat as insufficient if: empty, `Error:`, off-topic, missing core entity/scope, no usable evidence, partial coverage, or truncated results.
+**Maximum 3 retrieval calls per question.** After each call, evaluate immediately:
+
+### Sufficient — answer now
+- The core entity/topic in the user's question has been hit.
+- There is direct evidence supporting the main intent of the question.
+- Partial but usable coverage is sufficient — you do NOT need exhaustive or perfect coverage to answer.
+- **When results are sufficient, compose the answer immediately. Do NOT call retrieval again to "double-check" or "get more context".**
+
+### Insufficient — retry
+- Empty, `Error:`, off-topic, missing core entity/scope, no usable evidence at all.
 
 ## 6. Fallback and Sequential Retry
 
-On insufficient results, follow this sequence:
+On insufficient results, you may retry **up to 2 more times** (3 calls total):
 
-1. Rewrite query, retry same tool (once)
-2. Switch to next retrieval source in default order
-3. For `rag_retrieve`, expand `top_k`: `30 → 50 → 100`
+1. Rewrite query, retry same tool.
+2. Switch to next retrieval source in default order.
+3. For `rag_retrieve`, escalate `top_k` to `100` on retry.
 
 - Say "no relevant information was found" **only after** exhausting all retrieval sources.
 - Do NOT switch to local filesystem inspection at any point.
+- Do NOT call any retrieval tool more than 3 times in total.
 
 ## 7. Image Handling
 
@@ -89,7 +100,8 @@ This section applies only when self-knowledge is enabled.
 
 Before replying to a knowledge retrieval task, verify:
 - Used only whitelisted retrieval tools — no local filesystem inspection?
-- Exhausted retrieval flow before concluding "not found"?
+- Called retrieval at most 3 times total (not more)?
+- Answered immediately when results were sufficient (did NOT call again unnecessarily)?
 - Citations placed immediately after each relevant paragraph?
 - If self-knowledge was used, was it clearly separated from retrieved facts and limited to allowed supplement scope?
 

skills/support/rag-retrieve-only/hooks/retrieval-policy.md

@@ -35,24 +35,35 @@ Execute **sequentially, one at a time**. Do NOT run in parallel. Do NOT probe fi
 
 ## 4. Retrieval Breadth (`top_k`)
 
-- Apply `top_k` only to `rag_retrieve`. Use smallest sufficient value, expand if insufficient.
-- `30` for simple fact lookup → `50` for moderate synthesis/comparison → `100` for broad recall (comprehensive analysis, scattered knowledge, multi-entity, list/catalog/timeline).
-- Expansion order: `30 → 50 → 100`. If unsure, use `100`.
+- Apply `top_k` only to `rag_retrieve`. Choose the appropriate value upfront to maximize first-call success.
+- Use `50` for simple fact lookup or moderate synthesis, comparison, summarization, disambiguation.
+- Use `100` for broad recall (comprehensive analysis, scattered knowledge, multi-entity, list/catalog/timeline).
+- If unsure, use `50`. Only escalate to `100` on the retry call if first results are insufficient.
 
 ## 5. Result Evaluation
 
-Treat as insufficient if: empty, `Error:`, off-topic, missing core entity/scope, no usable evidence, partial coverage, or truncated results.
+**Maximum 3 retrieval calls per question.** After each call, evaluate immediately:
+
+### Sufficient — answer now
+- The core entity/topic in the user's question has been hit.
+- There is direct evidence supporting the main intent of the question.
+- Partial but usable coverage is sufficient — you do NOT need exhaustive or perfect coverage to answer.
+- **When results are sufficient, compose the answer immediately. Do NOT call retrieval again to "double-check" or "get more context".**
+
+### Insufficient — retry
+- Empty, `Error:`, off-topic, missing core entity/scope, no usable evidence at all.
 
 ## 6. Fallback and Sequential Retry
 
-On insufficient results, follow this sequence:
+On insufficient results, you may retry **up to 2 more times** (3 calls total):
 
-1. Rewrite query, retry same tool (once)
-2. Switch to next retrieval source in default order
-3. For `rag_retrieve`, expand `top_k`: `30 → 50 → 100`
+1. Rewrite query, retry same tool.
+2. Switch to next retrieval source in default order.
+3. For `rag_retrieve`, escalate `top_k` to `100` on retry.
 
 - Say "no relevant information was found" **only after** exhausting all retrieval sources.
 - Do NOT switch to local filesystem inspection at any point.
+- Do NOT call any retrieval tool more than 3 times in total.
 
 ## 7. Image Handling
 
@@ -89,7 +100,8 @@ This section applies only when self-knowledge is enabled.
 
 Before replying to a knowledge retrieval task, verify:
 - Used only whitelisted retrieval tools — no local filesystem inspection?
-- Exhausted retrieval flow before concluding "not found"?
+- Called retrieval at most 3 times total (not more)?
+- Answered immediately when results were sufficient (did NOT call again unnecessarily)?
 - Citations placed immediately after each relevant paragraph?
 - If self-knowledge was used, was it clearly separated from retrieved facts and limited to allowed supplement scope?