ADR 0020: Progressive deep search¶
Status¶
Accepted. The effort ladder is implemented.
Context¶
Prompt history is cheap to search but does not contain every conversation record. Opening every transcript for every request is complete but costs more I/O and parsing than a prompt-only question needs. The public request must make that trade-off explicit without turning scope, result limits, and routing into competing depth controls.
Decision¶
Search effort is an engine-owned, ordered read policy with three values:
promptdiscovers and reads only prompt-history sources. It does not open conversation bodies.targetedsearches prompt evidence, then uses the fixed routing decision in ADR 0021 to add selected conversations. It is approximate because candidate selection can omit a conversation.exhaustivediscovers and reads every eligible conversation source admitted by the normalized scope and source predicates.
The CLI normalizes --deep to targeted and --exhaustive to exhaustive;
a bare CLI --exhaustive retains prompt scope. A bare CLI --deep (or an
inline depth:targeted query term with no explicit scope) instead widens an
implicit prompts scope to all, since targeted effort has nothing to read
otherwise. MCP exposes the same prompt, targeted, and exhaustive
vocabulary, but an omitted scope with targeted or exhaustive effort infers
all; an explicitly supplied scope="prompts" remains invalid for targeted
effort. scope controls record kinds, while effort controls how broadly
the engine reads sources, and neither is a result limit.
A depth/effort query-language field (ADR 0006 owns its field shape and collision
rules) reaches this same ladder as literal query text, normalized through the
one resolver every frontend shares rather than a per-frontend copy of the
scope/effort reconciliation this ADR describes.
Each effort uses the same matcher, declared order, dedupe policy, and result
limit. The result summary reports requested and completed effort, status,
coverage, diagnostics, and engine-authored escalation actions. A targeted
summary reports approximate with the candidate-selection condition unless a
higher-precedence failure, cancellation, or truncation condition applies.
Consequences¶
Readers can begin with prompt history and explicitly spend more I/O only when their question warrants it. An empty result remains interpretable: the summary distinguishes no prompt match, no candidate conversation, no match in selected conversations, and no exhaustive match. Frontends must use that engine-owned evidence and next actions rather than infer coverage from an empty result list.
This ADR owns effort semantics and normalization. ADR 0021 owns targeted candidate selection. ADR 0014 owns ordering and result limits; a result-limit migration to 25 did not occur.