# Query Code
> Query Codemap's Python structural index for dependencies, callers, paths, symbols, blast radius, test impact, mocks, fixtures, subprocesses, and static gaps. Trigger for "what depends on", "who calls", "imports of", "dependency graph", or "blast radius". Skip for renames, text search, non-Python repositories, or index rebuilds.
- Skill: `borda/query-code-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add borda/query-code-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/borda/query-code-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Borda (https://skillmd.com/u/borda)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/borda/query-code-2
---
Answer structural Python questions via unified `codemap-py query` CLI.
NOT for: rebuilding the index (use `/codemap-py:scan-codebase`), renaming symbols (use `/codemap-py:rename-refs`), or which tests cover or are affected by a change (use `/codemap-py:test-impact`).
Test-impact split: a one-off structural fact ("which tests would this touch?") uses table subcommand `test-impact `; full affected-test workflow (index ensure, JSON parse, `pytest` command, `not_covered` caveat) uses `/codemap-py:test-impact`. NOT-for defers workflow, not subcommand.
Skip Codemap when exact file + symbol localize edit and no caller, dependency, blast-radius, test-impact, import, or source-slice fact remains open. Lifecycle boundary—callback/hook, cancellation/exception, scheduling/cleanup, state transfer—keeps scope open: inspect source + named test/oracle, then query `fn-rdeps` for caller or `fn-deps` for callee responsibility. Explicit structural query/tool requirement overrides skip. Otherwise use smallest complete query.
## Choose the smallest complete query set
"Affected if X changes" = reverse dependencies. Run every query from the caller's current repository; working directory selects project index. Do not `cd` into `$CLAUDE_PLUGIN_ROOT` or plugin directory.
```bash
codemap-py query --compact [arguments]
```
For a custom-root index, pass `--index --root `; `--root` is path resolution only and does not select the index.
Enabled plugin adds version-matched `bin/` to Bash `PATH`. If unavailable interactively, invoke installed plugin's absolute `bin/codemap-py` launcher as one standalone command and accept normal host permission prompt. Prepend no `cd`, `export`, or other shell command.
| Goal | Query subcommand |
| -- | -- |
| production module importers / blast radius | `rdeps --exclude-tests` |
| direct test-module importers | `rdeps ` then filter/report test modules |
| module imports | `deps ` |
| shortest import chain | `path ` |
| production centrality / highest in-degree | `central --top N --exclude-tests` |
| rank / threshold a known candidate set | `central --among --exclude-tests` |
| production vs test importer counts | `rdeps --exclude-tests` (`importer_count`, `excluded_test_importer_count`) |
| internal-import coupling (not centrality) | `coupled --top N` |
| symbol source including module imports or module symbols | `symbol --with-imports` · `symbols ` |
| regex symbol search | `find-symbol ` |
| direct production callers | `fn-rdeps --exclude-tests` |
| callers plus test-module importers | `fn-rdeps --exclude-tests`, then `rdeps ` |
| direct imports / callees | `fn-deps ` |
| transitive callers / function blast | `fn-blast ` |
| broken Sphinx cross-references | `xrefs --broken ` |
| changed-code blast radius | `diff-impact [--base REF]` |
| transitive affected tests / mocks | `test-impact ` · `mock-rdeps ` |
| pytest fixtures | `fixture-rdeps ` · `fixture-graph ` |
| subprocess relationships | `subprocess-deps ` · `subprocess-rdeps ` |
| coverage / documentation gaps | `coverage ` · `coverage-gap [module]` · `undocumented [module]` |
Direct/every/all/production/blast-radius callers → `fn-rdeps --exclude-tests`; `fn-blast ` only for explicit transitive, closure, hops, or all-levels requests.
Test modules directly importing module: use `rdeps `, then filter/report tests. Reserve `test-impact ` for transitive affected-test selection. For the counts alone, `rdeps --exclude-tests` reports `importer_count` and `excluded_test_importer_count` together; never derive one by subtracting a second call from the first.
Counts and scoped rankings come from the query, not from hand work on its output: do not count a returned list by eye, and do not intersect a repository-wide `central` ranking against a candidate set by hand. To order or threshold modules a previous query returned, pass them to `central --among `; its `unmatched` field names every requested module the ranking did not cover, so nothing drops silently.
`symbol ` accepts bare function (for example `authenticate`) or qualified method (for example `MyClass.method`); `module::symbol` belongs to `fn-*` call-graph queries. To chain `symbol` into `fn-*`, compose returned `module` + `qualified_name` exactly as `::`; example `mypackage.module::MyClass.method`. For feature scaffolding, query requested qualified extension method (for example, `symbol MyClass.add_feature`), not nearby `symbol MyClass` or `symbols ` listing unless broader scope requested.
For method changes possibly affecting overrides, use `find-symbol '\.$' --exclude-tests --limit 0` for same-name override candidates. Name match discovers candidates, not inheritance; inspect each source to verify ancestry + package boundaries before treating as override.
Source request naming imports: use `symbol --with-imports`. `query_complete: true` confirms index coverage, not requested optional fields.
Table is a routing shortlist, not the parser's full surface. If the operation is known but an argument is unknown, read `codemap-py query --help`; if the operation is unknown, read `codemap-py query --help`; never guess a subcommand. Known syntax needs no preliminary help, doctor, scan, or freshness call. For exploratory module importer questions, `rdeps --limit N` returns an explicit bounded preview of static `imported_by`; `dynamic_imported_by` and `config_refs` remain exhaustive. Default `rdeps ` and `rdeps --limit 0` return every static importer. A truncated preview never settles exhaustive callers.
## Index and completeness contract
Resolve the installed launcher once and retain its literal in reasoning; shell variables do not persist between tool calls. Run selected queries first; no unconditional pre-scan/freshness call. Independent read-only queries may run concurrently as separate tool commands only against a prepared stable index with no self-heal (`SCAN_NO_AUTOBUILD=1`); dependent queries wait for their inputs, and refresh, self-heal, or index writes run serially. Keep independent queries standalone, not `batch`, until its per-item completeness contract is verified. Use `test-impact` for test choice, not direct test-module import.
- Normal mode may perform the CLI's bounded incremental self-heal.
- With `SCAN_NO_AUTOBUILD=1`, never run freshness query, incremental refresh, or automatic full build. Query existing index unchanged.
- Missing frozen index = hard stop. Report structured error; ask for `/codemap-py:scan-codebase`.
- Explicit user-requested `codemap-py index` remains allowed; flag blocks only implicit writes.
Interpret `index`:
- Complete, untruncated `query_complete: true` settles its own answered structural fact, not sibling standard queries answering other dimensions. Complete-query paths are caller-repo-relative, never Skill-relative. Do not re-query/read/grep that same graph fact.
- Ordinary repository reads remain allowed for task-requested distinct independent AST/oracle view or source-body implementation/runtime. Label separately, never as rechecking complete Codemap result.
- `query_complete: false`: name `completeness_reason`; use only a targeted fallback for gaps named by `degraded`, `not_covered`, `root_mismatch`, or `stale`.
- `compact: true` changes only coverage metadata; findings/counts remain complete.
Truncation ≠ incompleteness. Truncation at 20 items is a real cap, not exhaustive unless `--limit 0` (`symbol` and `find-symbol` default). `query_complete` scores graph coverage only—staleness, degraded/untracked files, root mismatch, name collisions—not cap. Thus capped `query_complete: true` is still 20-of-N; never stop before missing items.
Before treating list as whole, read `index.confidence`: `"exact"` = all matches; `"partial"` = capped/stale. When capped, `index.truncated: true` + `index.total_available: ` give total. Before claiming complete, re-run with `--limit 0` or `--top`/`--limit` above `total_available`. This is a targeted correction for that fact, not a new sibling question.
`fn-blast` takes one qualified name, never `--depth`; `coupled` ≠ `central`. Never invent flags or retry a completed structural query. Continue distinct queries or exhaustive facts required to finish; there is no arbitrary total-call cap. For one started query, allow only bounded targeted correction retries for a syntax/argument error; if the same correction failure recurs, stop and report the failure and unfinished fact. Tool-routing failure with no CLI execution does not count.
## Render
Use JSON primary array: `imported_by` / `direct_imports`, `called_by` / `calls`, `path`, `symbols`, `central` / `coupled`, `blast_radius`, or `changed_modules` + `test_impact`. Preserve qualified names exactly. Include present stale, degraded, root-mismatch, and `not_covered` caveats.
Output routing (the only use of `Write`): if the rendered result set is 5+ items, write it to `.temp/output-query-code--.md`.