# How the /understand-diff Command Analyzes Code Change Impact

> Discover how the /understand-diff command analyzes code change impact by mapping Git diffs to your knowledge graph and identifying risks from complexity and dependencies.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-01

---

**The `/understand-diff` command inspects Git diffs against a project's knowledge graph to map changed files to architectural nodes, propagate impact through one-hop relationships, and generate risk-aware reports that weigh complexity, cross-layer dependencies, and blast radius.**

The `/understand-diff` command in the **Understand-Anything** repository (Lum1104/Understand-Anything) provides automated impact analysis for pull requests and local changes. Unlike traditional diff viewers that only display line-level modifications, this tool measures the **architectural ripple effect** by comparing modified files against a persisted knowledge graph, identifying downstream components at risk.

## The Three-Phase Impact Analysis Process

The analysis implemented in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts) proceeds through three tightly-coupled phases to transform raw Git output into structured architectural intelligence.

### Phase 1: Mapping Changed Files to Graph Nodes

The algorithm begins in `buildDiffContext` (lines 31–41) by reconciling the filesystem with the graph model.

- Each path returned by `git diff … --name-only` is compared against the `filePath` property of every `GraphNode`
- Matching nodes are recorded as **changed nodes** via their IDs
- Files lacking corresponding nodes are collected as **unmapped files** for the risk assessment

This phase establishes the foundation for all downstream impact calculations by anchoring filesystem changes to the architectural knowledge graph stored in [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json).

### Phase 2: Propagating One-Hop Relationships

Once changed nodes are identified, the system calculates immediate architectural neighbors in `buildDiffContext` (lines 57–69).

```typescript
// Include "contains" children of changed file nodes
for (const edge of edges) {
  if (edge.type === "contains" && changedNodeIds.has(edge.source)) {
    changedNodeIds.add(edge.target);
  }
}

// 1-hop propagation → affected nodes & impacted edges
for (const edge of edges) {
  const sourceChanged = changedNodeIds.has(edge.source);
  const targetChanged = changedNodeIds.has(edge.target);
  if (sourceChanged || targetChanged) {
    impactedEdges.push(edge);
    if (sourceChanged && !changedNodeIds.has(edge.target)) affectedNodeIds.add(edge.target);
    if (targetChanged && !changedNodeIds.has(edge.source)) affectedNodeIds.add(edge.source);
  }
}

```

The traversal captures **impacted edges** where either the source or target is a changed node, then adds the opposite endpoint to the **affected nodes** set unless it is already marked as changed.

### Phase 3: Deriving Higher-Level Impact

The final phase aggregates low-level graph changes into architectural insights (lines 74–77 and 90–97).

- **Layer identification**: Filters architectural layers that contain any impacted node ID, revealing which subsystems are touched
- **Risk assessment**: Weighs node `complexity` (simple vs. complex), the number of crossed layers, and the downstream blast radius (≥ 5 affected nodes)
- **Report generation**: The `formatDiffAnalysis` function produces a markdown report listing changed components, affected components, impacted edges, affected layers, and unmapped files

