Video-Tree-TRM5/.claude/skills/graphify/references/query.md

graphify reference: query, path, explain

Load this when the user asks a question against an existing graph, or runs /graphify path or /graphify explain. The core's query stub points here for the full traversal flow.

Two traversal modes - choose based on the question:

Mode	Flag	Best for
BFS (default)	(none)	"What is X connected to?" - broad context, nearest neighbors first
DFS	--dfs	"How does X reach Y?" - trace a specific chain or dependency path

Step 0 — Constrained query expansion (REQUIRED before traversal)

graphify's query CLI matches nodes via case-folded substring + IDF — there is no stemming, no synonyms, no cross-language match inside the binary. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.

Fix this without inventing tokens by expanding the query against the actual graph vocabulary first:

1. Extract the token vocabulary from node labels:

$(cat graphify-out/.graphify_python) -c "
import json, re
from pathlib import Path
data = json.loads(Path('graphify-out/graph.json').read_text())
vocab = set()
for n in data['nodes']:
    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
        for p in parts:
            t = p.lower()
            if 3 <= len(t) <= 30:
                vocab.add(t)
Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)))
print(f'vocab: {len(vocab)} tokens')
"

2. Read graphify-out/.vocab.txt. Then for the user's question, select up to 12 tokens from this exact list that semantically match the query intent. Hard constraints:

   • You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
   • If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
   • If no vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
   • Translate cross-language: Russian "аутентификация" → look for auth, credential, token, security IFF present in vocab.
   • Morphology: "handlers" maps to handler IFF present; "todos" maps to todo IFF present.

3. Print the selection explicitly to the user before running the query, so the expansion is auditable:

Query expanded to (from graph vocab, N tokens): [token1, token2, ...]

If the list is empty, say so plainly and stop — do not proceed to traversal.

Step 1 — Traversal

Build the expanded query string by joining the selected tokens with spaces. Use this string as QUESTION below — NOT the original user question. (The original question is preserved only for save-result at the end.)

graphify query "QUESTION"
# or: graphify query "QUESTION" --dfs --budget 3000

Answer using only what the graph output contains. Quote source_location when citing a specific fact. If the graph lacks enough information, say so - do not hallucinate edges.

After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the --answer text (e.g. "Expanded from original query via vocab: [tokens]. Then traversed...") so the next --update extracts the expansion history as a graph node:

$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2

Replace ORIGINAL_QUESTION with the user's verbatim question, ANSWER with your full answer text (containing the expanded-token trace), NODE1 NODE2 with the list of node labels you cited. This closes the feedback loop: the next --update will extract this Q&A as a node in the graph.

---

For /graphify path

Find the shortest path between two named concepts in the graph.

graphify path "NODE_A" "NODE_B"

Replace NODE_A and NODE_B with the actual concept names. Then explain the path in plain language - what each hop means, why it's significant.

After writing the explanation, save it back:

$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B

---

For /graphify explain

Give a plain-language explanation of a single node - everything connected to it.

graphify explain "NODE_NAME"

Replace NODE_NAME with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.

After writing the explanation, save it back:

$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME