Impact Flow

Impact Flow Analysis

Analyze codebase dependencies, measure change impact, score health, and trace execution paths.

Token Efficiency Note

This skill uses Serena MCP as the primary tool for significant cost savings:

Always try Serena first, then fall back to native tools if Serena fails.

Mode Selection

Determine the analysis mode from user intent:

If mode is ambiguous, ask: "Would you like me to analyze dependencies, impact, health, execution flow, or run a comprehensive analysis?"

Mode 1: Dependency Graph

Goal: Visualize who imports what across the codebase.

Workflow

1. Activate project (if using Serena)

   → activate_project(project_name)
   → check_onboarding_performed()
   

2. Identify scope

   • Single file: Analyze that file's exports and imports
   • Directory: Analyze all code files in directory
   • Whole codebase: Start from entry points or high-level modules

3. Collect exports (parallel where possible)

   PRIMARY (Serena):
   For each file in scope:
     → get_symbols_overview(relative_path=file, depth=0)
     → Record exported classes, functions, constants
   
   FALLBACK (Native):
   For each file in scope:
     → Grep pattern="^(def |class |export |function )" glob="*.py"
     → Parse results to extract symbol names
   

4. Trace references (parallel per symbol)

   PRIMARY (Serena):
   For each exported symbol:
     → find_referencing_symbols(name_path=symbol, relative_path=file)
     → Record: importer_file → symbol → source_file
   
   FALLBACK (Native):
   For each exported symbol:
     → Grep pattern="symbol_name\s*\(" path=scope
     → Filter to exclude definition line
   

5. Build adjacency list

   graph = {}
   for each reference:
     graph[importer] = graph.get(importer, []) + [imported]
   

6. Calculate coupling metrics

   • Afferent coupling (Ca): Number of files that depend on this file
   • Efferent coupling (Ce): Number of files this file depends on
   • Instability (I): Ce / (Ca + Ce) — 0=stable, 1=unstable

7. Generate output

   • Mermaid diagram (see references/report-templates.md)
   • High-coupling warnings (Ca > 10 or Ce > 10)
   • Cycle detection (if A→B and B→A)

Output Format

## Dependency Graph: [scope]

### Visualization
```mermaid
graph LR
    A[module_a] --> B[module_b]
    A --> C[module_c]
    B --> C

Coupling Analysis

Warnings

• ⚠️ module_a has high efferent coupling (depends on many modules)
• 🔄 Cycle detected: module_x ↔ module_y

---

## Mode 2: Blast Radius

**Goal**: Assess impact of changing a specific symbol or file.

### Workflow

1. **Locate target**

PRIMARY (Serena): → find_symbol(name_path_pattern=symbol, relative_path=file, include_body=false) → Confirm: "Analyzing impact of [symbol] in [file]"

FALLBACK (Native): → Grep pattern="(def|class|function)\s+symbol_name" path=scope → Read file to get context

2. **Collect direct dependents (depth 1)**

PRIMARY (Serena): → find_referencing_symbols(name_path=target, relative_path=file) → Store as level_1_refs

FALLBACK (Native): → Grep pattern="symbol_name\s*[(.]" path=scope output_mode=content → Parse file:line from results

3. **Recurse to configured depth** (default: 3)

For depth 2..N: For each ref in previous_level: → find_referencing_symbols(name_path=ref.symbol, relative_path=ref.file) → Store as level_N_refs Stop early if no new refs found

4. **Calculate blast radius metrics**
- `affected_files`: Unique files containing references
- `total_files`: Count from list_dir(recursive=true)
- `blast_percentage`: affected_files / total_files * 100

5. **Assign risk level**
| Percentage | Risk | Recommendation |
|------------|------|----------------|
| >30% | 🔴 Critical | Requires extensive testing, consider feature flag |
| 15-30% | 🟠 High | Integration tests required, staged rollout |
| 5-15% | 🟡 Medium | Unit tests + affected component tests |
| <5% | 🟢 Low | Standard testing sufficient |

6. **Generate impact tree** (see `references/report-templates.md`)

### Output Format

```markdown
## Blast Radius: `function_name`

**Risk Level**: 🟠 High (22% of codebase affected)

### Impact Tree

function_name (target) ├── caller_a.py:45 [DIRECT] │ ├── handler_x.py:102 │ └── handler_y.py:88 ├── caller_b.py:33 [DIRECT] │ └── main.py:15 └── caller_c.py:78 [DIRECT]

### Summary
- **Direct callers**: 3 files
- **Indirect callers**: 4 files
- **Total affected**: 7 files (22% of 32 code files)

### Recommendations
1. Write tests for `caller_a`, `caller_b`, `caller_c` before modifying
2. Consider staged rollout given handler dependencies
3. Review `handler_x` and `handler_y` for interface assumptions

Mode 3: Health Score

Goal: Generate unified A-F health grade for codebase or directory.

Workflow

