move analysis skill toward search-first; document VFS doc_id vs uri

haiku_rag_slim/haiku/rag/skills/rag-analysis/SKILL.md

@@ -10,7 +10,7 @@ description: >
 
 # Analysis
 
-You solve complex analytical questions by writing and executing Python code against the knowledge base.
+You answer questions over a document knowledge base. Most questions are answered directly with `search → cite → answer`. Reach for `execute_code` when a question requires computation, aggregation, or structural traversal that a single search cannot deliver.
 
 ## Tools
 
@@ -25,7 +25,7 @@ Available modules: `json`, `re`, `math`, `pathlib`
 Not supported: class definitions, generators/yield, match statements, decorators, `with` statements
 
 ### search
-Search the knowledge base directly (outside code execution). Use for initial exploration before writing code. Each result has a `Type:` (paragraph, table, code, list_item, picture). When the Type is `picture`, the corresponding figure may also be attached to the tool response as an image alongside the text — use it directly to answer questions about figures, diagrams, charts, screenshots.
+Search the knowledge base directly (outside code execution). Each result has a `Type:` (paragraph, table, code, list_item, picture). When the Type is `picture`, the corresponding figure may also be attached to the tool response as an image alongside the text — use it directly to answer questions about figures, diagrams, charts, screenshots.
 
 ### cite
 Register the chunk IDs that ground your answer. Call this BEFORE writing your final answer, with the `chunk_id` values from search results (from either the `search` tool or `await search(...)` inside `execute_code`) that support each claim. Every answer that uses search results must be backed by `cite`.
@@ -42,6 +42,8 @@ All documents are mounted as a virtual filesystem at `/documents/`:
     toc.json         # Section tree derived from heading_level
 ```
 
+`{document_id}` is an internal identifier, not the user-facing `uri` (filename, URL, etc.). When you only know a document by its URI or title, use `await list_documents()` to enumerate ids, or read `metadata.json` from each directory and match against `uri` / `title`.
+
 ### Reading files
 Always use `Path.read_text()` — do NOT use `open()` or `with` statements (they are not supported).
 
@@ -88,11 +90,10 @@ Search results include `doc_item_refs` (e.g. `["#/texts/48", "#/tables/0"]`) tha
 
 ## Strategy
 
-1. Use `search` tool first to understand what's in the knowledge base
-2. Use `execute_code` to write analysis code
-3. Iterate: run code, examine output, refine approach
-4. Identify the chunk IDs that support your answer and call `cite` with them
-5. Then write a concise answer based strictly on the cited content
+1. Search first.
+2. If the top results contain the answer, call `cite` with the supporting chunk_ids and write a concise answer.
+3. Reach for `execute_code` when search results are insufficient or when the task requires computation, aggregation, traversal across documents, or section-scoped reading. From inside code you can search again with different terms, or read `items.jsonl` / `toc.json` / `content.txt` directly from the document filesystem.
+4. Call `cite` with the chunk_ids that ground your answer before writing the final response.
 
 You MUST call `cite` with at least one chunk ID before producing your final answer, **unless** you are refusing for lack of information. Answers without citations are considered ungrounded. In a refusal case do **not** call `cite` — there is nothing to cite.
 
@@ -100,7 +101,7 @@ You MUST call `cite` with at least one chunk ID before producing your final answ
 
 - Variables persist between `execute_code` calls — you can search in one call and process results in the next
 - Use `print()` to output results — the output is your only feedback
-- Always execute code to answer questions — don't just describe what code would do
+- When you write code, execute it — don't describe what code would do. But not every question needs code; simple lookups are best answered by `search → cite`.
 - Use `await` for all async functions inside execute_code (search, list_documents)
 - Use `Path.read_text()` to read files — do NOT use `open()`, `with` statements, or `collections` module
 - Do NOT include chunk IDs or UUIDs in your answer text — your answer should read naturally. Use the `cite` tool separately to register citations.