docs: add one-shot synthesis pattern and turn-cost pitfall
Teach the agent to keep intermediate retrieval inside the query script and return compact evidence in a single turn, instead of spending multiple conversation rounds showing raw results. Add the pattern to query-patterns.md and the rationale to pitfalls.md.
This commit is contained in:
@@ -107,6 +107,24 @@ sql(`
|
||||
`, '/absolute/path/to/file')
|
||||
```
|
||||
|
||||
## Conversation Turns Are Expensive
|
||||
|
||||
SQLite queries are cheap; repeated conversation turns are not. Every turn can
|
||||
write intermediate query output into conversation context and make later turns
|
||||
read it again.
|
||||
|
||||
For conclusion, broad history, failure investigation, or file evolution tasks,
|
||||
prefer one bounded query script that does the mechanical retrieval work inside
|
||||
the script:
|
||||
|
||||
1. locate candidates with `search()`, `summaries()`, or SQL;
|
||||
2. expand only selected hits with `context()`, `trace()`, or neighbor SQL;
|
||||
3. dedupe and group by `session_id`, facet, file, or tool;
|
||||
4. return compact evidence rows plus counts/limits.
|
||||
|
||||
Do not show every intermediate result to the conversation. Return the final
|
||||
compact evidence view, then use the model for the conclusion.
|
||||
|
||||
## Compact Vs Raw
|
||||
|
||||
Default to compact evidence. Raw/full access is a conscious escalation.
|
||||
|
||||
Reference in New Issue
Block a user