1. Collect metrics in parallel:

   Task A: Count files
     PRIMARY: list_dir(relative_path=scope, recursive=true)
     FALLBACK: Glob pattern="**/*.py" (or appropriate extension)
   
   Task B: Count symbols
     PRIMARY: get_symbols_overview on sample files (up to 20)
     FALLBACK: Grep pattern="^(def |class )" output_mode=count
   
   Task C: Find dead code
     PRIMARY: exports with 0 references via find_referencing_symbols
     FALLBACK: Skip or use heuristics
   
   Task D: Check test coverage
     → Ratio of test files (test_*.py, *_test.py, *.spec.*)
   
   Task E: Check documentation
     PRIMARY: find_symbol with include_info=true, check for docstrings
     FALLBACK: Grep pattern='"""' or pattern="'''" for docstrings
   

2. Calculate component scores (see references/health-metrics.md for formulas)

   Metric	Weight	Calculation
   Coupling	25%	100 - (avg_refs_per_export * 5), min 0
   Complexity	25%	100 - (avg_branches_per_function * 3), min 0
   Dead Code	20%	100 - (dead_exports / total_exports * 100)
   Test Coverage	15%	(test_files / code_files) * 100, max 100
   Documentation	15%	(documented_symbols / total_symbols) * 100

3. Compute composite score

   score = Σ(metric_score * weight)
   

4. Assign grade

   Score	Grade	Description
   90-100	A	Excellent - Well-maintained, low debt
   80-89	B	Good - Minor issues, sustainable
   70-79	C	Fair - Notable tech debt, plan improvements
   60-69	D	Poor - Significant issues, prioritize fixes
   <60	F	Critical - Major refactoring needed

5. Identify top issues (lowest-scoring metrics)

Output Format

## Health Score: [scope]

# Grade: B (84/100)

### Metric Breakdown
| Metric | Score | Weight | Weighted |
|--------|-------|--------|----------|
| Coupling | 78 | 25% | 19.5 |
| Complexity | 85 | 25% | 21.25 |
| Dead Code | 92 | 20% | 18.4 |
| Test Coverage | 80 | 15% | 12.0 |
| Documentation | 86 | 15% | 12.9 |
| **Total** | | | **84.05** |

### Top Issues
1. **Coupling** (78): `auth/permissions.py` has 15 dependents
2. **Test Coverage** (80): `utils/` directory has no tests

### Recommendations
1. Extract interface from `auth/permissions.py` to reduce coupling
2. Add unit tests for utility functions

Mode 4: Flow Trace

Goal: Trace execution path from entry point through call tree.

Workflow

1. Identify entry point

   PRIMARY (Serena):
   → find_symbol(name_path_pattern=entry_function, relative_path=file, include_body=true)
   → Parse function body for called functions
   
   FALLBACK (Native):
   → Read file containing entry point
   → Use regex to extract function calls
   

