Analysis Tools

Seven tools for impact analysis, prediction, counterfactual simulation, fingerprinting, hypothesis testing, structural diffing, and drift detection.

`impact`

Impact radius / blast analysis for a node. Propagates signal outward from a source node to determine which other nodes would be affected by a change. Supports forward (downstream), reverse (upstream), and bidirectional analysis.

Parameters

Parameter	Type	Required	Default	Description
`node_id`	`string`	Yes	–	Target node identifier. Can be an external_id (`file::backend/config.py`) or a node label.
`agent_id`	`string`	Yes	–	Calling agent identifier.
`direction`	`string`	No	`"forward"`	Propagation direction. Values: `"forward"` (what does this affect?), `"reverse"` (what affects this?), `"both"`.
`include_causal_chains`	`boolean`	No	`true`	Include causal chain detection. Shows the specific paths through which impact propagates.

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "impact",
    "arguments": {
      "agent_id": "jimi",
      "node_id": "file::chat_handler.py",
      "direction": "forward",
      "include_causal_chains": true
    }
  }
}

Example Response

{
  "source": "file::chat_handler.py",
  "source_label": "chat_handler.py",
  "direction": "forward",
  "blast_radius": [
    { "node_id": "file::chat_routes.py", "label": "chat_routes.py", "type": "file", "signal_strength": 0.91, "hop_distance": 1 },
    { "node_id": "file::ws_relay.py", "label": "ws_relay.py", "type": "file", "signal_strength": 0.78, "hop_distance": 1 },
    { "node_id": "file::stream_parser.py", "label": "stream_parser.py", "type": "file", "signal_strength": 0.65, "hop_distance": 2 }
  ],
  "total_energy": 4271.0,
  "max_hops_reached": 3,
  "causal_chains": [
    {
      "path": ["chat_handler.py", "chat_routes.py", "main.py"],
      "relations": ["imported_by", "registered_in"],
      "cumulative_strength": 0.82
    }
  ]
}

When to Use

Before modifying code – understand the blast radius before touching a file
Risk assessment – high total_energy = high-risk change
Scope validation – verify that a planned change does not leak beyond expected boundaries
Reverse analysis – find all upstream dependencies that could cause a bug in a given module

predict – predicts which files will co-change (more actionable than blast radius)
counterfactual – simulates deletion rather than change
validate_plan – validates an entire modification plan

`predict`

Co-change prediction for a modified node. Given a node that was just changed, predicts which other nodes are most likely to need changes too, ranked by confidence. Uses historical co-change patterns, structural proximity, and velocity scoring.

Parameters

Parameter	Type	Required	Default	Description
`changed_node`	`string`	Yes	–	Node identifier that was changed.
`agent_id`	`string`	Yes	–	Calling agent identifier.
`top_k`	`integer`	No	`10`	Number of top predictions to return.
`include_velocity`	`boolean`	No	`true`	Include velocity scoring. Velocity considers how recently and frequently nodes co-changed.

Example Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "predict",
    "arguments": {
      "agent_id": "jimi",
      "changed_node": "file::session_pool.py",
      "top_k": 5
    }
  }
}

Example Response

{
  "changed_node": "file::session_pool.py",
  "predictions": [
    { "node_id": "file::worker_pool.py", "label": "worker_pool.py", "confidence": 0.89, "velocity": 0.72, "reason": "high co-change frequency + structural coupling" },
    { "node_id": "file::process_manager.py", "label": "process_manager.py", "confidence": 0.76, "velocity": 0.65, "reason": "imports session_pool" },
    { "node_id": "file::tests/test_session_pool.py", "label": "test_session_pool.py", "confidence": 0.71, "velocity": 0.80, "reason": "test file" },
    { "node_id": "file::spawner.py", "label": "spawner.py", "confidence": 0.54, "velocity": 0.41, "reason": "2-hop dependency" },
    { "node_id": "file::config.py", "label": "config.py", "confidence": 0.32, "velocity": 0.28, "reason": "shared configuration" }
  ],
  "elapsed_ms": 8.3
}

When to Use

After modifying a module – find what else needs updating
Before committing – verify you have not missed a co-change partner
Code review – check if a PR is missing changes to coupled modules

impact – blast radius (broader, less actionable)
timeline – detailed co-change history
validate_plan – validates an entire plan against co-change predictions

`counterfactual`

What-if node removal simulation. Simulates removing one or more nodes from the graph and reports the cascade: orphaned nodes, lost activation energy, and the resulting blast radius. Non-destructive – the graph is not modified.

Parameters

Parameter	Type	Required	Default	Description
`node_ids`	`string[]`	Yes	–	Node identifiers to simulate removal of.
`agent_id`	`string`	Yes	–	Calling agent identifier.
`include_cascade`	`boolean`	No	`true`	Include cascade analysis. Shows multi-hop propagation of the removal.

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "counterfactual",
    "arguments": {
      "agent_id": "jimi",
      "node_ids": ["file::spawner.py"],
      "include_cascade": true
    }
  }
}

