Impact Analysis - GitNexus

When to Use This Skill

Use the Impact Analysis skill when you need to:

Assess safety before changing code
Understand what depends on a function or class
Calculate blast radius of a change
Determine who uses specific code
Review changes before committing
Plan refactoring work

Example Scenarios

Is it safe to change this function?

Use gitnexus_impact({target: "functionName", direction: "upstream"}) to find all dependents at different depths.

What will break if I modify X?

Check d=1 (direct) dependents—these will definitely break. Review d=2 for likely affected code.

Show me the blast radius

Use impact with maxDepth: 3 to see transitive dependencies up to 3 hops away.

Who uses this code?

Use context to see incoming references categorized by type (CALLS, IMPORTS, EXTENDS).

Workflow

Follow these steps for thorough impact analysis:

Step-by-Step Guide

1. Analyze Symbol Blast Radius

gitnexus_impact({
  target: "validateUser",
  direction: "upstream",
  minConfidence: 0.8,
  maxDepth: 3
})

Returns depth-grouped dependencies:

TARGET: Function validateUser (src/auth/validate.ts:15)

UPSTREAM (what depends on this):
  Depth 1 (WILL BREAK):
    - loginHandler [CALLS, 100%] → src/auth/login.ts:42
    - apiMiddleware [CALLS, 100%] → src/api/middleware.ts:15
  
  Depth 2 (LIKELY AFFECTED):
    - authRouter [CALLS, 95%] → src/routes/auth.ts:22
    - sessionManager [CALLS, 90%] → src/session/manager.ts:33

2. Check Affected Processes

READ gitnexus://repo/{name}/processes

Find which execution flows touch the target symbol:

LoginFlow
TokenRefresh
APIMiddlewarePipeline

3. Pre-Commit Change Detection Before committing, map your git changes to affected processes:

gitnexus_detect_changes({scope: "staged"})

Returns:

{
  summary: {
    changed_count: 5,
    affected_count: 3,
    changed_files: 3,
    risk_level: "medium"
  },
  changed_symbols: ["validateUser", "AuthService", ...],
  affected_processes: ["LoginFlow", "TokenRefresh", ...]
}

4. Assess Risk Use the decision matrix below to determine risk level.

Checklist

gitnexus_impact({target, direction: "upstream"}) to find dependents
Review d=1 items first (these WILL BREAK)
Check high-confidence (>0.8) dependencies
READ processes to check affected execution flows
gitnexus_detect_changes() for pre-commit check
Assess risk level and report to user

Understanding Impact Output

Depth Levels

Depth	Risk Level	Meaning	Action Required
d=1	WILL BREAK	Direct callers/importers	Must update these
d=2	LIKELY AFFECTED	Indirect dependencies	Should review these
d=3	MAY NEED TESTING	Transitive effects	Run tests for these

Confidence Scores

GitNexus assigns confidence to each relationship:

100%: Direct static call or import
90-99%: Highly likely (named reference in same module)
80-89%: Probable (string reference or dynamic import)
Under 80%: Filtered out by default (use minConfidence to adjust)

Relationship Types

Type	Meaning	Example
`CALLS`	Direct function call	`login()` calls `validateUser()`
`IMPORTS`	Module import	`import { validateUser } from './auth'`
`EXTENDS`	Class inheritance	`class Admin extends User`
`IMPLEMENTS`	Interface implementation	`class AuthService implements IAuth`

Risk Assessment Matrix

Affected Symbols	Affected Processes	Risk Level
Under 5 symbols	0-1 processes	LOW
5-15 symbols	2-5 processes	MEDIUM
Over 15 symbols	Over 5 processes	HIGH
Any in critical path	Auth, payments, core	CRITICAL

Critical paths include:

Authentication flows
Payment processing
Data persistence
Security middleware
API gateway functions

Tools for Impact Analysis

gitnexus_impact

The primary tool for blast radius analysis:

