docs: establish helper-first retrieval as default entry point
Make overview() + memories() + search() the standard first pass for broad retrieval tasks, with sql() positioned as an escalation path for exact joins/aggregations. Add a Default First Pass section to SKILL.md, a copyable first-pass pattern to query-patterns.md, and update retrieval-semantics.md to reinforce the helper-before-sql principle.
This commit is contained in:
@@ -4,6 +4,67 @@ These are copyable CodeAct patterns for `runtime.mjs --query` scripts, plus one
|
||||
`--remember` registration pattern. They are not new APIs. Adapt them to the
|
||||
user's scope and return compact evidence.
|
||||
|
||||
Read this before the first query for broad synthesis, progress summaries,
|
||||
design history, weekly/monthly reviews, or questions that ask what the user did,
|
||||
learned, decided, tried, or abandoned. Start with a helper-first pass; use raw
|
||||
`sql()` only when the helper surface cannot express the needed join or
|
||||
aggregation.
|
||||
|
||||
## First Pass: Overview + Recall + Evidence
|
||||
|
||||
Use this for broad synthesis before writing custom SQL. It gives the agent a
|
||||
map, prior notes, and raw session evidence in one bounded result. Then run a
|
||||
faceted detail pass if the first pass reveals useful projects, sessions, files,
|
||||
or terms.
|
||||
|
||||
```js
|
||||
const topic = 'topic terms from the user request';
|
||||
const map = overview({ limit: 6 });
|
||||
const project = map.current.project?.project;
|
||||
const scoped = project ? { project } : {};
|
||||
|
||||
return {
|
||||
query_plan: {
|
||||
mode: 'first_pass',
|
||||
topic,
|
||||
project: project || null,
|
||||
limits: { sessions: 6, memories: 5, search: 8 },
|
||||
},
|
||||
orientation: map.current_project && {
|
||||
project: map.current_project.project,
|
||||
session_total: map.current_project.session_total,
|
||||
sessions: map.current_project.sessions.map(s => ({
|
||||
id: s.id,
|
||||
title: s.title,
|
||||
branch: s.git_branch,
|
||||
ended_at: s.ended_at,
|
||||
})),
|
||||
memory_total: map.current_project.memory_total,
|
||||
memories: map.current_project.memories.map(m => ({
|
||||
id: m.id,
|
||||
path: m.path,
|
||||
summary: m.summary?.slice(0, 240),
|
||||
})),
|
||||
},
|
||||
prior_memories: memories({ ...scoped, query: topic, limit: 5 }).map(m => ({
|
||||
id: m.id,
|
||||
path: m.path,
|
||||
session_id: m.session_id,
|
||||
created_at: m.created_at,
|
||||
summary: m.summary?.slice(0, 260),
|
||||
})),
|
||||
session_evidence: search(topic.replace(/[-_]/g, ' '), { ...scoped, limit: 8 })
|
||||
.slice(0, 6)
|
||||
.map(h => ({
|
||||
session_id: h.session.id,
|
||||
session_title: h.session.title,
|
||||
uuid: h.message.uuid,
|
||||
timestamp: h.message.timestamp,
|
||||
snippet: h.message.text?.slice(0, 220),
|
||||
})),
|
||||
};
|
||||
```
|
||||
|
||||
## Orient Before Retrieval
|
||||
|
||||
Use `overview()` when the current project or available scopes are unclear. Treat
|
||||
|
||||
@@ -21,6 +21,11 @@ project counts, and recent current-project session/memory entry points. Use it
|
||||
when scope is unclear, then query the memory or raw session layer for evidence.
|
||||
It does not guess the current session.
|
||||
|
||||
For a new task, the first pass normally starts with `overview({ limit: 6 })`
|
||||
unless the user gave an exact session ID, message UUID, or absolute file path.
|
||||
Broad synthesis and progress-summary tasks should start from
|
||||
`references/query-patterns.md`, not raw SQL.
|
||||
|
||||
One-shot retrieval is not all-shot retrieval. A query script may perform
|
||||
multiple steps, but the first locator should be the narrowest semantic fit. If a
|
||||
scope locator finds the relevant project/session/file, do not also run broad FTS
|
||||
@@ -34,9 +39,11 @@ Project-like fields are distinct:
|
||||
- `messages.cwd`: working directory at message time.
|
||||
- helper `project`: SQL `LIKE` over `sessions.project`, not exact membership.
|
||||
|
||||
For exact project membership, use `sql()` with `s.project = ?` or
|
||||
`s.project_path = ?`. Empty or tiny scoped results are valid results; do not
|
||||
broaden unless the user asks or your `query_plan` explicitly marks a fallback.
|
||||
For exact project membership, prefer helper filters or a scoped first pass when
|
||||
they are expressive enough; use `sql()` with `s.project = ?` or
|
||||
`s.project_path = ?` when you need exact membership across a join or
|
||||
aggregation. Empty or tiny scoped results are valid results; do not broaden
|
||||
unless the user asks or your `query_plan` explicitly marks a fallback.
|
||||
|
||||
### Plan Before Probe
|
||||
|
||||
@@ -58,7 +65,9 @@ If vocabulary is still unclear, use a small filtered window and say so in
|
||||
|
||||
### Structure Before Text
|
||||
|
||||
Use the database shape before asking the model to read text.
|
||||
Use the database shape before asking the model to read text. This means
|
||||
structured helpers and compact JS shaping first; raw SQL only when it expresses
|
||||
the needed join, grouping, or exact schema-level check better than helpers.
|
||||
|
||||
- Count and aggregate in SQL or JS (`GROUP BY`, `COUNT`, `MAX`, `ORDER BY`, `LIMIT`).
|
||||
- Join metadata from the owner table instead of inventing fields.
|
||||
|
||||
Reference in New Issue
Block a user