# How Egonex AI's /understand-diff Analyzes the Impact of Changes Before Committing

> Understand the impact of code changes before committing with Egonex AI's /understand-diff. It analyzes Git diffs against your project knowledge graph to prevent errors.

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

---

**Egonex AI's `/understand-diff` cross-references your Git diff against a project knowledge graph to map changed files, calculate ripple effects across 1-hop dependencies, and generate a risk assessment report before you commit.**

The `/understand-diff` skill in the `Egonex-AI/Understand-Anything` repository transforms raw Git diffs into actionable intelligence by analyzing how code changes propagate through your architecture. By examining the relationship between modified files and the project's knowledge graph stored in [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json), it identifies not just what changed, but what breaks downstream.

## The Three-Stage Impact Analysis Pipeline

The analysis engine in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts) processes changes through three tightly coupled stages to determine the blast radius of your modifications.

### Stage 1: Mapping Changed Files to Knowledge Graph Nodes

The process begins in `buildDiffContext` (lines 22-42) by executing `git diff --name-only` to capture the list of modified file paths. The algorithm greps each path against the knowledge graph JSON to identify corresponding *file* nodes and any nested *function* or *class* nodes. This step populates the `changedNodeIds` set and flags any paths absent from the graph as `unmappedFiles`, ensuring you know which parts of the codebase lack semantic coverage.

### Stage 2: Computing the Ripple Effect

Once direct mappings are established, the analyzer expands the scope to capture collateral impact through three specific mechanisms:

- **"Contains" expansion** (lines 44-49): The algorithm follows `contains` edges to mark all child nodes of changed files as modified. If you edit a file, every function and class defined within it is automatically flagged as changed.

- **1-hop neighbor discovery** (lines 53-70): The system traverses every edge in the graph. When either endpoint belongs to `changedNodeIds`, the edge is recorded in `impactedEdges` and the opposite endpoint—if not already marked as changed—is added to the *affected* nodes set. This captures immediate dependencies, imports, and relationships.

- **Layer aggregation** (lines 74-77): The analyzer identifies architectural *layers* whose `nodeIds` intersect with the combined set of changed and affected nodes. This reveals which high-level architectural concerns—such as "Data Layer" or "API Surface"—are impacted by your modifications.

### Stage 3: Risk Assessment and Markdown Rendering

The populated `DiffContext` is passed to `formatDiffAnalysis` (risk logic in lines 58-96) to produce a structured markdown report. The report organizes findings into six categories:

- **Changed Components**: Directly altered nodes with file paths and complexity metrics
- **Affected Components**: 1-hop downstream nodes that may require attention
- **Affected Layers**: Architectural layers spanning the changed code
- **Impacted Relationships**: Visual edge list showing `source --[type]--> target` connections
- **Unmapped Files**: Paths not yet represented in the knowledge graph
- **Risk Assessment**: Flags for high-complexity changes, cross-layer impact, wide blast radius, and unmapped files

## Programmatic Usage

You can invoke the analysis engine programmatically using the core API exported from the plugin.

```typescript
import { buildDiffContext, formatDiffAnalysis } from '@understand-anything/core';
import type { KnowledgeGraph } from '@understand-anything/core';

// Load your knowledge graph from .understand-anything/knowledge-graph.json
const graph: KnowledgeGraph = /* ... */;

// Changed files from git diff --name-only
const changedFiles = [
  'src/services/userService.ts',
  'src/utils/helpers.ts',
];

// Build the diff context (implements lines 22-88 in diff-analyzer.ts)
const diffCtx = buildDiffContext(graph, changedFiles);

// Generate markdown report (implements lines 92-199 in diff-analyzer.ts)
const markdown = formatDiffAnalysis(diffCtx);
console.log(markdown);

```

The `buildDiffContext` function implements the mapping and ripple-effect logic, while `formatDiffAnalysis` handles the final report generation.

## Dashboard Integration and Overlay Generation

Beyond markdown reports, the skill generates a machine-readable overlay for the visualization dashboard. The output is written to [`.understand-anything/diff-overlay.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/diff-overlay.json):

```json
{
  "version": "1.0.0",
  "baseBranch": "main",
  "generatedAt": "2026-06-20T14:32:10.123Z",
  "changedFiles": [
    "src/services/userService.ts",
    "src/utils/helpers.ts"
  ],
  "changedNodeIds": [
    "file:src/services/userService.ts",
    "class:src/services/userService.ts:UserService"
  ],
  "affectedNodeIds": [
    "function:src/middleware/auth.ts:verifyToken",
    "service:src/logger/logger.ts"
  ]
}

```

This JSON structure enables the dashboard to highlight changed nodes in red and affected nodes in yellow, providing visual confirmation of your change's blast radius.

## Summary

- **Graph-aware mapping**: `/understand-diff` converts file paths from `git diff` into semantic graph nodes using `buildDiffContext` in [`diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/diff-analyzer.ts).
- **Ripple effect calculation**: The algorithm expands changes through containment relationships (lines 44-49) and 1-hop neighbor discovery (lines 53-70) to identify collateral impact.
- **Architectural layer detection**: Changes are aggregated into affected architectural layers (lines 74-77) to reveal cross-cutting concerns.
- **Risk-based reporting**: `formatDiffAnalysis` generates markdown highlighting complexity, cross-layer impact, and unmapped files.
- **Dual output**: The skill produces both human-readable reports and JSON overlays for dashboard visualization.

## Frequently Asked Questions

### What is the knowledge graph in /understand-diff?

The knowledge graph is a JSON representation of your codebase's structure stored in [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). It contains *file* nodes, *function* and *class* nodes, and edges representing relationships like "contains," "imports," or "calls." The diff analyzer uses this graph to determine semantic relationships between changed files and the rest of the system.

### How does the ripple effect calculation work?

The ripple effect calculation uses three steps: first, it expands "contains" edges to mark child nodes as changed (lines 44-49); second, it performs 1-hop neighbor discovery by traversing all edges to find nodes directly connected to changes (lines 53-70); third, it identifies impacted architectural layers by checking which layer definitions include changed or affected nodes (lines 74-77).

### What risk factors does the analysis flag?

According to the risk assessment logic in `formatDiffAnalysis` (lines 58-96), the system flags four primary risk categories: **high complexity** when complex components are modified, **cross-layer impact** when changes span multiple architectural layers, **wide blast radius** when many downstream components are affected, and **unmapped files** when changed files lack representation in the knowledge graph.

### Can I use the diff analyzer outside of Claude Code?

Yes. While the skill definition in [`skills/understand-diff/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/skills/understand-diff/SKILL.md) provides instructions for Claude Code, the core logic is exported as a TypeScript API from `@understand-anything/core`. You can import `buildDiffContext` and `formatDiffAnalysis` in any Node.js application to integrate impact analysis into CI pipelines or custom Git hooks.