gitnexus-exploring

# 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 Follow project scope rules. Use only the steps needed for the current question; known paths and exact text can be read or searched directly. Reuse current context and stop when the relevant source and dependencies answer the question. If graph tools are unavailable, use scoped source and reference searches. ## Suggested workflow ``` 1. READ gitnexus://repos → Discover indexed repos 2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness 3. query({search_query: "<what you want to understand>"}) → Find related execution flows 4. context({name: "<symbol>"}) → Deep dive on specific symbol 5. READ gitnexus://repo/{name}/process/{name} → Trace full execution flow ``` > Refresh with `node .gitnexus/run.cjs analyze --index-only` only if stale coverage prevents the needed analysis; otherwise use the relevant source directly. ## Checklist ``` - [ ] READ gitnexus://repo/{name}/context - [ ] query for the concept you want to understand - [ ] Review returned processes (execution flows) - [ ] 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 **query** — find execution flows related to a concept: ``` query({search_query: "payment processing"}) → Processes: CheckoutFlow, RefundFlow, WebhookHandler → Symbols grouped by flow with file locations ``` **context** — 360-degree view of a symbol: ``` 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. query({search_query: "payment processing"}) → CheckoutFlow: processPayment → validateCard → chargeStripe → RefundFlow: initiateRefund → calculateRefund → processRefund 3. context({name: "processPayment"}) → Incoming: checkoutHandler, webhookHandler → Outgoing: validateCard, chargeStripe, saveTransaction 4. Read src/payments/processor.ts for implementation details ```