gitnexus_impact({
  target: "validateUser",
  direction: "upstream",      // or "downstream" for dependencies
  minConfidence: 0.8,          // filter low-confidence refs
  maxDepth: 3,                 // how deep to traverse
  relationTypes: ["CALLS"],    // optional: filter by relation type
  includeTests: false          // optional: exclude test files
})

Returns:

{
  target: {
    uid: "Function:validateUser",
    filePath: "src/auth/validate.ts",
    startLine: 15
  },
  upstream: {
    depth_1: [
      {
        symbol: "loginHandler",
        filePath: "src/auth/login.ts",
        line: 42,
        relationType: "CALLS",
        confidence: 1.0
      }
    ],
    depth_2: [...],
    depth_3: [...]
  },
  summary: {
    total_affected: 12,
    by_depth: {d1: 2, d2: 5, d3: 5}
  }
}

Parameters:

direction:
- "upstream" → what depends on this (callers)
- "downstream" → what this depends on (callees)
maxDepth: 1-3 recommended (higher = slower + more noise)
minConfidence: 0.8 recommended (lower = more false positives)

gitnexus_detect_changes

Git-diff based impact analysis:

gitnexus_detect_changes({
  scope: "staged"  // or "all" or "unstaged"
})

Returns:

{
  summary: {
    changed_count: 12,        // symbols you modified
    affected_count: 8,        // additional symbols affected
    changed_files: 4,
    risk_level: "medium"      // low/medium/high/critical
  },
  changed_symbols: [
    {
      name: "validateUser",
      filePath: "src/auth/validate.ts",
      changeType: "modified"
    }
  ],
  affected_processes: [
    {
      name: "LoginFlow",
      affected_steps: [2, 3],
      total_steps: 7
    }
  ]
}

Best for:

Pre-commit checks
Understanding scope of current changes
Identifying affected test suites

gitnexus_context

For simple “who calls this” queries:

gitnexus_context({name: "validateUser"})

Use context when you need categorized references (calls vs imports vs extends). Use impact when you need depth-grouped blast radius.

Example: “What breaks if I change validateUser?”

Here’s a complete impact analysis walkthrough:

Step 1: Analyze Blast Radius

gitnexus_impact({
  target: "validateUser",
  direction: "upstream",
  minConfidence: 0.8,
  maxDepth: 3
})

Result:

TARGET: Function validateUser (src/auth/validate.ts:15)

UPSTREAM DEPENDENCIES:
  Depth 1 (WILL BREAK):
    - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
    - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]

  Depth 2 (LIKELY AFFECTED):
    - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
    - sessionManager (src/session/manager.ts:33) [CALLS, 90%]
    - testAuthFlow (tests/auth.test.ts:18) [CALLS, 85%]

  Depth 3 (MAY NEED TESTING):
    - app (src/index.ts:12) [IMPORTS, 80%]

Summary: 6 total dependencies (2 direct, 4 indirect)

Step 2: Check Affected Processes

READ gitnexus://repo/my-app/processes

Processes that touch validateUser:

LoginFlow (step 2/7)
TokenRefresh (step 1/3)

Step 3: Assess Risk

Using the risk matrix:

Affected symbols: 6 (within MEDIUM range)
Affected processes: 2 (within MEDIUM range)
Critical path: Yes (LoginFlow is authentication)

Risk Level: HIGH (bumped from MEDIUM due to critical path)

Step 4: Recommendations

Report:

Changing validateUser will affect:

2 direct callers (loginHandler, apiMiddleware) → will break

2 indirect callers (authRouter, sessionManager) → likely affected

2 execution flows (LoginFlow, TokenRefresh)

Risk: HIGH (authentication is a critical path) Recommended actions:

Update loginHandler and apiMiddleware to match new signature

Review authRouter and sessionManager for compatibility

Run full auth test suite

Regression test: LoginFlow and TokenRefresh

Advanced Techniques

Finding All Callers Across the Codebase

MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
RETURN caller.name, caller.filePath
ORDER BY caller.filePath

Finding High-Impact Symbols

MATCH (f:Function)<-[r:CodeRelation {type: 'CALLS'}]-(caller)
WITH f, COUNT(caller) as callerCount
WHERE callerCount > 10
RETURN f.name, f.filePath, callerCount
ORDER BY callerCount DESC

Comparing Two Symbols

Run impact on both and compare the results:

const impact1 = gitnexus_impact({target: "funcA", direction: "upstream"})
const impact2 = gitnexus_impact({target: "funcB", direction: "upstream"})

// Compare total_affected to see which has larger blast radius

Best Practices

Always Check d=1 First

Depth 1 dependencies will break—these are your highest priority.

Use detect_changes Before Commits

Run pre-commit checks to understand the full scope of your changes.

Watch for Critical Paths

Changes to auth, payments, or core systems require extra scrutiny.

Trust Confidence Scores

Focus on >80% confidence—lower scores may be false positives.

Pre-Commit Workflow

Before committing changes, follow this workflow:

# 1. Stage your changes
git add .

# 2. Run impact detection
gitnexus_detect_changes({scope: "staged"})

# 3. Review affected processes and symbols

# 4. Run tests for affected processes
npm test -- LoginFlow TokenRefresh

# 5. Commit if all tests pass
git commit -m "Update validateUser signature"

Common Pitfalls

Ignoring d=2 Dependencies

Even if d=2 won’t immediately break, they’re likely affected. Always review them.

Not Checking Processes

A change might affect only 2 symbols but break 5 execution flows—always check processes.

Trusting Low Confidence

Confidence below 80% may be false positives (string references, dynamic imports). Review carefully.

Forgetting Test Files

By default, impact excludes tests. Use includeTests: true if you want to see test dependencies.

Next Steps

Learn Safe Refactoring

Once you understand impact, learn how to safely refactor code with automated rename

Get Started

Core Concepts

CLI Usage

MCP Integration

Agent Skills

Web UI

Advanced

​When to Use This Skill

​Example Scenarios

​Workflow

​Step-by-Step Guide

​Checklist

​Understanding Impact Output

​Depth Levels

​Confidence Scores

​Relationship Types

​Risk Assessment Matrix

​Tools for Impact Analysis

​gitnexus_impact

​gitnexus_detect_changes

​gitnexus_context

​Example: “What breaks if I change validateUser?”

​Step 1: Analyze Blast Radius

​Step 2: Check Affected Processes

​Step 3: Assess Risk

​Step 4: Recommendations

​Advanced Techniques

​Finding All Callers Across the Codebase

​Finding High-Impact Symbols

​Comparing Two Symbols

​Best Practices

Always Check d=1 First

Use detect_changes Before Commits

Watch for Critical Paths

Trust Confidence Scores

​Pre-Commit Workflow

​Common Pitfalls

​Ignoring d=2 Dependencies

​Not Checking Processes

​Trusting Low Confidence

​Forgetting Test Files

​Next Steps

Learn Safe Refactoring

Build docs developers (and LLMs) love

When to Use This Skill

Example Scenarios

Workflow

Step-by-Step Guide

Checklist

Understanding Impact Output

Depth Levels

Confidence Scores

Relationship Types

Risk Assessment Matrix

Tools for Impact Analysis

gitnexus_impact

gitnexus_detect_changes

gitnexus_context

Example: “What breaks if I change validateUser?”

Step 1: Analyze Blast Radius

Step 2: Check Affected Processes

Step 3: Assess Risk

Step 4: Recommendations

Advanced Techniques

Finding All Callers Across the Codebase

Finding High-Impact Symbols

Comparing Two Symbols

Best Practices

Pre-Commit Workflow

Common Pitfalls

Ignoring d=2 Dependencies

Not Checking Processes

Trusting Low Confidence

Forgetting Test Files

Next Steps