From c4564b02262b26bfa7ae0a15574b058119727c8a Mon Sep 17 00:00:00 2001 From: sanguine59 Date: Sun, 16 Aug 2026 14:05:37 +0700 Subject: [PATCH] docs(claude-skills): update gitnexus-impact-analysis --- .../skills/gitnexus-impact-analysis/SKILL.md | 51 +++++++++++++++---- 1 file changed, 40 insertions(+), 11 deletions(-) diff --git a/.claude/skills/gitnexus-impact-analysis/SKILL.md b/.claude/skills/gitnexus-impact-analysis/SKILL.md index ee1cd3496..058788d29 100644 --- a/.claude/skills/gitnexus-impact-analysis/SKILL.md +++ b/.claude/skills/gitnexus-impact-analysis/SKILL.md @@ -14,27 +14,40 @@ description: "Use when the user wants to know what will break if they change som - 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 {}`. With one indexed +repository, use the examples below as written. With more than one, pass `repo` +explicitly on every call — an omitted `repo` errors, or silently resolves to a +configured default — and stop and ask if the intended repository is ambiguous. +Pass `worktree` to `detect_changes` when your changes live in a linked worktree +the server was not launched from. See `references/repository-identity.md`. + ## Workflow ``` -1. impact({target: "X", direction: "upstream"}) or `node .gitnexus/run.cjs impact "X" --direction upstream --repo .` +0. list_repos {} → Bind repo (and worktree) +1. impact({target: "X", direction: "upstream"[, repo: ""]}) 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 +3. detect_changes({scope: "all"[, repo: ""][, worktree: ""]}) or `node .gitnexus/run.cjs detect-changes --scope all --repo ` +4. Assess risk and report to user, echoing the bound repo/worktree/index ``` -> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal. +> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in the bound checkout. > 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 total > 1, 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 -- [ ] Assess risk level and report to user +- [ ] Confirm the checkout you edited is the checkout that was diffed +- [ ] Assess risk level and report, stating repo/worktree/index freshness ``` ## Understanding Output @@ -64,11 +77,12 @@ treating the symbol as safe to change or delete. ## Tools -**impact** — the primary tool for symbol blast radius. If MCP is unavailable, use `node .gitnexus/run.cjs impact --direction upstream --repo .` instead: +**impact** — the primary tool for symbol blast radius. If MCP is unavailable, use `node .gitnexus/run.cjs impact --direction upstream --repo ` instead: ``` impact({ target: "validateUser", + repo: "my-app", // required once >1 repository is indexed direction: "upstream", minConfidence: 0.8, maxDepth: 3 @@ -82,25 +96,36 @@ impact({ - 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** — git-diff based impact analysis. If MCP is unavailable, use `node .gitnexus/run.cjs detect-changes --scope all --repo ` instead: ``` -detect_changes({scope: "all"}) +detect_changes({scope: "all", repo: "my-app", worktree: "/abs/path/to/checkout"}) → Changed: 5 symbols in 3 files → Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline → Risk: MEDIUM ``` +`repo` is required once more than one repository is indexed. `worktree` is +needed when your changes are in a linked worktree the MCP server was not +launched from — omit it there and `git diff` runs in the wrong checkout, +reporting zero changed symbols for a tree full of edits. + `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 -than tick the pre-commit check. +`UNKNOWN` above: a zero there means unseen, not unaffected. A wrong-worktree +zero carries none of those flags and looks exactly like a clean result, so +confirm the checkout you edited is the checkout that was diffed. Re-run it +rather than tick the pre-commit check. ## Example: "What breaks if I change validateUser?" ``` -1. impact({target: "validateUser", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .` +0. list_repos {} + → total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly + +1. impact({target: "validateUser", repo: "my-app", direction: "upstream"}) + or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo /abs/path/my-app` → d=1: loginHandler, apiMiddleware (WILL BREAK) → d=2: authRouter, sessionManager (LIKELY AFFECTED) @@ -108,4 +133,8 @@ than tick the pre-commit check. → LoginFlow and TokenRefresh touch validateUser 3. Risk: 2 direct callers, 2 processes = MEDIUM + Repository: my-app (/abs/path/my-app) Worktree: same Index: current ``` + +With a single indexed repository, step 0 returns `total: 1` and the `repo` +argument drops out of every call above.