docs(claude-skills): update gitnexus-debugging

.claude/skills/gitnexus-debugging/SKILL.md

@@ -13,20 +13,33 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 - "This endpoint returns 500"
 - Investigating bugs, errors, or unexpected behavior
 
+## Bind the repository first
+
+A root cause traced in the wrong repository is a wrong root cause. 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. This matters most for `cypher`, whose
+statement carries no in-band hint of which database it ran against. See
+`references/repository-identity.md`.
+
 ## Workflow
 
 ```
-1. query({search_query: "<error or symptom>"})            → Find related execution flows
-2. context({name: "<suspect>"})                    → See callers/callees/processes
+0. list_repos {}                                          → Bind repo (and worktree)
+1. query({search_query: "<error or symptom>"[, repo: "<repo>"]})  → Find related execution flows
+2. context({name: "<suspect>"[, repo: "<repo>"]})         → See callers/callees/processes
 3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
-4. cypher({statement: "MATCH path..."})                 → Custom traces if needed
+4. cypher({statement: "MATCH path..."[, repo: "<repo>"]}) → Custom traces if needed
 ```
 
-> 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.
+> A stale index describes the code before your bug; refresh before trusting a trace.
 
 ## Checklist
 
 ```
+- [ ] list_repos {} — bind repo; explicit repo when total > 1, ask if ambiguous
 - [ ] Understand the symptom (error message, unexpected behavior)
 - [ ] query for error text or related code
 - [ ] Identify the suspect function from returned processes
@@ -34,6 +47,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 - [ ] Trace execution flow via process resource if applicable
 - [ ] cypher for custom call chain traces if needed
 - [ ] Read source files to confirm root cause
+- [ ] State the repository and index freshness with the diagnosis
 ```
 
 ## Debugging Patterns
@@ -44,7 +58,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 | Wrong return value   | `context` on the function → trace callees for data flow    |
 | Intermittent failure | `context` → look for external calls, async deps            |
 | Performance issue    | `context` → find symbols with many callers (hot paths)     |
-| Recent regression    | `detect_changes` to see what your changes affect           |
+| Recent regression    | `detect_changes` to see what your changes affect — pass `worktree` if your changes are in a linked worktree |
 | "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |
 
 ## Tools
@@ -52,7 +66,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 **query** — find code related to error:
 
 ```
-query({search_query: "payment validation error"})
+query({search_query: "payment validation error", repo: "my-app"})
 → Processes: CheckoutFlow, ErrorHandling
 → Symbols: validatePayment, handlePaymentError, PaymentException
 ```
@@ -60,23 +74,27 @@ query({search_query: "payment validation error"})
 **context** — full context for a suspect:
 
 ```
-context({name: "validatePayment"})
+context({name: "validatePayment", repo: "my-app"})
 → Incoming calls: processCheckout, webhookHandler
 → Outgoing calls: verifyCard, fetchRates (external API!)
 → Processes: CheckoutFlow (step 3/7)
 ```
 
-**cypher** — custom call chain traces:
+**cypher** — custom call chain traces. Pass `repo` alongside the statement; the
+Cypher text itself names no repository, so the result is unattributable without
+it:
 
-```cypher
+```
+cypher({repo: "my-app", statement: `
 MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
 RETURN [n IN nodes(path) | n.name] AS chain
+`})
 ```
 
 **trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
 
 ```
-trace({ from: "processCheckout", to: "fetchRates" })
+trace({ from: "processCheckout", to: "fetchRates", repo: "my-app" })
 → status: ok, hopCount: 3
 → hops: processCheckout → validatePayment → verifyCard → fetchRates
 → edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
@@ -87,15 +105,22 @@ When no path exists, `trace` reports the furthest reachable node — exactly whe
 ## Example: "Payment endpoint returns 500 intermittently"
 
 ```
-1. query({search_query: "payment error handling"})
+0. list_repos {}
+   → total: 2 (my-app, billing-api) — bind my-app explicitly on every call
+
+1. query({search_query: "payment error handling", repo: "my-app"})
    → Processes: CheckoutFlow, ErrorHandling
    → Symbols: validatePayment, handlePaymentError
 
-2. context({name: "validatePayment"})
+2. context({name: "validatePayment", repo: "my-app"})
    → Outgoing calls: verifyCard, fetchRates (external API!)
 
 3. READ gitnexus://repo/my-app/process/CheckoutFlow
    → Step 3: validatePayment → calls fetchRates (external)
 
 4. Root cause: fetchRates calls external API without proper timeout
+   Repository: my-app  Index: current
 ```
+
+With a single indexed repository, step 0 returns `total: 1` and the `repo`
+argument drops out of every call above.