/devql-explore-first

name: devql-explore-first
description: >
  Use always before codebase exploration, bug fixing, SWE-bench tasks, locating
  symbols, files, or tests, or before using rg, grep, sed, find, or source-file
  reads in a repository.

DevQL Explore First

<VERY_IMPORTANT> For code understanding and exploration, DevQL is the primary discovery tool, not a one-time preflight. Use `bitloops devql query ...` whenever locating symbols, files, tests, implementations, callers/usages, or the next source region to inspect. </VERY_IMPORTANT>

Do not use `sed`, `rg`, `grep`, `find`, `wc`, directory crawling, or broad source-file reads to discover task-relevant code while DevQL can answer the lookup. Use traditional tools only to:

• read bounded ranges returned by DevQL
• inspect files you are editing after DevQL selected them
• run tests or git/status commands
• fall back when DevQL fails, is empty, or contradicts the task

Do not run `bitloops devql --help` or `bitloops devql query --help`.

Choose the most specific selector:

• known `symbolFqn`: use `symbolFqn`
• known file or file range: use `path`, optionally with `lines`
• single concrete identifier, method name, literal, error code, path-like

string, or copied snippet: use `searchMode: LEXICAL`

• architecture role terms such as API endpoint, command handler, repository,

adapter, or boundary: use `searchMode: ARCHITECTURE`

• multiple related terms, behavior, concept, or task keywords without one exact

anchor: omit `searchMode` and use default `AUTO`

Fuzzy symbol-name lookup is included in the lexical lane; do not use a separate fuzzy selector.

Use compact exploration queries. If the prompt has no concrete anchor, start with the default `AUTO` query:

bitloops devql query '{ selectArtefacts(by: { search: "<short behavior phrase or task keywords>" }) { count artefacts(first: 10) { path symbolFqn canonicalKind startLine endLine score } } }'
bitloops devql query '{ selectArtefacts(by: { search: "<single identifier, literal, path fragment, or short snippet>", searchMode: LEXICAL }) { count artefacts(first: 10) { path symbolFqn canonicalKind startLine endLine score } } }'
bitloops devql query '{ selectArtefacts(by: { symbolFqn: "<symbol-fqn>" }) { count artefacts(first: 10) { path symbolFqn canonicalKind startLine endLine score } } }'
bitloops devql query '{ selectArtefacts(by: { path: "<repo-relative-path>", lines: { start: <start>, end: <end> } }) { count artefacts(first: 10) { path symbolFqn canonicalKind startLine endLine score } } }'

For architecture role context on a known file, use the minimal GraphQL shape and request role fields only unless target or rule metadata is needed:

bitloops devql query  '{ selectArtefacts(by: { path: "<repo-relative-path>" }) { architectureRoles(first: 10) { items(first: 10) { role { canonicalKey displayName family description } target { symbolFqn canonicalKind } } } } }'
bitloops devql query  '{ selectArtefacts(by: { symbolFqn: "<symbol-fqn>" }) { architectureRoles(first: 10) { items(first: 10) { role { canonicalKey displayName family description } target { symbolFqn canonicalKind } } } } }'

If DevQL returns relevant paths and line ranges:

• read only about 50 lines before and after those ranges
• do not duplicate the same search with `rg`, `grep`, `glob`, or `find`
• for each new exploration question, query DevQL again instead of switching to

grep/glob/find

• fall back to normal search only if DevQL fails, is empty, or contradicts the task
• use at most 3 DevQL calls before each bounded source-read phase