/gitnexus-impact-analysis

name: gitnexus-impact-analysis
description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""

Impact Analysis with GitNexus

When to Use

• "Is it safe to change this function?"
• "What will break if I modify X?"
• "Show me the blast radius"
• "Who uses this code?"
• Before making non-trivial code changes
• Before committing — to understand what your changes affect

Bind the repository first

Impact analysis is the gate that authorizes an edit, so it must answer for the repository you are about to edit.

Call `list_repos {}` before the first tool call. With one indexed repository, use the examples below as written. With more than one, pass `repo` on every call: an omitted `repo` normally errors, but under an MCP policy with a configured default it resolves to that default silently. If you cannot tell which repository is meant, stop and ask — every result below an ambiguous identity inherits the ambiguity. `list_repos` is paginated, so page with `offset: pagination.nextOffset` until `hasMore` is false before concluding a repository is absent.

`detect_changes` takes `worktree` when your changes are in a linked worktree the MCP server was not launched from. The server auto-detects a worktree only when it was launched from inside one; otherwise `git diff` runs in the wrong checkout and reports zero changed symbols — a false clean check that carries none of the degradation flags described below. In the CLI fallbacks, `--repo .` means the current checkout; pass the intended repository path instead when you are not standing in it.

State the bound identity with your risk report:

Repository: <name> (<path>)   Worktree: <path>   Index: <commit>, <n> behind HEAD

Workflow

0. list_repos {}                                           → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) or `node .gitnexus/run.cjs impact "X" --direction upstream --repo .`
2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
3. detect_changes({scope: "all"}) or `node .gitnexus/run.cjs detect-changes --scope all --repo .`
4. Assess risk and report to user, echoing repo/worktree/index identity

> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal. > If `.gitnexus/run.cjs` is missing, replace `node .gitnexus/run.cjs` with `npx gitnexus` in the fallback commands.

Checklist

- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] impact({target, direction: "upstream"}) or CLI fallback to find dependents
- [ ] Review d=1 items first (these WILL BREAK)
- [ ] Check high-confidence (>0.8) dependencies
- [ ] READ processes to check affected execution flows
- [ ] detect_changes({scope: "all"}) or CLI fallback for pre-commit check
- [ ] Confirm the checkout you edited is the checkout that was diffed
- [ ] Assess risk level and report, stating repo/worktree/index identity

Understanding Output

| Depth | Risk Level | Meaning | | ----- | ---------------- | ------------------------ | | d=1 | **WILL BREAK** | Direct callers/importers | | d=2 | LIKELY AFFECTED | Indirect dependencies | | d=3 | MAY NEED TESTING | Transitive effects |

Risk Assessment

| Affected | Risk | | ------------------------------ | -------- | | <5 symbols, few processes | LOW | | 5-15 symbols, 2-5 processes | MEDIUM | | >15 symbols or many processes | HIGH | | Critical path (auth, payments) | CRITICAL | | **Zero callers found** | **UNKNOWN** |

`UNKNOWN` is not a low rung on this scale — it means the walk could not answer. An empty caller set is equally consistent with "genuinely unused" and "the callers are not resolvable by the index" (plain-object property access, dynamic dispatch, cross-language calls), so few-callers ⇒ LOW does **not** apply. The result carries a `riskNote` saying so. Confirm with a text search before treating the symbol as safe to change or delete.

`risk` is the edit gate: warn on HIGH/CRITICAL and stop on UNKNOWN until the uncertainty is resolved. Within single-repo mode, compare File and symbol targets with local `riskSharedAxes` (direct/total only). Within group mode, compare only group results: their `riskSharedAxes` overlays resolved cross-repo crossings on that local value. Never use either field to waive the edit gate. Check `riskScale.unusedAxes` before comparing kinds: MCP File walks omit process/module axes, while web Graph-RAG expands File targets to in-file symbols before enrichment.

Tools

**impact** — the primary tool for symbol blast radius. If MCP is unavailable, use `node .gitnexus/run.cjs impact <symbol> --direction upstream --repo .` instead:

impact({
  target: "validateUser",
  repo: "my-app",          // required once >1 repository is indexed
  direction: "upstream",
  minConfidence: 0.8,
  maxDepth: 3
})

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

→ d=2 (LIKELY AFFECTED):
  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]

**detect_changes** — git-diff based impact analysis. If MCP is unavailable, use `node .gitnexus/run.cjs detect-changes --scope all --repo .` instead:

detect_changes({scope: "all"})

→ Changed: 5 symbols in 3 files
→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
→ Risk: MEDIUM

Add `repo` once more than one repository is indexed, and `worktree: "<abs path>"` when your changes are in a linked worktree the server was not launched from.

`partial: true` (a graph query failed) or `truncated: true` (the changed-symbol listing was capped) means the result is short of the truth, and reads like `UNKNOWN` above: a zero there means unseen, not unaffected. Re-run it rather th