# How the /understand-diff Command Analyzes Impact of Changes in Understand-Anything

> Discover how /understand-diff analyzes change impact using deterministic graph-based dependency propagation and risk assessments for Egonex-AI/Understand-Anything.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-24

---

**The `/understand-diff` command performs deterministic graph-based impact analysis by mapping changed files to knowledge graph nodes, propagating dependencies one hop through the graph, and generating a structured markdown report with risk assessments.**

The `/understand-diff` command is a built-in skill in the Understand-Anything agent that transforms raw git diffs into architectural impact assessments. By leveraging the project's knowledge graph stored in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts), it traces how code modifications ripple through dependencies to surface hidden risks and affected components. This analysis helps developers understand the blast radius of changes before they reach production.

## Mapping Changed Files to Knowledge Graph Nodes

### Input Processing with buildDiffContext

The analysis begins in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts) where the `buildDiffContext` function receives a list of changed file paths from `git diff --name-only` or a PR diff. The function iterates over every node in `graph.nodes` and matches `node.filePath` against the changed file list, storing matched IDs in `changedNodeIds` while recording unmapped files separately (lines 31-42).

### Including Child Nodes via Containment Edges

To ensure comprehensive coverage, the algorithm includes child components contained within changed files. For every edge of type `contains` where the source node is a changed file, the target child node—such as functions or classes—is added to `changedNodeIds` (lines 44-49). This captures both the file-level changes and their internal constituents.

## One-Hop Impact Propagation Algorithm

After identifying directly changed nodes, the system performs **one-hop impact propagation**. The algorithm scans all edges in the knowledge graph, and if an edge touches any changed node (either as source or target), it adds the edge to `impactedEdges`. The opposite endpoint of each such edge—provided it isn't already marked as changed—is added to `affectedNodeIds` (lines 57-69). This yields the complete set of **affected components** that depend on or are depended upon by the changed code.

## Architectural Layer Analysis and Risk Assessment

### Deriving Affected Layers

The `allImpactedIds` set unites both changed and affected node IDs. The system then filters the `layers` array to retain only those layers whose `nodeIds` intersect with this impacted set (lines 74-77). This reveals which architectural layers—such as Service Layer or Data Layer—are touched by the modification.

### Generating the Markdown Report

The `formatDiffAnalysis` function consumes the `DiffContext` to emit a structured markdown report containing sections for changed components, affected components, impacted layers, and unmapped files. The report includes a **risk assessment** that flags high-complexity changes, cross-layer impact, large blast radius, and unmapped files (lines 58-94).

## Practical Implementation Example

To programmatically analyze a diff using the Understand-Anything core library:

```typescript
import { buildDiffContext, formatDiffAnalysis } from "./diff-analyzer.js";
import type { KnowledgeGraph } from "@understand-anything/core";

// 1️⃣ Load the knowledge graph generated by /understand
const graph: KnowledgeGraph = await import(
  "./.understand-anything/knowledge-graph.json"
);

// 2️⃣ Collect changed files (example for a PR)
const changedFiles = ["src/service.ts", "src/db.ts"];

// 3️⃣ Build the diff context
const ctx = buildDiffContext(graph, changedFiles);

// 4️⃣ Render a markdown report
const markdown = formatDiffAnalysis(ctx);
console.log(markdown);

```

Running this snippet produces a markdown document structured as follows:

```markdown

# Diff Analysis: test-project

## Changed Components

- **service.ts** (file) — Service
  - File: `src/service.ts`
  - Complexity: complex

## Affected Components

- **routes.ts** (file) — Routes
- **db.ts** (file) — Database

## Affected Layers

- **Service Layer**: Business logic
- **Data Layer**: Database

## Risk Assessment

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

```

## Summary

- **`buildDiffContext`** in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts) performs the core graph mapping by matching changed files to nodes and including child components via `contains` edges.
- **One-hop impact propagation** identifies affected nodes by scanning all edges touching changed nodes, revealing dependencies one level away from the modification.
- **Layer filtering** intersects impacted node IDs with architectural layer definitions to show which system layers are affected.
- **`formatDiffAnalysis`** generates a human-readable markdown report with risk indicators for complexity, cross-layer impact, and blast radius.
- The skill orchestration is defined in [`understand-anything-plugin/skills/understand-diff/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-diff/SKILL.md), guiding the agent through diff acquisition and analysis assembly.

## Frequently Asked Questions

### How does /understand-diff determine which components are affected by a change?

The command uses **one-hop impact propagation** by scanning all edges in the knowledge graph. If an edge connects to a changed node—whether as source or target—the opposite endpoint is marked as affected. This catches immediate dependencies and dependents without traversing the entire graph, providing a focused blast radius analysis.

### What is the difference between changed nodes and affected nodes in the analysis?

**Changed nodes** represent files and their internal components (functions, classes) that appear in the git diff. **Affected nodes** are components one edge away from changed nodes—those that import, extend, or are imported by the changed code. The distinction helps reviewers separate the modified code from its downstream impact.

### Where does /understand-diff get the knowledge graph data?

The skill reads the [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) file generated by the `/understand` command, typically located at [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). This JSON contains the complete graph structure including nodes, edges, and layer definitions required for impact analysis.

### How does the risk assessment flag high-risk changes?

The `formatDiffAnalysis` function evaluates four specific criteria: **high complexity** (components marked as complex), **cross-layer impact** (changes spanning multiple architectural layers), **wide blast radius** (large number of affected components), and **unmapped files** (changed files not present in the knowledge graph). Each trigger generates a specific warning in the markdown output.