diff --git a/SKILL.md b/SKILL.md index 524a270..93bf602 100644 --- a/SKILL.md +++ b/SKILL.md @@ -44,12 +44,13 @@ Custom query: The query file runs inside `(async () => { ... })()`. Use `return` to emit JSON. -## Reference Triggers +## Query Routing -Use progressive disclosure, but do not guess. +Before writing a query, classify the task. Progressive disclosure is useful, but +skipping the relevant reference usually costs extra query rounds. -- Read `references/schema.md` before raw `sql()` unless the needed table/column relationship is already explicit here. -- Read `references/query-patterns.md` for one-shot synthesis retrieval, workflow trees, failed tool counts or failure groups, broad development-history synthesis, file history synthesis, summary neighbors, subagent recall, raw windows, and empty-result handling. +- Read `references/schema.md` before raw `sql()` unless the needed table/column relationship is already explicit here. Do this before running the SQL, not after a missing-column error. +- Read `references/query-patterns.md` before broad "how did X evolve / what did we do / what problems happened / what was the conclusion" synthesis, and for one-shot synthesis retrieval, workflow trees, failed tool counts or failure groups, file history synthesis, summary neighbors, subagent recall, raw windows, and empty-result handling. - Read `references/pitfalls.md` when a scoped result is empty or tiny, when a query may over-fetch, when a term is hyphenated, when project scope is ambiguous, or when helper row fields are unclear. If a helper row shape is unclear, first run a tiny scoped query and return @@ -140,7 +141,7 @@ Keep queries scoped, bounded, and structural. - For conclusion, broad history, failure investigation, or file evolution questions, prefer one bounded query script that locates, expands, dedupes, groups, and returns compact evidence rows. Do not spend multiple conversation turns showing intermediate query results. - Return compact evidence with stable IDs (`session_id`, `uuid`, `tool_call_id`, `run_id`, `agent_id`) and short snippets. - Avoid `thread()` unless the user explicitly asks for a full transcript or all smaller probes are insufficient. -- Keep runtime JSON small. Do not return all sessions, all summaries, all tool calls, complete workflow trees, full raw messages, or whole tool results. +- Keep runtime JSON small, ideally under 10k-12k chars for synthesis tasks. Do not return all sessions, all summaries, all tool calls, complete workflow trees, full raw messages, or whole tool results. - When counting or aggregating, compute counts in SQL or in the query script and return those counts. Do not hand-count from long rows in prose. - For recent failures or "which tasks failed" questions, aggregate by session/task and return counts plus sparse examples. Do not return raw failure rows. - For broad "how did X evolve / what did we do / what problems happened" history synthesis, use a bounded facet sweep from `references/query-patterns.md`. For concept recall, session lookup, or exact term recall, keep compact `search()` first. diff --git a/references/pitfalls.md b/references/pitfalls.md index f4ed1db..51e43cf 100644 --- a/references/pitfalls.md +++ b/references/pitfalls.md @@ -139,6 +139,7 @@ Default to compact evidence. Raw/full access is a conscious escalation. Common wrong guesses: - Summaries: use `source` and `content`; do not use `summary_type` or `text`. +- Tool call name: use `tool_calls.name`. `tool_name` is only a safe alias in `SELECT tc.name AS tool_name`; `tc.tool_name` is not a table column. - Tool result timestamps: `tool_results` has no timestamp. Join `messages`. - Tool call timestamps: `tool_calls` has no timestamp. Join `messages`. - Workflow agent message counts: `workflowTree()` returns `messageCount` for agents. diff --git a/references/query-patterns.md b/references/query-patterns.md index c8871bc..206def3 100644 --- a/references/query-patterns.md +++ b/references/query-patterns.md @@ -32,7 +32,8 @@ Use this for conclusion, broad history, failure investigation, or file evolution questions. The goal is to reduce conversation turns: keep intermediate search results inside the query script, then return only a compact task-local evidence view. This does not create stored semantic entities; the agent still reads the -evidence and forms the conclusion. +evidence and forms the conclusion. Expect 1-2 runtime queries: one broad compact +evidence pass, and optionally one targeted detail pass by stable IDs. ```js const project = '%quiet-zero%';