Graph Query

---
name: graph-query
description: '[Code Intelligence] Use when querying code relationships and connections via the knowledge graph.'
version: 1.0.0
---

## Quick Summary

**Goal:** [Code Intelligence] Query code relationships and connections using the structural knowledge graph. Show related files, callers, callees, imports, tests, inheritance, and file structure. Requires graph to be built first via /graph-build. Triggers on "who calls", "what imports", "related files", "connections of", "depends on", "tests for", "inherits from", "file structure", "graph query".

**Workflow:**

1. **Detect** — classify request scope and target artifacts.
2. **Execute** — apply required steps with evidence-backed actions.
3. **Verify** — confirm constraints, output quality, and completion evidence.

**Key Rules:**

- MUST ATTENTION keep claims evidence-based (`file:line`) with confidence >80% to act.
- MUST ATTENTION keep task tracking updated as each step starts/completes.
- NEVER skip mandatory workflow or skill gates.

## Prerequisites

1. **Graph must exist** -- check `.code-graph/graph.db`. If missing, tell user to run `/graph-build` first.
2. Requires Python 3.10+ with tree-sitter, tree-sitter-language-pack, networkx.

## Intent Mapping

Map user's question to the appropriate query pattern(s):

| User asks...                                                   | Pattern(s) / Command                   |
| -------------------------------------------------------------- | -------------------------------------- |
| "who/what calls X", "callers of X"                             | `callers_of`                           |
| "what does X call", "callees of X"                             | `callees_of`                           |
| "what does X import", "X depends on", "deps of X"              | `imports_of`                           |
| "who/what imports X", "importers of X", "who references X"     | `importers_of`                         |
| "who uses X", "what uses X", "reverse deps of X"               | `importers_of`                         |
| "what's inside X", "structure of X", "contents"                | `file_summary` (files) / `children_of` |
| "what tests cover X", "tests for X"                            | `tests_for`                            |
| "who inherits/extends X", "subclasses of X"                    | `inheritors_of`                        |
| "show all connections/related files of X", "graph connections" | `connections` command (see below)      |

For composite queries ("show all connections", "related files", "full picture"), use the **`connections`** command instead of running multiple queries manually.

## Workflow

### Step 1: Check graph exists

```bash
ls .code-graph/graph.db 2>/dev/null && echo "OK" || echo "MISSING"
```

If MISSING: stop and tell user to run `/graph-build`.

### Step 2: Identify target

Extract the target from user's question (file path, function name, or class name).

- For files: use relative path (e.g., `{source-root}/utils`)
- For functions/classes: use the name (e.g., `validateInput`) or qualified name (e.g., `{source-root}/utils::validateInput`)

### Step 3: Run query

Execute via Bash with `--json` flag:

```bash
python .claude/scripts/code_graph query <pattern> <target> --json
```

For composite "show all connections" queries, use the **`connections`** command instead:

```bash
python .claude/scripts/code_graph connections <target> --json
```

This returns `file_summary`, `imports_of`, `importers_of`, `callers_of`, and `tests_for` in one call (capped at 20 results per section).

**Tip:** Add `--node-mode file` to `query`, `connections`, or `trace` for a file-level overview with 10-30x less noise. Options: `file`, `function`, `class`, `all` (default).

### Step 4: Handle response status

- **`status: "ok"`** -- Parse `results[]` and `edges[]`, format report (Step 5)
- **`status: "ambiguous"`** -- Multiple matches found. Show `candidates[]` list and ask user to pick one using `AskUserQuestion`
- **`status: "not_found"`** -- No match. Suggest: check spelling, use relative file path, try a different name. Optionally run `file_summary` on the parent file to show available names.
- **`status: "error"`** -- Show error message. Common: graph.db missing, Python version too old.

### Step 5: Format results

Present results grouped by relationship type. For each result show:

- **Name** and **kind** (function, class, method)
- **File path** with line numbers (`file:line_start-line_end`)
- **Relationship** (calls, imports, tests, inherits)

