使い方
- インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
- 必要なツール、認証情報、対応環境を原文で確認します。
- 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/abhigyanpatwari/gitnexus --skill gitnexus-debugging開始前の確認
- 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
- スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。
Debugging with GitNexus
When to Use
- "Why is this function failing?"
- "Trace where this error comes from"
- "Who calls this method?"
- "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.
Bind once using a confirmed registry name/path or configured MCP default. Call list_repos {} if the target is not yet known; reuse that binding across calls. 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. This matters most for cypher, whose statement carries no in-band hint of which database it ran against.
list_repos is paginated, so page with offset: pagination.nextOffset until hasMore is false before concluding a repository is absent.
A stale index describes the code from before your bug, so refresh before trusting a trace, and state the repository and index freshness with the diagnosis.
Workflow
0. Bind the repo once (list_repos only if not already known)
1. If the suspect is unknown, query for the error/symptom with small result limits
2. context({name: "<suspect>"}) → See callers/callees/processes
3. Read a process resource only if its trace resolves an open question
4. cypher({statement: "MATCH path..."}) → Custom traces if neededIf "Index is stale" → runnode .gitnexus/run.cjs analyzein terminal. Hot-toolstalenessnames which index answered (branch/lastCommit) and how fresh it is (status). Re-analyze only forbehindordiverged—currentis identity,unknownis unmeasurable.
Checklist
- [ ] Once per session: bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
- [ ] Identify the suspect function from returned processes
- [ ] context to see callers and callees
- [ ] 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 diagnosisKeep investigations focused
Start with a known symbol's context, or a small query (limit: 3, max_symbols: 3, include_content: false, chain_depth: 0) to discover one. When the server advertises these single-repository filters, request only the needed evidence:
context({uid: "<suspect id>", repo: "my-app", include_content: true,
response_sections: ["outgoing"], relationTypes: ["CALLS"]})
trace({from_uid: "<suspect id>", to_uid: "<failure id>", repo: "my-app"})symbol and completeness/staleness diagnostics remain in a filtered context. relationTypes filters the returned incoming/outgoing categories only; it does not expand their existing bounded window or filter an explicitly requested chain. For callback registration, include USES; for imports or inheritance, request those relation types or omit the filter. Omitted references are not absent references. Broaden when the hypothesis needs it, and preserve UNKNOWN/partial warnings. Confirm source and tests before claiming a root cause. A useful 2–3 call investigation is a goal, not a reason to skip verification or pre-edit impact.
Debugging Patterns
| Symptom | GitNexus Approach |
|---|---|
| Error message | query for error text → context on throw sites |
| 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 — pass worktree for a linked worktree |
| "How does A reach B?" | trace between the two symbols — shortest call chain in one call |
Tools
query — find code related to error:
query({search_query: "payment validation error", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentExceptioncontext — full context for a suspect:
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. Pass repo alongside the statement; the Cypher text itself names no repository, so the result is unattributable without it:
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
RETURN [n IN nodes(path) | n.name] AS chaintrace — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining context hops:
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)When no path exists, trace reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
Example: "Payment endpoint returns 500 intermittently"
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", 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: currentWith a single indexed repository, step 0 returns total: 1 and the repo argument drops out of every call above.
