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

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

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:

{
  "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.
• 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. 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 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.

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