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

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, 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 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:

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:

# 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 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, 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 file generated by the /understand command, typically located at .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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}