# How to Perform Impact Analysis Across a Codebase Using /understand-diff

> Master codebase impact analysis with /understand-diff. Map git changes to your knowledge graph, identify affected components, and assess risk effectively. Boost your development workflow now.

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

---

**`/understand-diff`** is a built-in skill that leverages the knowledge graph from `/understand` to map git changes to graph nodes, compute one-hop relationships, and generate a `DiffContext` report showing affected components, architectural layers, and risk assessments.

The Egonex-AI/Understand-Anything repository provides intelligent code analysis through persistent knowledge graphs. By executing `/understand-diff`, developers can perform automated impact analysis across a codebase to identify downstream breakages and architectural risks before merging changes.

## How /understand-diff Maps Changes to Architecture

The impact analysis process implemented in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts) consists of three logical phases that transform raw file changes into structured architectural insights.

### Phase 1: Gather the Change Set

The workflow begins by obtaining the list of modified file paths from git. This includes uncommitted changes, feature-branch diffs, or pull request modifications. The skill accepts any standard git diff source to establish the initial change boundary for analysis.

### Phase 2: Map Files to Graph Nodes

The `buildDiffContext` function loads the persisted knowledge graph from [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) and performs path matching. For each changed file, it locates nodes where the `filePath` property matches and automatically includes "contains" children—such as functions or classes defined within the changed file.

### Phase 3: Compute the Ripple Effect

For every changed node, the analyzer traverses the edge list to collect all **one-hop neighbors**. It identifies **impacted edges** (relationships crossing the changed boundary) and aggregates **affected layers** (architectural zones containing impacted nodes). This computation produces a complete `DiffContext` object that quantifies the blast radius of the change.

## Analyzing the DiffContext Output Structure

The `DiffContext` object generated by `buildDiffContext` contains specific fields that precisely quantify the scope of impact across your codebase:

- **`changedFiles`**: The list of files directly modified in the git diff
- **`unmappedFiles`**: Files present in the diff but not represented in the knowledge graph
- **`changedNodes`**: Graph nodes corresponding to directly edited components (files, functions, classes)
- **`affectedNodes`**: Downstream or upstream components connected by one-hop relationships
- **`impactedEdges`**: Specific relationships that cross the boundary between changed and unchanged nodes
- **`affectedLayers`**: Architectural layers (e.g., "Domain", "Data") that contain any affected nodes

## Generating Impact Reports with formatDiffAnalysis

The `formatDiffAnalysis` function in [`diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/diff-analyzer.ts) converts the `DiffContext` into a structured markdown report. This report includes several critical sections for code reviewers:

**Changed Components** display the name, type, summary, file path, and complexity metrics for each directly modified node.

**Affected Components** list downstream nodes that could potentially break due to dependency relationships.

**Affected Layers** identify which architectural zones see activity, helping reviewers understand cross-layer coupling and violations.

**Risk Assessment** calculates overall risk based on node complexity, cross-layer count, blast radius size, and the presence of unmapped files.

## Persisting Results for Dashboard Visualization

After analysis, the skill writes a concise overlay to [`.understand-anything/diff-overlay.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/diff-overlay.json). This file contains metadata including `version`, `baseBranch`, and `generatedAt` timestamp, plus arrays of `changedNodeIds` and `affectedNodeIds`.

The dashboard consumes this overlay to visually render the diff graph, highlighting the affected subgraph within the broader codebase architecture and enabling interactive exploration of the impact boundary.

## Complete Implementation Example

The following TypeScript implementation demonstrates how to programmatically execute impact analysis across a codebase using the core functions:

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

// 1️⃣ Load the knowledge graph (produced by `/understand`)
const graph: KnowledgeGraph = JSON.parse(
  await readFile(".understand-anything/knowledge-graph.json", "utf-8")
);

// 2️⃣ Obtain the list of changed files (example for a feature branch)
const changedFiles = await exec("git diff main...HEAD --name-only");

// 3️⃣ Build the diff context
const ctx = buildDiffContext(graph, changedFiles.split("\n").filter(Boolean));

// 4️⃣ Render a markdown analysis (can be sent back to Claude Code)
const report = formatDiffAnalysis(ctx);
console.log(report);

// 5️⃣ Persist a diff overlay for the dashboard
await writeFile(
  ".understand-anything/diff-overlay.json",
  JSON.stringify({
    version: "1.0.0",
    baseBranch: "main",
    generatedAt: new Date().toISOString(),
    changedFiles: ctx.changedFiles,
    changedNodeIds: ctx.changedNodes.map((n) => n.id),
    affectedNodeIds: ctx.affectedNodes.map((n) => n.id),
  }, null, 2)
);

```

## Summary

- **`/understand-diff`** leverages the knowledge graph from `/understand` to map code changes to architectural components according to the Egonex-AI/Understand-Anything source code.
- The **`buildDiffContext`** function in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts) executes a three-phase workflow: gather changes, map to nodes, and compute ripple effects.
- Output includes **`changedNodes`**, **`affectedNodes`**, **`impactedEdges`**, and **`affectedLayers`** for comprehensive impact assessment.
- **`formatDiffAnalysis`** generates markdown reports with risk assessments based on complexity and cross-layer dependencies.
- Results persist to **[`.understand-anything/diff-overlay.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/diff-overlay.json)** for visual dashboard rendering.

## Frequently Asked Questions

### Where is the buildDiffContext function implemented?

The `buildDiffContext` function is implemented in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts). This file also contains the `formatDiffAnalysis` function responsible for rendering markdown reports from the `DiffContext` object.

### How does /understand-diff handle files not in the knowledge graph?

The analyzer tracks unmapped files separately in the `unmappedFiles` field of the `DiffContext` object. These files appear in the git diff but lack corresponding nodes in [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json), and their presence contributes to higher risk assessments in the final report.

### What determines the risk assessment in the impact report?

Risk assessment calculates severity based on four factors: the complexity metrics of changed nodes, the count of cross-layer dependencies, the total blast radius (number of affected nodes), and the presence of unmapped files that cannot be analyzed against the graph.

### Can /understand-diff analyze changes between specific branches?

Yes, the skill accepts any standard git diff source. You can analyze changes between specific branches by passing the appropriate git command output—such as `git diff main...feature-branch --name-only`—to the `buildDiffContext` function as the `changedFiles` array.