understand-chat · diff
git:20260703.f0f5fa5 to git:20260708.0bae36e
41 added, 39 removed. Audit A to A.
- ---
- name: understand-chat
- description: Use when you need to ask questions about a codebase or understand code using a knowledge graph
- argument-hint: "[query]"
- ---
-
- # /understand-chat
-
- Answer questions about this codebase using the knowledge graph at `.understand-anything/knowledge-graph.json`.
-
- ## Graph Structure Reference
-
- The knowledge graph JSON has this structure:
- - `project` — {name, description, languages, frameworks, analyzedAt, gitCommitHash}
- - `nodes[]` — each has {id, type, name, filePath?, summary, tags[], complexity, languageNotes?}
- - Code node types: file, function, class, module, concept
- - Non-code node types: config, document, service, table, endpoint, pipeline, schema, resource
- - Domain/knowledge node types: domain, flow, step, article, entity, topic, claim, source
- - IDs use the node type as prefix, e.g. `file:path`, `function:path:name`, `config:path`, `article:path`
- - `edges[]` — each has {source, target, type, direction, weight}
- - Key types: imports, contains, calls, depends_on, configures, documents, deploys, triggers, contains_flow, flow_step, related, cites
- - `layers[]` — each has {id, name, description, nodeIds[]}
- - `tour[]` — each has {order, title, description, nodeIds[]}
-
- ## How to Read Efficiently
-
- 1. Use Grep to search within the JSON for relevant entries BEFORE reading the full file
- 2. Only read sections you need — don't dump the entire graph into context
- 3. Node names and summaries are the most useful fields for understanding
- 4. Edges tell you how components connect — follow imports and calls for dependency chains
-
- ## Instructions
-
- 1. Check that `.understand-anything/knowledge-graph.json` exists in the current project root. If not, tell the user to run `/understand` first.
+ ---
+ name: understand-chat
+ description: Use when you need to ask questions about a codebase or understand code using a knowledge graph
+ argument-hint: "[query]"
+ ---
+
+ # /understand-chat
+
+ Answer questions about this codebase using the knowledge graph at `.understand-anything/knowledge-graph.json`.
+
+ ## Graph Structure Reference
+
+ The knowledge graph JSON has this structure:
+ - `project` — {name, description, languages, frameworks, analyzedAt, gitCommitHash}
+ - `nodes[]` — each has {id, type, name, filePath?, summary, tags[], complexity, languageNotes?}
+ - Code node types: file, function, class, module, concept
+ - Non-code node types: config, document, service, table, endpoint, pipeline, schema, resource
+ - Domain/knowledge node types: domain, flow, step, article, entity, topic, claim, source
+ - IDs use the node type as prefix, e.g. `file:path`, `function:path:name`, `config:path`, `article:path`
+ - `edges[]` — each has {source, target, type, direction, weight}
+ - Key types: imports, contains, calls, depends_on, configures, documents, deploys, triggers, contains_flow, flow_step, related, cites
+ - `layers[]` — each has {id, name, description, nodeIds[]}
+ - `tour[]` — each has {order, title, description, nodeIds[]}
+
+ ## How to Read Efficiently
+
+ 1. Use Grep to search within the JSON for relevant entries BEFORE reading the full file
+ 2. Only read sections you need — don't dump the entire graph into context
+ 3. Node names and summaries are the most useful fields for understanding
+ 4. Edges tell you how components connect — follow imports and calls for dependency chains
+
+ ## Instructions
+
+ 1. Check that `.understand-anything/knowledge-graph.json` exists in the current project root. If not, tell the user to run `/understand` first.
+
+ 2. **Check graph freshness** — read `project.gitCommitHash` from the graph metadata and run `git rev-parse HEAD` in the project root. If both values exist and differ, warn the user before answering that the knowledge graph may be stale and newer code may be missing from the answer. Suggest: Run `/understand` to refresh the graph. If git metadata is missing or unavailable, continue with a brief best-effort warning instead of blocking.
- 2. **Read project metadata only** — use Grep or Read with a line limit to extract just the `"project"` section from the top of the file for context (name, description, languages, frameworks).
+ 3. **Read project metadata only** — use Grep or Read with a line limit to extract just the `"project"` section from the top of the file for context (name, description, languages, frameworks).
- 3. **Search for relevant nodes** — use Grep to search the knowledge graph file for the user's query keywords: "$ARGUMENTS"
+ 4. **Search for relevant nodes** — use Grep to search the knowledge graph file for the user's query keywords: "$ARGUMENTS"
- Search `"name"` fields: `grep -i "query_keyword"` in the graph file
- Search `"summary"` fields for semantic matches
- Search `"tags"` arrays for topic matches
- Note the `id` values of all matching nodes
- 4. **Find connected edges** — for each matched node ID, Grep for that ID in the `edges` section to find:
+ 5. **Find connected edges** — for each matched node ID, Grep for that ID in the `edges` section to find:
- What it imports or depends on (downstream)
- What calls or imports it (upstream)
- This gives you the 1-hop subgraph around the query
- 5. **Read layer context** — Grep for `"layers"` to understand which architectural layers the matched nodes belong to.
+ 6. **Read layer context** — Grep for `"layers"` to understand which architectural layers the matched nodes belong to.
- 6. **Answer the query** using only the relevant subgraph:
+ 7. **Answer the query** using only the relevant subgraph:
- Reference specific files, functions, and relationships from the graph
- Explain which layer(s) are relevant and why
- Be concise but thorough — link concepts to actual code locations
- If the query doesn't match any nodes, say so and suggest related terms from the graph