The command also writes a **diff overlay** ([`.understand-anything/diff-overlay.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/diff-overlay.json)) that visualizes changed ↔ affected component relationships directly on the interactive dashboard.

## Risk Assessment Methodology

The `formatDiffAnalysis` function (lines 58–94) interprets collected data to classify change risk:

- **High complexity**: Flags when complex components (as defined in the knowledge graph) are modified
- **Cross-layer impact**: Alerts when changes span multiple architectural layers, indicating potential coupling issues
- **Wide blast radius**: Triggered when 5 or more downstream components are affected
- **Unmapped files**: Warns when modified files exist outside the knowledge graph coverage

If none of these conditions are met, the change is reported as **low-risk**.

## Using the /understand-diff Command

### Direct Library Integration

You can invoke the analysis programmatically using the utilities exported from [`understand-anything-plugin/src/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/index.ts):

```typescript
import { readFile } from "fs/promises";
import { buildDiffContext, formatDiffAnalysis } from "@understand-anything/skill";

// Load the persisted knowledge graph
const graphJson = await readFile("./.understand-anything/knowledge-graph.json", "utf-8");
const graph = JSON.parse(graphJson);

// Changed files from a CI job or git command
const changedFiles = [
  "src/api/userController.ts",
  "src/models/User.ts",
];

// Build context and generate report
const diffCtx = buildDiffContext(graph, changedFiles);
const report = formatDiffAnalysis(diffCtx);

console.log(report);

```

### Running via Claude Code

When invoked as a Claude Code skill per [`skills/understand-diff/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand-diff/SKILL.md), the agent:

1. Executes `git diff … --name-only` to obtain the `changedFiles` array
2. Loads [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json)
3. Calls `buildDiffContext(graph, changedFiles)` to identify nodes and edges
4. Renders the markdown analysis via `formatDiffAnalysis` for user review
5. Persists [`diff-overlay.json`](https://github.com/Lum1104/Understand-Anything/blob/main/diff-overlay.json) for dashboard visualization

### Expected Output Format

The generated markdown report includes structured sections:

```markdown

# Diff Analysis: MyProject

## Changed Components

- **UserController** (function) — Handles user-related HTTP routes
  - File: `src/api/userController.ts`
  - Complexity: complex

## Affected Components

These components are connected to changed code and may need attention:
- **AuthService** (service) — Auth utilities
- **UserRepository** (module) — Data access layer

## Affected Layers

- **Backend API**: Exposes public endpoints
- **Data Layer**: Persists domain objects

## Risk Assessment

- **High complexity**: 1 complex component changed: UserController
- **Cross-layer impact**: Changes span 2 architectural layers
- **Wide blast radius**: 4 components affected downstream

```

## Key Implementation Files

- **[`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts)**: Contains `buildDiffContext` and `formatDiffAnalysis`, implementing the three-phase mapping, propagation, and reporting logic
- **[`understand-anything-plugin/src/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/index.ts)**: Re-exports the diff analysis utilities for package consumers
- **[`understand-anything-plugin/skills/understand-diff/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-diff/SKILL.md)**: Defines the Claude Code skill interface, instructing agents on executing git commands and invoking the analysis pipeline
- **[`understand-anything-plugin/src/__tests__/diff-analyzer.test.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/__tests__/diff-analyzer.test.ts)**: Validates the accuracy of node mapping and edge traversal logic

## Summary

- The `/understand-diff` command maps Git diff output to knowledge graph nodes via `filePath` matching in `buildDiffContext`
- Impact propagates through one-hop edge traversal, identifying affected components while excluding already-changed nodes
- Risk assessment weighs component complexity, cross-layer dependencies, and blast radius (≥ 5 affected nodes) to categorize changes
- The analysis produces both human-readable markdown reports and machine-readable [`diff-overlay.json`](https://github.com/Lum1104/Understand-Anything/blob/main/diff-overlay.json) for visualization
- Implementation resides primarily in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts), lines 31–97

## Frequently Asked Questions

### How does `/understand-diff` identify which files have changed?

The command relies on standard Git commands (`git diff … --name-only`) to obtain the list of modified file paths. In `buildDiffContext` (lines 31–41), these paths are compared against the `filePath` field of each `GraphNode` in the persisted knowledge graph to establish the initial changed node set.

### What constitutes a "high-risk" change in the analysis?

According to the `formatDiffAnalysis` implementation (lines 58–94), high-risk changes are flagged when they involve complex components (as defined by the `complexity` property), span multiple architectural layers, or affect 5 or more downstream nodes (wide blast radius). The presence of unmapped files also contributes to elevated risk levels.

### Can the impact analysis be used outside of Claude Code?

Yes. The core logic is available as a Node.js library via the `@understand-anything/skill` package. Developers can import `buildDiffContext` and `formatDiffAnalysis` directly to integrate impact analysis into CI/CD pipelines, custom scripts, or other development tools, provided they supply the knowledge graph JSON and changed files list.

### What happens if a changed file isn't in the knowledge graph?

Files that do not match any `GraphNode.filePath` are collected as **unmapped files** and reported in the risk assessment section. While they do not participate in the graph traversal for affected components, their presence is flagged as a potential coverage gap or architectural blind spot requiring attention.