playbooks

home / skills / adibfirman / dotfiles / gitnexus-exploring

gitnexus-exploring skill

/claude/.claude/skills/gitnexus-exploring

This skill helps you understand code structure and execution flows by querying and tracing a codebase with GitNexus context and processes.

npx playbooks add skill adibfirman/dotfiles --skill gitnexus-exploring

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.0 KB
---
name: gitnexus-exploring
description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
---

# 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 step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.

## 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
```

## 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
```

Overview

This skill helps you explore unfamiliar codebases, trace execution flows, and understand architecture using GitNexus-indexed repositories. It guides discovery from high-level context down to per-symbol callers and callees, plus full execution traces. Use it when you need to answer "How does X work?" or map where a feature lives in the repo.

How this skill works

Start by reading the repository context to get stats and staleness hints. Run targeted queries to find processes and execution flows related to the concept you care about, then inspect symbols for incoming/outgoing calls and membership in flows. Finally, open the process or source files for step-by-step traces and implementation details.

When to use it

  • You want to understand how a feature or flow (auth, payments, deploy) works end-to-end.
  • You need to find what calls a function or where a symbol is defined and used.
  • You’re onboarding into an unfamiliar repo and need a structured discovery path.
  • You want to map high-level components or identify areas of cohesion.
  • You need a reproducible process to trace runtime execution across files.

Best practices

  • Always READ the repo context first to check index freshness and get summary stats.
  • Form a short, focused query (e.g., "payment processing", "auth flow") to limit results.
  • Inspect returned processes, then run gitnexus_context on key symbols to see callers/callees.
  • If the index is stale, run npx gitnexus analyze before deep dives.
  • Complement traces with reading the actual source files for implementation specifics.

Example use cases

  • Show me the auth flow: discover LoginFlow, trace handlers, and inspect validateUser symbol.
  • What calls this function? Use gitnexus_context to list incoming callers and processes.
  • Map project structure: read clusters to see cohesive areas and file memberships.
  • Trace payment processing: query for payments, inspect CheckoutFlow and charge paths.
  • Onboard to dotfiles repo: find main config loaders, initialization steps, and where environment is applied.

FAQ

What if results say the index is stale?

Run npx gitnexus analyze in your terminal to refresh the index, then re-read the repo context.

How do I find all places a concept appears?

Use gitnexus_query with a concise keyword or phrase; review returned processes and cluster results for locations.