Example Response

{
  "removed_nodes": ["file::spawner.py"],
  "cascade": [
    { "depth": 1, "affected": 23 },
    { "depth": 2, "affected": 456 },
    { "depth": 3, "affected": 3710 }
  ],
  "total_affected": 4189,
  "orphaned_count": 0,
  "pct_activation_lost": 0.41,
  "elapsed_ms": 3.1
}

When to Use

Before deleting/rewriting modules – understand the full cascade before removing code
Dependency audit – find modules whose removal would be catastrophic
Architecture planning – evaluate the cost of removing a subsystem

impact – change impact (less extreme than removal)
hypothesize – test a structural claim about dependencies

`fingerprint`

Activation fingerprint and equivalence detection. Computes a structural fingerprint for a target node (or the entire graph) and finds functionally equivalent or duplicate nodes. Uses probe queries to generate activation patterns and compares them via cosine similarity.

Parameters

Parameter	Type	Required	Default	Description
`target_node`	`string`	No	–	Target node to find equivalents for. If omitted, performs global fingerprinting.
`agent_id`	`string`	Yes	–	Calling agent identifier.
`similarity_threshold`	`number`	No	`0.85`	Cosine similarity threshold for equivalence. Range: 0.0 to 1.0. Lower values find more (but weaker) matches.
`probe_queries`	`string[]`	No	–	Optional probe queries for fingerprinting. Auto-generated from the node’s neighborhood if omitted.

Example Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "fingerprint",
    "arguments": {
      "agent_id": "jimi",
      "target_node": "file::session_pool.py",
      "similarity_threshold": 0.7
    }
  }
}

Example Response

{
  "target": "file::session_pool.py",
  "fingerprint": [0.92, 0.45, 0.78, 0.33, 0.67],
  "equivalents": [
    { "node_id": "file::worker_pool.py", "label": "worker_pool.py", "similarity": 0.88, "reason": "similar pool lifecycle pattern" },
    { "node_id": "file::fast_pool.py", "label": "fast_pool.py", "similarity": 0.74, "reason": "shared structural role" }
  ],
  "elapsed_ms": 55.2
}

When to Use

Duplicate detection – find code doing the same thing in different places
Consolidation audit – identify candidates for unification
Post-build review – verify new code does not duplicate existing functionality

resonate – finds harmonically coupled nodes (complementary, not duplicate)
activate – simpler search without equivalence scoring

`hypothesize`

Graph-based hypothesis testing. Takes a natural language claim about the codebase, parses it into a structural query pattern, and returns evidence for and against the claim with a Bayesian confidence score.

Supported claim patterns (auto-detected from natural language): NEVER_CALLS, ALWAYS_BEFORE, DEPENDS_ON, NO_DEPENDENCY, COUPLING, ISOLATED, GATEWAY, CIRCULAR.

Parameters

Parameter	Type	Required	Default	Description
`claim`	`string`	Yes	–	Natural language claim about the codebase. Examples: `"chat_handler never validates session tokens"`, `"all external calls go through smart_router"`, `"critic is independent of whatsapp"`.
`agent_id`	`string`	Yes	–	Calling agent identifier.
`max_hops`	`integer`	No	`5`	Maximum BFS hops for evidence search.
`include_ghost_edges`	`boolean`	No	`true`	Include ghost edges as weak evidence. Ghost edges count as lower-weight supporting evidence.
`include_partial_flow`	`boolean`	No	`true`	Include partial flow when full path not found. Shows how far the search reached.
`path_budget`	`integer`	No	`1000`	Budget cap for all-paths enumeration. Limits computation on dense graphs.

Example Request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "hypothesize",
    "arguments": {
      "agent_id": "jimi",
      "claim": "worker_pool depends on whatsapp_manager at runtime"
    }
  }
}

Example Response

{
  "claim": "worker_pool depends on whatsapp_manager at runtime",
  "claim_type": "depends_on",
  "subject_nodes": ["file::worker_pool.py"],
  "object_nodes": ["file::whatsapp_manager.py"],
  "verdict": "likely_true",
  "confidence": 0.72,
  "supporting_evidence": [
    {
      "type": "path_found",
      "description": "2-hop path via process_manager.cancel",
      "likelihood_factor": 3.5,
      "nodes": ["file::worker_pool.py", "file::process_manager.py", "file::whatsapp_manager.py"],
      "relations": ["calls", "imports"],
      "path_weight": 0.68
    }
  ],
  "contradicting_evidence": [],
  "paths_explored": 25015,
  "elapsed_ms": 58.0
}

