---
name: DevQL Explore First
slug: devql-explore-first
category: AI Engineering
description: DevQL Explore First directs codebase exploration through `bitloops devql query` before using grep, find, or broad file reads. Use it to locate symbols, files, tests, implementations, and related source regions in a repository.
github: "https://github.com/bitloops/bitloops/tree/main/bitloops/src/host/hooks/augmentation/skills/devql-explore-first"
language: Rust
stars: 239
forks: 17
install: "npx degit https://github.com/bitloops/bitloops/tree/main/bitloops/src/host/hooks/augmentation/skills/devql-explore-first ~/.claude/skills/devql-explore-first"
installs_to: ~/.claude/skills/devql-explore-first
source_path: bitloops/src/host/hooks/augmentation/skills/devql-explore-first/SKILL.md
collection_size: 2
category_size: 2793
collection_url: "https://dirskills.com/collections/bitloops/bitloops"
added: 2026-09-03T06:03:59.930Z
last_synced: 2026-09-03T06:03:59.930Z
canonical_url: "https://dirskills.com/skills/devql-explore-first"
---

# DevQL Explore First

DevQL Explore First directs codebase exploration through `bitloops devql query` before using grep, find, or broad file reads. Use it to locate symbols, files, tests, implementations, and related source regions in a repository.

**Install:**

```bash
npx degit https://github.com/bitloops/bitloops/tree/main/bitloops/src/host/hooks/augmentation/skills/devql-explore-first ~/.claude/skills/devql-explore-first
```

## README

# 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:

```bash
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:

```bash
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