| name | graphify-query-helper |
| description | Query the local graphify knowledge graph to answer semantic cross-document questions. Wraps `just graphify-query` with synthesis and citation. Use when a question spans design docs, RFCs, or screenshots that a single-file read cannot answer, or when the user explicitly asks about "what connects X to Y", "why did we decide Z", or "which doc explains W". Requires a pre-built graph at `graphify-out/graph.json` — if missing, stops and tells the user to run `just graphify-rebuild docs/design-docs/` first. |
/graphify-query-helper
Thin orchestrator around the graphify CLI. Graphify itself returns a BFS traversal of the graph as raw node/edge dumps. That output is hard to read and provides no citations. This skill wraps a query with:
- Graph-existence check (fail-fast if
graphify-out/graph.json is missing).
- Invocation of
just graphify-query with the user's question.
- Synthesis of the traversal output into a prose answer with
source_file:source_location citations drawn from the graph's node metadata.
- A transparency line about graph freshness — the graph's build timestamp, so the user knows whether the answer reflects current docs or a stale snapshot.
When to use
Triggers:
- User asks a question that spans multiple design docs ("why did we make X decision related to Y?").
- User asks for a connection path ("how does the Entra rollout relate to the Spacedrive integration?").
- User asks for an explanation of a concept that appears in multiple places ("explain
AuthRejectReason").
Not for:
- Structural Rust code questions — use
code-review-graph MCP tools instead (it has the full AST; graphify's AST pass covers code but code-review-graph is faster and fresher).
- Questions the user could answer by reading one file — don't over-engineer.
- A fresh workspace where no graph has been built. Say so, don't fabricate an answer.
Behavior
Step 1 — verify graph exists and is fresh enough
cd /Users/jason/dev/spacebot
if [ ! -f graphify-out/graph.json ]; then
echo "No graph at graphify-out/graph.json."
echo "Run: just graphify-rebuild docs/design-docs/"
exit 1
fi
GRAPH_AGE_DAYS=$(( ($(date +%s) - $(stat -f %m graphify-out/graph.json)) / 86400 ))
echo "Graph age: ${GRAPH_AGE_DAYS} day(s)"
If the graph is more than 30 days old, lead the answer with a staleness caveat: "Note: the graph was built N days ago — facts about recent commits may not appear."
Step 2 — pick traversal mode based on question shape
| Question shape | Mode |
|---|
| "What connects X to Y?" | just graphify-query "X Y" + graphify path "X" "Y" |
| "Explain X" | graphify explain "X" (single-node expansion) |
| "Why did we do Z?" | just graphify-query "why Z" — BFS finds rationale nodes |
| "How does X work?" | just graphify-query "X how" — BFS finds related concepts |
Step 3 — run the query
just graphify-query "<question>" 2>&1 | tee /tmp/graphify-query-raw.txt
Capture both stdout and stderr. If the output contains No matching nodes found, do NOT fabricate an answer from training data — say so explicitly: "Graphify returned no matches for this query. The graph may not cover this topic, or the question's keywords don't match any node labels."
Step 4 — synthesize with citations
For each node/edge in the raw output, extract:
source_file — always cite this when presenting a fact.source_location — include line numbers when available.confidence tag — if AMBIGUOUS, note uncertainty in the answer.
Answer template:
Based on the graph built <TIMESTAMP> over <CORPUS> (<NODE_COUNT> nodes, <EDGE_COUNT> edges):
<SYNTHESIZED PROSE ANSWER>
Sources:
- <node label> (<source_file>:<source_location>) — <one-line summary>
- <node label> (<source_file>) — <one-line summary>
If the synthesis pulls from INFERRED or AMBIGUOUS edges, flag it: "The graph infers this connection rather than finding it explicitly in the source — verify before citing."
Step 5 — save the Q&A back to the graph's memory
Graphify has a feedback-loop mechanism for memorializing good answers:
graphify save-result \
--question "<exact question the user asked>" \
--answer "<your full synthesized answer>" \
--type query \
--nodes <node labels cited>
This writes to graphify-out/memory/ and makes the Q&A surface as a node in the next --update pass. Only do this when the answer is high-confidence. For AMBIGUOUS or "no matches" paths, skip — don't pollute the memory with low-signal entries.
Example invocations
User asks a cross-doc question
User: "Why did we rename auth.rs to anthropic_oauth.rs?"
Skill:
1. Verifies graph exists (freshness: 2 days).
2. Runs: just graphify-query "rename auth.rs anthropic_oauth"
3. BFS traversal returns nodes: {auth_rs_rename, entra_phase_1, anthropic_oauth_pkce}
with edges from entra-app-registrations.md citing the rename.
4. Synthesizes:
"The rename happened during Entra Phase 1 (PR #82, 2026-04-20).
src/auth.rs previously held the Anthropic OAuth PKCE flow. Phase 1
introduced src/auth/ as a module tree for Entra JWT validation,
which needed the auth namespace. The OAuth PKCE code was moved to
src/anthropic_oauth.rs to free the path, with 10 call sites migrated.
Sources:
- entra-app-registrations.md:42 (EXTRACTED)
- entra-phase-1 node (INFERRED, confidence 0.8)"
5. graphify save-result to memorize this answer.
User asks a question the graph can't answer
User: "What's the latest on the Entra Phase 5 design?"
Skill:
1. Verifies graph exists (freshness: 5 days).
2. Runs: just graphify-query "Entra Phase 5"
3. Output: "No matching nodes found."
4. Responds:
"The graph has nodes for Phase 1-3 but no match for Phase 5.
Either the design doc hasn't been written yet, or the graph
needs rebuilding to pick up recent design work. Try:
ls docs/design-docs/ | grep -i phase-5
If a file exists, run: just graphify-rebuild docs/design-docs/"
Related
spacebot-dev skill — use for Rust architectural questions.spacedrive-dev skill — use for Spacedrive-integration questions.code-review-graph MCP tools — use for structural code queries (faster than graphify for code-only questions)..scratchpad/completed/2026-04-21-graphify-research.md — full context on graphify itself, including why this skill exists.
Honesty rules
- Never invent a source citation. If the graph doesn't provide a
source_location, omit the citation rather than fabricate one.
- Always report graph freshness. A 30-day-old graph answering a question about yesterday's commit is misleading.
- Never claim an INFERRED or AMBIGUOUS edge is a definitive connection — flag the uncertainty.
- If
just graphify-query returns "No matching nodes found", say so. Do not fall back to training-data answers about the codebase.