Verdict Values

Verdict	Confidence Range	Meaning
`"likely_true"`	> 0.8	Strong structural evidence supports the claim
`"likely_false"`	< 0.2	Strong structural evidence contradicts the claim
`"inconclusive"`	0.2 – 0.8	Evidence exists both for and against

When to Use

Architecture validation – test claims about module boundaries and dependencies
Bug investigation – test whether a suspected dependency exists
Code review – verify architectural invariants are maintained
Security audit – test isolation claims (e.g. “auth module is isolated from user input”)

why – finds the path between two specific nodes
impact – measures downstream impact rather than testing a claim
scan – structural analysis with predefined patterns

`differential`

Focused structural diff between two graph snapshots. Compares edges, weights, nodes, and coupling between snapshot A and snapshot B, optionally narrowed by a focus question.

Parameters

Parameter	Type	Required	Default	Description
`agent_id`	`string`	Yes	–	Calling agent identifier.
`snapshot_a`	`string`	Yes	–	Path to snapshot A, or `"current"` for the in-memory graph.
`snapshot_b`	`string`	Yes	–	Path to snapshot B, or `"current"` for the in-memory graph.
`question`	`string`	No	–	Focus filter question. Narrows the diff output. Examples: `"what new coupling was introduced?"`, `"what modules became isolated?"`.
`focus_nodes`	`string[]`	No	`[]`	Limit diff to neighborhood of specific nodes.

Example Request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "differential",
    "arguments": {
      "agent_id": "jimi",
      "snapshot_a": "/path/to/before.json",
      "snapshot_b": "current",
      "question": "what new coupling was introduced?"
    }
  }
}

Example Response

{
  "snapshot_a": "/path/to/before.json",
  "snapshot_b": "current",
  "new_edges": [
    { "source": "whatsapp_routes.py", "target": "chat_handler.py", "relation": "calls", "weight": 0.45 }
  ],
  "removed_edges": [],
  "weight_changes": [
    { "source": "session_pool.py", "target": "worker_pool.py", "relation": "imports", "old_weight": 0.5, "new_weight": 0.78, "delta": 0.28 }
  ],
  "new_nodes": ["file::whatsapp_chat_bridge.py"],
  "removed_nodes": [],
  "coupling_deltas": [
    { "community_a": "whatsapp", "community_b": "chat", "old_coupling": 0.2, "new_coupling": 0.65, "delta": 0.45 }
  ],
  "summary": "1 new edge, 1 new node, 1 weight change, 1 coupling increase",
  "elapsed_ms": 120.5
}

When to Use

Pre/post refactor comparison – snapshot before, refactor, then diff against current
PR review – compare graph before and after a branch’s changes
Architecture drift monitoring – periodic snapshot comparison

diverge – higher-level drift analysis with anomaly detection
lock_diff – diff within a locked region (no snapshot file needed)

`diverge`

Structural drift detection between a baseline and the current graph state. Higher-level than differential – includes anomaly detection (test deficits, velocity spikes, new coupling), coupling matrix changes, and a Jaccard-based structural drift score.

Parameters

Parameter	Type	Required	Default	Description
`agent_id`	`string`	Yes	–	Calling agent identifier.
`baseline`	`string`	Yes	–	Baseline reference. Values: ISO date (`"2026-03-01"`), git ref (SHA or tag), or `"last_session"` to use the saved GraphFingerprint.
`scope`	`string`	No	–	File path glob to limit scope. Example: `"backend/stormender*"`. `None` = all nodes.
`include_coupling_changes`	`boolean`	No	`true`	Include coupling matrix delta between communities.
`include_anomalies`	`boolean`	No	`true`	Detect anomalies: test deficits, velocity spikes, new coupling, isolation.

Example Request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "diverge",
    "arguments": {
      "agent_id": "jimi",
      "baseline": "2026-03-01",
      "scope": "backend/stormender*"
    }
  }
}

Example Response

{
  "baseline": "2026-03-01",
  "baseline_commit": "a1b2c3d",
  "scope": "backend/stormender*",
  "structural_drift": 0.23,
  "new_nodes": ["file::stormender_v2_runtime_guard.py"],
  "removed_nodes": [],
  "modified_nodes": [
    { "file": "stormender_v2.py", "delta": "+450/-30", "growth_ratio": 1.85 }
  ],
  "coupling_changes": [
    { "pair": ["stormender_v2.py", "stormender_v2_routes.py"], "was": 0.4, "now": 0.72, "direction": "strengthened" }
  ],
  "anomalies": [
    { "type": "test_deficit", "file": "stormender_v2_runtime_guard.py", "detail": "New file with 0 test files", "severity": "warning" },
    { "type": "velocity_spike", "file": "stormender_v2.py", "detail": "450 lines added in 12 days", "severity": "info" }
  ],
  "summary": "23% structural drift. 1 new file (untested). Stormender coupling strengthened.",
  "elapsed_ms": 85.0
}

