Dhpk Gitnexus Debugging

---
name: dhpk-gitnexus-debugging
description: "Trace bugs and errors through the GitNexus knowledge graph. Use when: debugging a failure, tracing an error to its origin, finding callers of a suspect symbol, investigating unexpected behavior. Not for: general architecture understanding (use dhpk-gitnexus-exploring), change blast-radius (use dhpk-gitnexus-impact-analysis), CLI/index ops (use dhpk-gitnexus-cli). Output: a root-cause hypothesis with the call chain + files to inspect."
metadata:
  dhpk-invocation-class: "implicit-eligible"
---

# 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

## Workflow

```
1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
```

> If the context reports a stale index, follow `dhpk-gitnexus-guide` for the
> single stale-index recovery path before continuing this workflow.

## Checklist

```
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] gitnexus_query for error text or related code
- [ ] Identify the suspect function from returned processes
- [ ] gitnexus_context to see callers and callees
- [ ] Trace execution flow via process resource if applicable
- [ ] gitnexus_cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause
```

## Debugging Patterns

| Symptom              | GitNexus Approach                                          |
| -------------------- | ---------------------------------------------------------- |
| Error message        | `gitnexus_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           |

## Tools

**gitnexus_query** — find code related to error:

```
gitnexus_query({query: "payment validation error"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException
```

**gitnexus_context** — full context for a suspect:

```
gitnexus_context({name: "validatePayment"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)
```

**gitnexus_cypher** — custom call chain traces:

```cypher
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
RETURN [n IN nodes(path) | n.name] AS chain
```

## Example: "Payment endpoint returns 500 intermittently"

```
1. gitnexus_query({query: "payment error handling"})
   → Processes: CheckoutFlow, ErrorHandling
   → Symbols: validatePayment, handlePaymentError

2. gitnexus_context({name: "validatePayment"})
   → 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
```

## When NOT to Use

- You want to understand architecture, not chase a bug → `dhpk-gitnexus-exploring`
- You need the blast radius of a planned change → `dhpk-gitnexus-impact-analysis`
- You need to (re)build the index or run CLI ops → `dhpk-gitnexus-cli`

## Output

A root-cause hypothesis backed by the graph: the suspect symbol, its call chain (callers/callees), the execution flow it sits in, and the source files to confirm the fix.

## Verification

- [ ] The index freshness and query scope are recorded.
- [ ] The suspect call chain is corroborated with source file evidence.
- [ ] The affected execution flow and external boundary are identified.
- [ ] Hypotheses are separated from confirmed root cause.
- [ ] The next reproduction or focused test is explicit.

The schema, tool names, resource catalog, and stale-index recovery are owned by
`dhpk-gitnexus-guide`; this skill owns bug-tracing workflow and evidence.