2. Extract calls from body

   • Look for: function calls, method calls, constructor calls
   • Pattern: identifier( or self.method( or ClassName(

3. Recursively trace (with cycle detection)

   visited = set()
   
   def trace(symbol, depth):
     if symbol in visited or depth > max_depth:
       return "[CYCLE]" or "[MAX DEPTH]"
     visited.add(symbol)
   
     body = find_symbol(name_path_pattern=symbol, include_body=true)
     calls = extract_calls(body)
   
     for call in calls:
       trace(call, depth + 1)
   

4. Build call tree with depth indicators

5. Annotate with metadata

   • File locations
   • Async/sync markers (look for async def, await)
   • External dependency markers (imports from packages)

Output Format

## Flow Trace: `process_request`

### Call Tree

process_request(request) → handlers/main.py:45 ├── validate_input(request.data) → validators/input.py:12 │ ├── check_schema(data) → validators/schema.py:33 │ └── sanitize(data) → utils/sanitize.py:8 ├── authenticate(request.headers) → auth/authenticate.py:22 │ ├── decode_token(token) → auth/jwt.py:15 [EXTERNAL: pyjwt] │ └── get_user(user_id) → db/users.py:44 [ASYNC] └── handle_action(user, data) → handlers/actions.py:88 └── save_result(result) → db/storage.py:102 [ASYNC]

### Flow Summary
- **Total calls**: 8
- **Unique functions**: 8
- **External dependencies**: pyjwt
- **Async boundaries**: 2 (get_user, save_result)

### Notes
- Authentication happens before action handling
- Two database calls could be parallelized

Mode 5: Comprehensive Analysis

Goal: Run all modes and generate unified report.

Workflow

1. Run Health Score first (establishes baseline)

   → Execute Mode 3 workflow
   → Store health_grade, metrics, top_issues
   

2. Run Dependency Graph (structural context)

   → Execute Mode 1 workflow
   → Store graph, coupling_data, cycles
   

3. Identify high-risk symbols from coupling data

   high_risk_symbols = [
     symbols where Ca > 10 OR
     symbols in cycles OR
     symbols flagged in top_issues
   ]
   

4. Run Blast Radius on top 3 high-risk symbols

   For each high_risk_symbol (limit 3):
     → Execute Mode 2 workflow
     → Store impact_data
   

5. Run Flow Trace on main entry point(s)

   → Find entry points: main(), app(), handler patterns
   → Execute Mode 4 workflow on primary entry
   → Store call_tree
   

6. Compile unified report

   → Executive summary with grade and key metrics
   → Dependency visualization
   → Impact analysis for high-risk areas
   → Execution flow overview
   → Prioritized recommendations
   

Output Format

See the report generated during testing for a complete example. Key sections:

# Impact Flow Analysis Report: [project]

## Executive Summary
| Metric | Value | Status |
|--------|-------|--------|
| Health Grade | [A-F] | [status] |
| Total LOC | [N] | |
| Coupling Level | [Low/Med/High] | |
| Code Duplication | [Low/Med/High] | |

## Mode 1: Dependency Graph
[Graph output]

## Mode 2: Blast Radius Analysis
[Impact trees for high-risk symbols]

## Mode 3: Health Score
[Detailed metrics]

## Mode 4: Flow Trace
[Call trees]

## Recommendations
[Prioritized action items]

Tool Reference

Primary Tools (Serena MCP) — Use First

Important Parameter Notes:

• Use name_path_pattern (not name_path) for find_symbol
• Use substring_matching=true for partial symbol names
• Set include_body=false unless you need the full code (saves tokens)

Fallback Tools (Claude Code Native) — Use When Serena Fails

Fallback Decision Logic

try:
    result = serena_tool(params)
    if result is empty or error:
        raise FallbackNeeded
except (Error, FallbackNeeded):
    result = native_tool(equivalent_params)

Language-Specific Patterns

Python

Import detection: ^(from\s+\S+\s+import|import\s+)
Entry points: if __name__ == "__main__"
Test files: test_*.py, *_test.py, tests/
Docstrings: """...""" or '''...'''

TypeScript/JavaScript

Import detection: ^import\s+|^const\s+\w+\s*=\s*require\(
Entry points: package.json main/bin fields
Test files: *.test.ts, *.spec.ts, __tests__/

Rust

Import detection: ^use\s+
Entry points: fn main() in src/main.rs or src/bin/
Test files: #[cfg(test)] modules, tests/

Go

Import detection: ^import\s+[\("']
Entry points: func main() in main.go
Test files: *_test.go

Troubleshooting

"No symbol matching X found"

Cause: Serena's LSP didn't index the symbol, or name doesn't match exactly.

Solutions:

1. Try substring_matching=true in find_symbol
2. Use search_for_pattern to locate the symbol first
3. Fall back to Grep: Grep pattern="def symbol_name\s*\(" path=scope

Empty import/reference results from Serena

Cause: Serena's search may not parse all file types or patterns.

Solutions:

1. Use native Grep (more reliable for regex):

   Grep pattern="^(import|from)" glob="*.py" output_mode=content
   

2. Check if files are in Serena's scope (activate_project first)

"Project not activated" errors

Cause: Serena requires explicit project activation.

Solution:

→ activate_project(project_name_or_path)
→ check_onboarding_performed()
Then proceed with analysis

High token usage despite using Serena

Cause: Using include_body=true or reading full files unnecessarily.

Solutions:

1. Use include_body=false for discovery, only true when needed
2. Use depth=0 for initial overview, increase only if needed
3. Limit file reads to specific line ranges

find_symbol returns too many results

Cause: Common symbol name matches across codebase.

Solutions:

1. Provide relative_path to narrow scope
2. Use full name_path_pattern: ClassName/method_name
3. Filter results by file path pattern

Example Invocations

Quick health check

User: "How healthy is this codebase?"
→ Run Mode 3 only
→ Output: Grade + top 3 issues + brief recommendations

Pre-refactor analysis

User: "I want to refactor the auth module"
→ Run Mode 2 on key auth symbols (find high-Ca symbols first)
→ Run Mode 1 on auth/ directory
→ Output: Risk assessment + dependency map + affected tests

PR impact assessment

User: "What's the impact of changing UserService?"
→ Run Mode 2 with depth=3 on UserService
→ List affected test files
→ Output: Risk level + impact tree + recommended test commands

New developer onboarding

User: "Help me understand this codebase"
→ Run Mode 5 (comprehensive)
→ Output: Full report with health, dependencies, and main flows

Dead code hunt

User: "Find unused code I can safely delete"
→ Run Mode 1 on scope
→ Filter to exports with 0 references
→ Exclude: entry points, test fixtures, public API
→ Output: List of likely-dead symbols with locations

Agent Deferral

When user requests overlap with existing specialized agents, defer appropriately.

Complementary Workflows

Impact-flow works well before or after other agents:

1. Before architecture-strategist: Run dependency graph first to provide structural context
2. After security-sentinel: Run blast radius on flagged vulnerabilities to prioritize fixes
3. Before refactoring: Run health score to identify highest-debt areas
4. After pattern-recognition: Trace flow through detected anti-patterns

Quick Reference

For detailed algorithms, see references/health-metrics.md and references/dependency-analysis.md. For output templates, see references/report-templates.md. For agent integration details, see references/agent-integration.md. For troubleshooting, see the Troubleshooting section above.