Anomaly Types

Type	Description
`test_deficit`	New or modified file with no corresponding test file
`velocity_spike`	Unusually high churn rate
`new_coupling`	Previously independent modules are now coupled
`isolation`	Module that was connected became isolated

When to Use

Session start – drift shows weight-level changes; diverge shows structural-level changes
Sprint retrospective – how much did the architecture change this sprint?
Quality gate – flag files with test deficits before merging

drift – weight-level drift (lighter, faster)
differential – lower-level snapshot diff
timeline – single-node temporal history

`ghost_edges`

Parse git history and surface temporal co-change ghost edges: files that move together without an explicit static dependency.

Parameters

Parameter	Type	Required	Description
`agent_id`	`string`	Yes	Calling agent identifier.
`scope`	`string`	No	Optional path prefix.
`depth`	`string`	No	Git history window such as `7d`, `30d`, `90d`, or `all`.
`top_k`	`integer`	No	Maximum ghost edges to return.

When to Use

To find hidden temporal coupling
Before refactors in churn-heavy areas

`taint_trace`

Inject taint at entry points and trace propagation through the graph to expose missed validation, auth, or sanitization boundaries.

Parameters

Parameter	Type	Required	Description
`agent_id`	`string`	Yes	Calling agent identifier.
`entry_nodes`	`string[]`	Yes	Entry points to taint.
`taint_type`	`string`	No	`user_input`, `sensitive_data`, or `custom`.
`max_depth`	`integer`	No	Maximum propagation depth.

When to Use

Security reviews on trust boundaries
Input validation and auth flow audits

`twins`

Find structurally similar or identical nodes by topology signature.

Parameters

Parameter	Type	Required	Description
`agent_id`	`string`	Yes	Calling agent identifier.
`scope`	`string`	No	Optional path prefix.
`node_types`	`string[]`	No	Restrict to node families.
`similarity_threshold`	`number`	No	Minimum similarity threshold.

When to Use

Duplicate logic detection
Consolidation/refactor candidate discovery

fingerprint
refactor_plan

`refactor_plan`

Graph-native refactoring proposals: community detection and extraction candidates for a scoped region.

Parameters

Parameter	Type	Required	Description
`agent_id`	`string`	Yes	Calling agent identifier.
`scope`	`string`	No	Optional path prefix.
`max_communities`	`integer`	No	Upper bound on candidate communities.
`min_community_size`	`integer`	No	Smallest extractable group to report.

When to Use

Before modularization/extraction work
To identify communities with high internal cohesion

twins
impact

`runtime_overlay`

Overlay OpenTelemetry span activity onto the graph to paint runtime heat, latency, and error signals onto nodes.

Parameters

Parameter	Type	Required	Description
`agent_id`	`string`	Yes	Calling agent identifier.
`spans`	`object[]`	Yes	OTel-like spans to ingest.
`service_name`	`string`	No	Optional service scope.
`mapping_strategy`	`string`	No	Mapping mode such as `label_match`, `code_attribute`, `exact_id`.

When to Use

Correlating runtime hotspots with structural risk
Prioritizing where to inspect first after a production incident

`metrics`

Return structural metrics per file, function, class, struct, or module.

Parameters

Parameter	Type	Required	Description
`agent_id`	`string`	Yes	Calling agent identifier.
`scope`	`string`	No	Optional path prefix.
`node_types`	`string[]`	No	Restrict output to certain node types.
`sort`	`string`	No	Sort order such as `loc_desc`, `complexity_desc`, `name_asc`.

When to Use

To rank hot modules by size/degree/centrality
To anchor audits with hard structural numbers

`type_trace`

Trace where a type, struct, or enum is used across the graph.

Parameters

Parameter	Type	Required	Description
`agent_id`	`string`	Yes	Calling agent identifier.
`target`	`string`	Yes	Type name or external_id to trace.
`direction`	`string`	No	`forward`, `reverse`, or `both`.
`group_by_file`	`boolean`	No	Group usage sites by file.

When to Use

Following type spread before edits
Understanding where a central data model is consumed

`diagram`

Generate Mermaid or DOT graph diagrams from a query or node-centered slice.

Parameters

Parameter	Type	Required	Description
`agent_id`	`string`	Yes	Calling agent identifier.
`center`	`string`	No	Seed query or node_id to center the diagram.
`format`	`string`	No	`mermaid` or `dot`.
`direction`	`string`	No	`TD` or `LR`.
`max_nodes`	`integer`	No	Maximum nodes to include.

When to Use

Human-readable architecture explanations
Sharing graph context with another agent or reviewer

Keyboard shortcuts

m1nd Documentation