kg-query

name: kg-query description: "Query accumulated knowledge — BFS/DFS graph traversal + wiki lookup. Supports --depth quick|standard|deep for token-efficient queries. Use when asking questions ABOUT existing knowledge (relationships, evidence, decisions). For PROPOSING new connections between communities, use /kg-connect instead." trigger: /kg-query

/kg-query — Query Knowledge

Answer questions against accumulated knowledge. Strategy depends on available layers and requested depth.

Activate When

User asks a question about the kg wiki, codebase relationships, or concept connections
User invokes /kg-query <question> [--depth quick|standard|deep]
After /kg-orient, when user wants to dive into a specific topic
Before deciding what to ingest next (deep mode = "do we have this already?")

Do Not Activate When

Question is about external (web) information not in wiki → /kg-autoresearch
User wants pattern/tension surfacing → /kg-reflect
User wants to test a single claim → /kg-challenge
User wants suggestions for what to ingest → /kg-suggest

Query Depth Modes

/kg-query [question] --depth [quick|standard|deep]

Default: standard. User can override per query.

Quick (~1.5K tokens read budget)

BM25 lookup (0 tokens): If wiki/.search_index.json exists and is fresh (<24h), load and search directly. Otherwise rebuild first with python3 ~/.claude/skills/kg/schema/tools/build_search_index.py wiki. Returns top-5 pages ranked by relevance.
Read wiki/hot.md (session context cache)
Read top-1 BM25 result page if high confidence (score > 50)
If insufficient: say so and suggest --depth standard

Best for: "What was I working on?", "Which heuristics exist for X?", status checks.

Standard (~3K tokens read budget) — default

BM25 lookup (0 tokens): get top-10 results. Use scores to prioritize which pages to read.
Read wiki/hot.md
Read up to 5 pages from BM25 top results (prioritize: highest BM25 score, then most recently modified)
For structural questions, supplement with graphify query
Synthesize with [[wikilink]] citations
wiki/index.md is a low-confidence fallback — only if BM25 returns no results

Best for: factual questions, concept lookups, relationship queries.

Deep (~8K+ tokens read budget)

All of Standard
Follow wikilinks to depth 2 (pages linked by the pages you read)
Read raw source files cited in provenance fields
If graph layer exists, run BFS traversal from relevant nodes
Cross-reference claims across sources; flag contradictions
Deterministic claim/evidence harvest: run python3 ~/.claude/skills/kg/schema/tools/extract_claims.py wiki/ --types=claim,evidence to get a JSON list of all > [!claim] and > [!evidence] callouts before synthesizing the answer. Cite by page:line.
If wiki is insufficient and topic is external: suggest /kg-autoresearch

Best for: "Why did we choose X over Y?", cross-cutting analysis, preparing for decisions.

Token Budget Enforcement

Each mode has a soft budget. If exceeded before synthesis:

Quick: truncate to hot.md only
Standard: skip low-relevance pages
Deep: skip depth-2 pages, keep raw source reads

Operating Modes

Graph-only (no wiki/):

Read graphify-out/GRAPH_REPORT.md for structural context
Load graph.json via json_graph.node_link_graph(data, edges='links')
Match query terms to node labels, BFS traverse (depth 3)
Synthesize answer from graph structure with source citations

Graph + Wiki (depth modes apply):

Follow the depth mode flow above
File answer to wiki/queries/ if worth keeping
Update wiki/hot.md with the query topic

Verification chain: Graph -> Wiki -> Raw Source. Never cite graph/wiki as primary evidence.

Codex handoff: Query results can be injected into Codex prompts as <domain_context> when the follow-up is a Codex review/rescue task. Selection: matched heuristics (confidence: high), related decisions (decided_for), hot.md tensions. Cap ~~500 tokens. See `~~/.claude/skills/kg/references/codex-integration.md`.

Structural sub-queries (graphify CLI, when `graphify-out/` fresh)

For relationship/impact questions the bare graphify CLI answers from graph.json at 0 LLM tokens — prefer it over loading the graph into context:

Question shape	Command
"What connects A to B?" / topic neighborhood	`graphify query "<q>" --budget N` (BFS; `--dfs` for depth-first)
"…but only along USE / import / calls edges"	`graphify query "<q>" --context use` (repeatable edge-context filter)
"Shortest link between X and Y"	`graphify path "X" "Y"`
"Explain this node"	`graphify explain "X"`
Impact / blast radius — "what breaks if I change X?"	`graphify affected "X" --relation R --depth N` (reverse traversal)

Impact mode is the v0.8.x addition most useful for refactoring and large-scale porting/modernization (e.g. Fortran→PyTorch): graphify affected "<symbol>" --relation imports --depth 3 returns everything transitively depending on a node before you touch it. Match --relation to how the symbol is depended on — for a Fortran module use imports (USE), for a derived type use references (--relation is repeatable: --relation imports --relation references covers both); the wrong relation silently returns an empty set. Cite the returned nodes as Evidence read → graph traversal. For Fortran specifics (USE-only filters, partial CALL coverage) see ~/.claude/skills/kg/references/fortran.md. (A dedicated /kg-impact split is intentionally avoided — impact is a query; this mode lives here.)

Output Contract

Always return:

Answer:
<direct answer to the question>

Evidence read:
- hot.md: yes | no
- overview.md: yes | no
- wiki pages: [[a]], [[b]], ...
- raw sources: <none | list>
- graph traversal: <none | depth-N from [[anchor]]>

Confidence:
high | medium | low

Caveats:
- <missing evidence | stale pages | contradictions | none>

Next command:
- <none | /kg-query --depth deep | /kg-autoresearch "<topic>" | read [[page]]>

Examples

Example 1 — quick status

User:

/kg-query "최근에 내가 뭘 보고 있었지?" --depth quick

Expected behavior:

Read wiki/hot.md only.
Skip BM25 if hot.md fresh (<24h).
Return compact answer + confidence + suggested next step.
Do not scan raw sources.

Example 2 — decision question, deep mode