graph-query

---
name: graph-query
description: Use when the user asks a question about how things in the codebase or wiki relate — what connects two things, how something works end to end, what depends on what, or what a concept means in this repo. Answers from the knowledge graph in graphify-out/graph.json, with source-location citations. Trigger on "/graph-query", "ask the graph", "what connects X to Y", "trace how X works", "explain <concept> from the graph", "shortest path between".
---

# Graph Query

Ask the knowledge graph a relationship question and get a **cited answer grounded in the graph** —
not a guess. The graph is built by `/graph` (graphify) over code + the committed `wiki/`. This skill
only reads it.

## When to run
- `graphify-out/graph.json` exists, and the user has a question about how things relate:
  - "what connects the intake flow to the billing module?"
  - "trace how a `/wiki` capture becomes a committed entry."
  - "explain the WAT execution model from the graph."
  - "shortest path between `wiki_lint.py` and the commit gate."
- Use this for *relationships and explanations*. To (re)build or refresh the graph, run `/graph`.

## The output (always this shape)
```
## Graph answer — <the question>
**Answer** — the relationship/explanation, in plain sentences, grounded only in graph edges.
**Path / nodes used**
- <node A> —[<relation>]→ <node B>   (EXTRACTED · src: <path:line>)
- <node B> —[<relation>]→ <node C>   (INFERRED — not literal in source)
**Citations** — source_location for each EXTRACTED edge (path:line).
**Gaps** — anything the question asked that the graph does NOT contain (say so plainly).
```
Every claim traces to an edge. If the graph doesn't have it, the answer says so — it never fills the gap from memory.

## Process
1. **Check the graph exists.** If `graphify-out/graph.json` is missing, stop and tell the user:
   "No graph yet — run `/graph` first to build it." Don't answer from training data or by re-reading files.
2. **Pick the query that fits the question** (graphify, read-only):
   - Broad / "what relates to X" / "what connects X to Y" → `graphify query "<question>"` (BFS, broad neighborhood).
   - Trace a chain / "how does X flow to Y" / "trace how X works" → `graphify query "<question>" --dfs` (follows a path; `--budget N` to bound it).
   - "shortest path between A and B" → `graphify path "A" "B"`.
   - "explain <concept/node>" → `graphify explain "X"` (the node + its neighbors).
   For richer interactive exploration, the graphify MCP server may be wired
   (`python3 -m graphify.serve graphify-out/graph.json` → `query_graph`, `get_node`,
   `get_neighbors`, `shortest_path`, `god_nodes`, `graph_stats`); use it when the question needs
   several hops or node lookups. Otherwise the CLI is enough.
3. **Answer using ONLY what the graph returns.** Quote the `source_location` (path:line) for each edge
   you rely on. Fill the output shape above. Two hard rules:
   - **Never invent edges.** If the query returns nothing for part of the ask, list it under **Gaps**
     and say the graph doesn't cover it — do not bridge it with a guess or by reading the file yourself.
   - **Honor the honesty trail.** graphify labels every edge `EXTRACTED` (literal in source),
     `INFERRED` (graphify's inference), or `AMBIGUOUS` (uncertain). Present only `EXTRACTED` as fact.
     Tag `INFERRED`/`AMBIGUOUS` edges as such inline — never pass them off as established.

## Autonomy
**L1 — read-only.** Suggests/answers from the graph; the human decides. Builds nothing, sends nothing,
writes no files. (To rebuild the graph, that's `/graph`, not this skill.)

## Guardrails (from CLAUDE.md)
- **Cite, don't invent** (Guardrail #6). Every claim cites a graph edge's `source_location`;
  unsupported parts of the ask are flagged as gaps, never fabricated.
- **Respect the honesty audit trail.** `EXTRACTED` = fact; `INFERRED`/`AMBIGUOUS` are flagged as such,
  not stated as truth.
- The graph covers **code + the committed (de-identified) `wiki/` only** — by design it excludes `raw/`,
  `.env`, `.tmp/`, and secrets. If asked about something outside that scope, say it isn't in the graph.
- Read-only: no commits, no external sends, no file writes from this skill.