Understand Change Impact Before You Edit

Map every file that depends on your code before you change a single line.

Step 1: Run graph_neighbors() to See Direct Imports

graph_neighbors() returns the immediate import graph for a file — what it imports and what imports it. This is your first cut at understanding a file's surface area. Run it on any file you're about to touch.

graph_neighbors("src/auth/middleware.py")

The response shows two lists: imports (files this module depends on) and imported_by (files that depend on this module). The second list is where your risk lives.

Step 2: Run graph_impact() for Full Blast Radius

Direct neighbors only show depth 1. graph_impact() walks the full dependency tree and returns every file that transitively depends on your target. Set max_depth to control how far it traverses.

graph_impact("src/auth/middleware.py", max_depth=5)

Expect a ranked list of affected files with their dependency depth. A file at depth 1 is directly exposed. A file at depth 4 is four hops away — still affected, but less immediately.

Step 3: Interpret the Dependency Depth Output

The output groups files by depth tier. Depth 1 files break immediately if your interface changes. Depth 2 and beyond break if their intermediaries change behavior. Read the depth tiers as concentric blast rings — innermost ring first.

Depth 1: src/api/routes.py, src/api/middleware_chain.py
Depth 2: src/api/v2/endpoints.py, tests/test_routes.py
Depth 3: src/app.py
Depth 4: tests/integration/test_app.py

Any test files in the output tell you exactly which test suite to run after your change. Any entry point files (like app.py or main.py) at depth 3+ signal system-wide exposure.

Step 4: Use Impact Analysis Before a Refactor

Before renaming a function, splitting a module, or changing a return type — run graph_impact() first. The output becomes your refactor checklist. Every file in the list is a call site or downstream consumer you need to audit or update.

graph_impact("src/utils/token_validator.py", max_depth=4)

Work top-down: fix depth-1 files first, then verify depth-2 files still compile, then run integration tests that cover depth-3+ entry points. This order prevents cascading failures mid-refactor.

Step 5: Combine Impact Analysis with Semantic Search

The dependency graph tells you which files are affected. Semantic search tells you how they use your code. Run both together to build a complete picture before any significant change.

graph_impact("src/auth/token.py", max_depth=3)
search_code("token validation error handling")

The graph_impact() call surfaces the structural exposure. The search_code() call finds the behavioral patterns — callers that rely on specific error types, return shapes, or side effects that won't show up in import graphs alone.