**Single query output format:**

```
## {Pattern Description} for `{target}`

Found {N} result(s).

| Name | Kind | File | Lines |
|------|------|------|-------|
| ... | function | {source-root}/file | 10-25 |
```

**Composite query output format:**

```
## Connections of `{target}`

### File Summary
{N} nodes: {list functions/classes}

### Imports (outgoing)
{What this file/module imports}

### Importers (incoming)
{Who imports this file/module}

### Callers
{Functions that call functions in this file}

### Test Coverage
{Tests covering functions in this file}
```

## Semantic Query Protocol (When User Query is Not File-Specific)

When the user asks about a FLOW or BEHAVIOR (not a specific file), follow this protocol:

### Step 0: Grep/Glob/Search to find trace anchors

Use Grep/Glob/Search to find key classes/functions related to the user's query.

- Bug/failure symptom: find the final output reader first (renderer, query, assertion, aggregate, log, stored field), then trace upstream.
- Feature-flow question: find entry points (`CreateX`, `XCommand`, `XHandler`) and trace both directions.

### Step 1: Use graph to expand

Run `connections` or `batch-query` on the grep-discovered files to find ALL related files. For bugs, group results by final reader, storage/projection, writer, consumer/job, and producer/origin.

### Step 2: Trace full system flow

Run the `trace` command to follow the complete chain through all edge types:

```bash
python .claude/scripts/code_graph trace <entry-file> --direction both --depth 3 --json
```

This traces upstream (who calls this?) AND downstream (what does this trigger?) through:
CALLS → TRIGGERS_EVENT → PRODUCES_EVENT → MESSAGE_BUS → API_ENDPOINT

For bug/failure symptoms, run an upstream-first pass from the final output before expanding the suspected producer:

```bash
python .claude/scripts/code_graph trace <final-reader-or-output-file> --direction upstream --depth 5 --json
python .claude/scripts/code_graph batch-query <final-reader> <writer> <producer> --json
```

### Step 3: Verify with grep

For any graph edge that seems surprising, verify with grep that the connection is real.

## Available Query Patterns

| Pattern         | Description                              | Edge Kind             |
| --------------- | ---------------------------------------- | --------------------- |
| `callers_of`    | Functions that call the target function  | CALLS                 |
| `callees_of`    | Functions called by the target function  | CALLS                 |
| `imports_of`    | What the target file/module imports      | IMPORTS_FROM          |
| `importers_of`  | Files that import the target file/module | IMPORTS_FROM          |
| `children_of`   | Nodes contained in a file or class       | CONTAINS              |
| `tests_for`     | Tests covering the target function/class | TESTED_BY + naming    |
| `inheritors_of` | Classes inheriting from the target class | INHERITS / IMPLEMENTS |
| `file_summary`  | All nodes (functions, classes) in a file | (direct lookup)       |
| `trace`         | Full system flow from a target node      | All edge types (BFS)  |

**Aliases** (natural language mappings):

| Alias           | Resolves to     |
| --------------- | --------------- |
| `references_of` | `importers_of`  |
| `uses_of`       | `callers_of`    |
| `who_calls`     | `callers_of`    |
| `who_imports`   | `importers_of`  |
| `depends_on`    | `imports_of`    |
| `subclasses_of` | `inheritors_of` |
| `extends`       | `inheritors_of` |

## Search (Find Nodes by Keyword)

When you don't know the exact name, search first to find candidates:

```bash
python .claude/scripts/code_graph search <keyword> --json
python .claude/scripts/code_graph search <keyword> --kind Function --json
python .claude/scripts/code_graph search <keyword> --kind Class --limit 5 --json
```

Use search to **disambiguate** when a query returns `status: "ambiguous"` — narrow results by `--kind` (Function, Class, File, Type, Test) then use the full qualified_name.

## Find Path (Shortest Path Between Nodes)

Discover how two nodes are connected through the dependency graph:

```bash
python .claude/scripts/code_graph find-path <source> <target> --json
```

