choral-io Workspace Search
Honor explicit tool choices, repository conventions, and access boundaries. Discover available tools once per working environment and consult relevant CLI help as needed.
Search decision tree
- Searching for calls, declarations, imports, or other code syntax patterns? Prefer ast-grep when the language and pattern are supported. For file paths, exact strings, comments, logs, or configuration keys, use text search. When ast-grep is unavailable or unsuitable, text matches are candidates requiring context checks.
- Reuse or scan? For text search, reuse a ready tgrep service covering the intended scope; otherwise use direct scanning: choose the first available, suitable tool in
rg → tgrep --no-index → greporder. Read Indexed search before relying on or preparing an index. - Upgrade to an index? If direct scanning is slow and more queries are expected, or substantial repeated searches across a large workspace are predictable, prepare tgrep indexing and serving within authorized scope. Once ready, use it for subsequent queries. Small scopes and one-off queries stay on direct scanning; tool availability alone does not justify indexing.
Use the same direct-scanning order when an index is unreliable, a service fails, or an indexed result needs verification. Preserve equivalent scope and filters. If no suitable tool is available, report the limitation rather than silently installing one.
Execute efficiently
Start with the requested root and likely owning paths; use the selected tool's file-discovery mode when location is unknown. Choose filenames, bounded context, or structured output according to the next decision. Narrow or partition truncated output rather than treating a displayed sample as complete.
For a simple code syntax pattern, select the language, search directly, and inspect the matches. For complex patterns, unexpected empty results, or excessive noise, check a representative match and non-match before expanding the search. Preserve the intended scope and filters when using an index.
If a tool fails, correct a clear invocation error using its help. If the failure persists or the tool cannot express the query, switch to a suitable fallback and continue the search; report any resulting limitation. Clean up any task-owned startup process after service preparation fails. Investigate the tool itself only when that is part of the requested task.
Validate and finish
Read decisive matches in context and follow relevant definitions, callers, configuration, or tests until the requested relationship is supported. Syntax matches alone do not establish symbol identity, types, or runtime reachability; use language tooling or source inspection for those questions. Before making an absence claim, check coverage, command errors, parsing failures, and index freshness as applicable; confirm important negative indexed results with direct scanning. If output drives an edit or parser, verify its format and offset semantics.
Honor read-only constraints for index writes and obtain any required service permission. Keep search separate from source rewrites and tool installation. Report decisive paths and line numbers and material coverage limits. Include service status only when the task started or changed a service, stating its final disposition.