SuperAPI AI Directory

query-and-explain

General & other

View repository

Updated 10-16 06:14

About this skill

Query & Explain the Graph

Self-Evolving Skill: This skill improves through use. If a query verb drifts or graph-interpretation guidance proves wrong — fix this file immediately, don't defer. Only update for real, reproducible issues.

Interrogate a persistent graphify-out/graph.json built earlier by graphify-tools:build-graph. This is the token-efficiency payoff: answers come from the graph (~71× fewer tokens on large corpora), not from re-reading raw files.

Prerequisite: a graphify-out/ directory must exist for the target corpus. If missing, invoke graphify-tools:build-graph first. If the corpus changed since the last build, suggest graphify <target> --update before trusting answers.

Verbs

Run from the directory containing graphify-out/ (or pass the target folder):

# Natural-language question across the whole graph
graphify query "what connects attention to the optimizer?"

# Shortest/strongest path between two named nodes
graphify path "DigestAuth" "Response"
Deep-dive one node: its edges, communities, provenance

graphify explain "SwinTransformer"


## Interpreting results

- Edge tags matter: `EXTRACTED` = found in source; `INFERRED` = LLM-suggested; `AMBIGUOUS` = flagged uncertain. Quote the tag when relaying a claim to the operator.
- If `query` returns nothing useful, check node naming with the graph's own inventory first — `GRAPH_REPORT.md` lists god nodes and communities; `graph.html` has interactive search.
- For **symbol-level** follow-ups (who calls this function, what breaks if I change it) hand off to the codegraph MCP tools instead — that's their home turf.
- `query`/`path`/`explain` read `graph.json` locally — **no LLM call, no backend needed**. (Only `extract`/`cluster-only`/`label` hit an LLM; see [`../../references/backends.md`](../../references/backends.md).)

## Staleness check

```bash
# Newest source file vs newest cache entry — if sources are newer, recommend --update
find <target> -newer <target>/graphify-out/graph.json -type f | grep -v graphify-out | head

Post-Execution Reflection

After this skill completes, reflect before closing the task:

  1. Locate yourself. — Find this SKILL.md's canonical path before editing.
  2. What failed? — Fix the instruction that caused it.
  3. What worked better than expected? — Promote to recommended practice.
  4. What drifted? — Fix any script, reference, or dependency (esp. references/backends.md) that no longer matches reality.
  5. Log it. — Add a dated note to the plugin CLAUDE.md provenance with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.