Returns the shortest path as a list of nodes. Useful for tracing how a command reaches an event handler, or how a frontend component connects to a backend entity.

**Tip:** If ambiguous, search for exact qualified names first, then use those in find-path.

## Query Filtering and Limiting

Control result size for large codebases:

```bash
# Limit results
python .claude/scripts/code_graph query callers_of <target> --limit 5 --json

# Filter by file path regex
python .claude/scripts/code_graph query importers_of <target> --filter "ServiceName" --json

# Limit connections per section
python .claude/scripts/code_graph connections <target> --limit 10 --json
```

**Implicit connection edge types** (created by `connect-implicit`):

| Edge Kind                | Meaning                                     |
| ------------------------ | ------------------------------------------- |
| `TRIGGERS_EVENT`         | Entity CRUD triggers event handler          |
| `PRODUCES_EVENT`         | Event handler triggers bus message producer |
| `MESSAGE_BUS`            | Message bus producer to consumer            |
| `TRIGGERS_COMMAND_EVENT` | Command triggers command event handler      |

## Batch Query (Multiple Files)

When reviewing multiple files, use batch mode for deduplicated results:

```bash
python .claude/scripts/code_graph batch-query file1 file2 file3 --json
```

Returns: deduplicated nodes + edges (internal + 1-hop external) across all queried files. Single DB connection, no duplicate data.

## Trace (Full System Flow)

Trace all connections from a target node through multiple edge types using BFS:

```bash
python .claude/scripts/code_graph trace <target> --json
python .claude/scripts/code_graph trace <target> --direction both --json
python .claude/scripts/code_graph trace <target> --direction upstream --depth 2 --json
python .claude/scripts/code_graph trace <target> --edge-kinds CALLS,MESSAGE_BUS --json
python .claude/scripts/code_graph trace <target> --direction both --node-mode file --json  # file-level overview
```

Direction options:

- `downstream` (default): Follow outgoing edges. "What happens after X?"
- `upstream`: Follow incoming edges. "What calls/triggers X?"
- `both`: Both directions. "Full flow through X" — use when entry point is a middle file (controller, command handler)

Returns a multi-level tree of connected nodes grouped by BFS depth, with edge types at each level.

## Post-Grep Trace Trigger (run a trace after grep surfaces a key file)

When a grep/glob surfaces an important entry-point file — an entity, command, query, event/command handler, controller, bus message/consumer, component, store, or api-service — immediately run a graph trace on it before concluding. Grep finds files; the trace reveals callers, consumers, bus messages, event chains, and tests that grep CANNOT find:

```bash
python .claude/scripts/code_graph trace <key-entry-file> --direction both --json
```

**Pattern: grep finds files → graph trace reveals full system flow → grep verifies specific details.**

## Anti-Patterns

- **Don't rebuild graph** -- use `/graph-build` for that. This skill only queries.
- **Don't use for change-driven analysis** -- use `/graph-blast-radius` for git-diff-based impact.
- **Don't use for bulk export** -- use `/graph-export` for full graph dump.
- **Don't use for diagrams** -- use `/graph-export --format=mermaid` for Mermaid visualization.
- **Always use `--json` flag** -- ensures structured parseable output.

## Related Skills

- `/graph-build` -- Build or update the graph (prerequisite)
- `/graph-blast-radius` -- Change-driven impact analysis from git diff
- `/graph-export` -- Export full graph to JSON (`--format=json`) or a single file as a Mermaid diagram (`--format=mermaid`)

---

# Graph Query

Query code relationships using the structural knowledge graph. Maps natural language questions to graph CLI queries and formats structured reports.

<!-- SYNC:end-to-start-debugger-trace -->

