Dhpk Gitnexus Exploring

---
name: dhpk-gitnexus-exploring
description: 'Explore and understand a codebase via the GitNexus knowledge graph. Use when: asking how code works, understanding architecture, tracing execution flows, or exploring unfamiliar code. Not for: blast-radius of a change (use dhpk-gitnexus-impact-analysis), bug tracing (use dhpk-gitnexus-debugging), CLI/index ops (use dhpk-gitnexus-cli). Output: a code-flow explanation grounded in graph queries + the files to read.'
metadata:
  dhpk-invocation-class: implicit-eligible
---

# Exploring Codebases with GitNexus

## When to Use

- "How does authentication work?"
- "What's the project structure?"
- "Show me the main components"
- "Where is the database logic?"
- Understanding code you haven't seen before

## Workflow

```
1. READ gitnexus://repos                          → Discover indexed repos
2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
```

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

## Checklist

```
- [ ] READ gitnexus://repo/{name}/context
- [ ] gitnexus_query for the concept you want to understand
- [ ] Review returned processes (execution flows)
- [ ] gitnexus_context on key symbols for callers/callees
- [ ] READ process resource for full execution traces
- [ ] Read source files for implementation details
```

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

## Resources

| Resource                                | What you get                                            |
| --------------------------------------- | ------------------------------------------------------- |
| `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
| `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |

## Tools

**gitnexus_query** — find execution flows related to a concept:

```
gitnexus_query({query: "payment processing"})
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
→ Symbols grouped by flow with file locations
```

**gitnexus_context** — 360-degree view of a symbol:

```
gitnexus_context({name: "validateUser"})
→ Incoming calls: loginHandler, apiMiddleware
→ Outgoing calls: checkToken, getUserById
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
```

## Example: "How does payment processing work?"

```
1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
2. gitnexus_query({query: "payment processing"})
   → CheckoutFlow: processPayment → validateCard → chargeStripe
   → RefundFlow: initiateRefund → calculateRefund → processRefund
3. gitnexus_context({name: "processPayment"})
   → Incoming: checkoutHandler, webhookHandler
   → Outgoing: validateCard, chargeStripe, saveTransaction
4. Read src/payments/processor.ts for implementation details
```

## When NOT to Use

- You need the blast radius of a planned change → `dhpk-gitnexus-impact-analysis`
- You are chasing a specific bug or error → `dhpk-gitnexus-debugging`
- You need to (re)build the index or run CLI ops → `dhpk-gitnexus-cli`

## Output

A grounded explanation of how the code works — the relevant processes / execution flows, the key symbols and their callers/callees, and the source files to open next.

## Verification

- [ ] The repository context and index freshness were checked.
- [ ] Execution flows are distinguished from isolated symbol matches.
- [ ] Callers, callees, and source locations support the explanation.
- [ ] Unknowns and dynamic or external edges are called out.