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.