Analyze the current code changes against the knowledge graph in the project's data directory (.ua/knowledge-graph.json, or the legacy .understand-anything/knowledge-graph.json when that directory is present).
-
Resolve the data directory $UA_DIR. Run UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua) — this is the legacy .understand-anything/ when it already exists, otherwise the new .ua/. Check that $UA_DIR/knowledge-graph.json exists. If not, tell the user to run /understand first.
-
Get the changed files list (do NOT read the graph yet):
- If on a branch with uncommitted changes:
git diff --name-only
- If on a feature branch:
git diff main...HEAD --name-only (or the base branch)
- If the user specifies a PR number: get the diff from that PR
-
Read project metadata and check graph freshness — use Grep or Read with a line limit to extract the "project" section, including gitCommitHash as GRAPH_COMMIT_RAW, then:
-
Find nodes for changed files — for each changed file path, use Grep to search the knowledge graph for:
- Nodes with matching
"filePath" values (e.g., grep "changed/file/path")
- This finds file-level nodes (including non-code types) AND function/class nodes defined in those files
- Note the
id values of all matched nodes
-
Find connected edges (1-hop) — for each matched node ID, Grep for that ID in the edges to find:
- What imports or depends on the changed nodes (upstream callers)
- What the changed nodes import or call (downstream dependencies)
- These are the "affected components" — things that might break or need updating
-
Identify affected layers — Grep for the matched node IDs in the "layers" section to determine which architectural layers are touched.
-
Provide structured analysis:
- Changed Components: What was directly modified (with summaries from matched nodes)
- Affected Components: What might be impacted (from 1-hop edges)
- Affected Layers: Which architectural layers are touched and cross-layer concerns
- Risk Assessment: Based on node
complexity values, number of cross-layer edges, and blast radius (number of affected components)
- Suggest what to review carefully and any potential issues
-
Write diff overlay for dashboard — after producing the analysis, write the diff data to $UA_DIR/diff-overlay.json so the dashboard can visualize changed and affected components. The file contains:
{
"version": "1.0.0",
"baseBranch": "<the base branch used>",
"generatedAt": "<ISO timestamp>",
"changedFiles": ["<list of changed file paths>"],
"changedNodeIds": ["<node IDs from step 4>"],
"affectedNodeIds": ["<node IDs from step 5, excluding changedNodeIds>"]
}
After writing, tell the user they can run /understand-anything:understand-dashboard to see the diff overlay visually.