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

/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 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 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 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. 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:

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

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