understand-diff

3. **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:

• Resolve it as a commit before using it in any Git diff. From the project root, compare the resolved commit with git rev-parse HEAD and inspect project-scoped committed and working-tree changes:

     GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
     git rev-parse HEAD
     git diff --name-only "$GRAPH_COMMIT" HEAD -- .
     git diff --cached --name-only -- .
     git diff --name-only -- .
     git ls-files --others --exclude-standard -- .

• The -- . pathspec is required: commits that only touch a sibling monorepo project must not make this graph stale. A hash mismatch alone is not stale when the project diff is empty.
• Ignore the selected data directory (.ua/ or legacy .understand-anything/) in every command's output because it contains generated graph artifacts, not project source drift.
• If the committed diff or any working-tree command reports project files, warn before impact analysis that the graph may omit those changes. Suggest: Run /understand to refresh the graph.
• Run the commit diff only when GRAPH_COMMIT_RAW resolves successfully. If the graph commit or Git metadata is missing, invalid, or unavailable, give a brief best-effort warning and continue instead of blocking.

4. **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

5. **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

6. **Identify affected layers** — Grep for the matched node IDs in the "layers" section to determine which architectural layers are touched.

7. **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

8. **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.