> **End-to-Start Debugger Trace** — For non-trivial bugs, failed verification, regression fixes, behavior-changing code, or unclear code flow, start from the observed final state and walk backward before proposing a fix.
>
> 1. **Frame 0: observed end state** — Name the exact user-visible output, failing assertion, log line, persisted value, API response, rendered UI, or aggregate bucket. Record the reader/query/renderer that produced it with `file:line` evidence.
> 2. **Walk backward one hop at a time** — Trace final reader -> projection/cache/storage -> writer -> consumer/handler/job -> producer/caller -> original trigger. At every hop record: input, transformation, output, owner, and evidence.
> 3. **Enumerate all feeder paths** — Find every upstream producer/caller/event/job that can write into the final path, including retry, async, cache, background, and alternate UI/API paths. Mark each path verified, ruled out, or still unknown.
> 4. **Build the hypothesis matrix** — For each plausible cause, list evidence for, evidence against, how to reproduce/verify, blast radius, and status (`primary`, `contributing`, `ruled out`, `latent`). Do not fix until competing causes are explicitly resolved or bounded.
> 5. **Choose the owning fix layer** — Identify the invariant owner and the lowest shared point that protects all downstream consumers. A fix at the symptom site is rejected unless the symptom site owns the invariant.
> 6. **Prove convergence forward** — After choosing the fix, walk start -> end again and show how the corrected state reaches the observed final output. Map each root cause to a fix part and each fix part to a test/proof.
>
> **BLOCKED until:** final state named · backward trace written · all feeder paths enumerated · hypothesis matrix completed · owning fix layer justified · forward convergence proof mapped to tests.
>
> **NEVER:** Start at the first suspicious code path. Collapse multiple producers into one "flow". Treat duplicate symptoms as duplicate records without proving the read model. Skip ruled-out hypotheses.

<!-- /SYNC:end-to-start-debugger-trace -->

<!-- SYNC:ai-mistake-prevention -->

> **AI Mistake Prevention** — Failure modes to avoid on every task:
>
> **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting.
> **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing.
> **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first.
> **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done.
> **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect.
> **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard.
> **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk.
> **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure.
> **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.

<!-- /SYNC:ai-mistake-prevention -->

<!-- SYNC:critical-thinking-mindset -->

> **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
> **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

<!-- /SYNC:critical-thinking-mindset -->

<!-- SYNC:critical-thinking-mindset:reminder -->

**MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.

<!-- /SYNC:critical-thinking-mindset:reminder -->

<!-- SYNC:ai-mistake-prevention:reminder -->

**MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.

<!-- /SYNC:ai-mistake-prevention:reminder -->

<!-- SYNC:end-to-start-debugger-trace:reminder -->

**IMPORTANT MUST ATTENTION** debugger trace gate: for non-trivial bug/fix/investigation/review work, start at the observed final output and trace backward through reader -> storage/projection -> writer -> consumer/job -> producer/trigger. Enumerate all feeder paths and hypotheses before fixing. **BLOCKED until** trace, hypothesis matrix, owning fix layer, and forward convergence proof exist.

<!-- /SYNC:end-to-start-debugger-trace:reminder -->

<!-- SYNC:project-protocol-overlay -->

> **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `<protocols-dir>/<Name>.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`.
>
> Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently.

<!-- /SYNC:project-protocol-overlay -->

<!-- SYNC:project-protocol-overlay:reminder -->

**MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `<protocols-dir>/<Name>.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user.

<!-- /SYNC:project-protocol-overlay:reminder -->

## Closing Reminders

**Protocols in force (concise digest of the SYNC/shared blocks this skill carries):**

- **End-To-Start Debugger Trace:** start at observed final output, trace backward, hypothesis matrix before fixing.
- **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity.
- **Critical Thinking:** every claim needs traced `file:line` proof, confidence >80% to act.

- **MANDATORY IMPORTANT MUST ATTENTION** break work into small todo tasks using `TaskCreate` BEFORE starting
- **MANDATORY IMPORTANT MUST ATTENTION** search codebase for 3+ similar patterns before creating new code
- **MANDATORY IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act)
- **MANDATORY IMPORTANT MUST ATTENTION** add a final review todo task to verify work quality

**[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.