gitnexus 1.1.0 → 1.1.2

package/skills/debugging.md

@@ -1,106 +1,106 @@
----
-name: gitnexus-debugging
-description: Trace bugs through call chains using knowledge graph
----
-
-# Debugging with GitNexus
-
-## Quick Start
-```
-0. READ gitnexus://repos                          → Discover indexed repos
-1. If "Index is stale" → gitnexus_analyze({repo: "my-app"})
-2. gitnexus_search({query: "...", repo: "my-app"})  → Find code related to error
-3. gitnexus_explore({name, type: "symbol", repo: "my-app"}) → Get callers and callees
-4. READ gitnexus://repo/my-app/process/{name}      → Trace execution flow
-```
-
-## When to Use
-- "Why is this function failing?"
-- "Trace where this error comes from"
-- "Who calls this method?"
-- "Debug the payment issue"
-
-## Workflow Checklist
-```
-Bug Investigation:
-- [ ] READ gitnexus://repos to find the right repo
-- [ ] Understand the symptom (error message, behavior)
-- [ ] gitnexus_search to find related code
-- [ ] Identify the suspect function
-- [ ] gitnexus_explore to see callers/callees
-- [ ] READ gitnexus://repo/{name}/process/{name} if suspect is in a process
-- [ ] READ gitnexus://repo/{name}/schema for Cypher query help
-- [ ] gitnexus_cypher for custom traces
-```
-
-## Resource Reference
-
-### gitnexus://repo/{name}/schema
-Graph schema for writing Cypher queries:
-```yaml
-nodes: [Function, Class, Method, File, Community, Process]
-relationships: [CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS]
-example_queries:
-  find_callers: |
-    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"})
-    RETURN caller.name
-```
-
-### gitnexus://repo/{name}/process/{processName}
-Trace execution flow to find where bug might occur:
-```yaml
-name: CheckoutFlow
-trace:
-  1: handleCheckout
-  2: validateCart
-  3: processPayment  ← bug here?
-  4: sendConfirmation
-```
-
-## Tool Reference
-
-### gitnexus_search
-Find code related to error or symptom:
-```
-gitnexus_search({query: "payment validation error", depth: "full", repo: "my-app"})
-```
-
-### gitnexus_explore
-Get symbol context:
-```
-gitnexus_explore({name: "validatePayment", type: "symbol", repo: "my-app"})
-→ Callers: processCheckout, webhookHandler
-→ Callees: verifyCard, fetchRates
-```
-
-### gitnexus_cypher
-Custom graph queries for tracing:
-```cypher
-// Trace call chain (2 hops)
-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_search({query: "payment error handling", repo: "my-app"})
-   → validatePayment, handlePaymentError, PaymentException
-
-2. gitnexus_explore({name: "validatePayment", type: "symbol", repo: "my-app"})
-   → Callees: verifyCard, fetchRates (external API!)
-
-3. READ gitnexus://repo/my-app/process/CheckoutFlow
-   → Step 3: validatePayment → calls external API
-
-4. Root cause: fetchRates calls external API without proper timeout
-```
-
-## Debugging Patterns
-
-| Symptom | Approach |
-|---------|----------|
-| Error message | Search for error text, trace throw sites |
-| Wrong return value | Trace data flow through callees |
-| Intermittent failure | Look for external calls, timeouts |
-| Performance issue | Find hot paths via callers count |
+---
+name: gitnexus-debugging
+description: Trace bugs through call chains using knowledge graph
+---
+
+# Debugging with GitNexus
+
+## Quick Start
+```
+0. READ gitnexus://repos                          → Discover indexed repos
+1. If "Index is stale" → gitnexus_analyze({repo: "my-app"})
+2. gitnexus_search({query: "...", repo: "my-app"})  → Find code related to error
+3. gitnexus_explore({name, type: "symbol", repo: "my-app"}) → Get callers and callees
+4. READ gitnexus://repo/my-app/process/{name}      → Trace execution flow
+```
+
+## When to Use
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "Debug the payment issue"
+
+## Workflow Checklist
+```
+Bug Investigation:
+- [ ] READ gitnexus://repos to find the right repo
+- [ ] Understand the symptom (error message, behavior)
+- [ ] gitnexus_search to find related code
+- [ ] Identify the suspect function
+- [ ] gitnexus_explore to see callers/callees
+- [ ] READ gitnexus://repo/{name}/process/{name} if suspect is in a process
+- [ ] READ gitnexus://repo/{name}/schema for Cypher query help
+- [ ] gitnexus_cypher for custom traces
+```
+
+## Resource Reference
+
+### gitnexus://repo/{name}/schema
+Graph schema for writing Cypher queries:
+```yaml
+nodes: [Function, Class, Method, File, Community, Process]
+relationships: [CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS]
+example_queries:
+  find_callers: |
+    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"})
+    RETURN caller.name
+```
+
+### gitnexus://repo/{name}/process/{processName}
+Trace execution flow to find where bug might occur:
+```yaml
+name: CheckoutFlow
+trace:
+  1: handleCheckout
+  2: validateCart
+  3: processPayment  ← bug here?
+  4: sendConfirmation
+```
+
+## Tool Reference
+
+### gitnexus_search
+Find code related to error or symptom:
+```
+gitnexus_search({query: "payment validation error", depth: "full", repo: "my-app"})
+```
+
+### gitnexus_explore
+Get symbol context:
+```
+gitnexus_explore({name: "validatePayment", type: "symbol", repo: "my-app"})
+→ Callers: processCheckout, webhookHandler
+→ Callees: verifyCard, fetchRates
+```
+
+### gitnexus_cypher
+Custom graph queries for tracing:
+```cypher
+// Trace call chain (2 hops)
+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_search({query: "payment error handling", repo: "my-app"})
+   → validatePayment, handlePaymentError, PaymentException
+
+2. gitnexus_explore({name: "validatePayment", type: "symbol", repo: "my-app"})
+   → Callees: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls external API
+
+4. Root cause: fetchRates calls external API without proper timeout
+```
+
+## Debugging Patterns
+
+| Symptom | Approach |
+|---------|----------|
+| Error message | Search for error text, trace throw sites |
+| Wrong return value | Trace data flow through callees |
+| Intermittent failure | Look for external calls, timeouts |
+| Performance issue | Find hot paths via callers count |

package/skills/exploring.md

@@ -1,126 +1,126 @@
----
-name: gitnexus-exploring
-description: Navigate unfamiliar code using GitNexus knowledge graph
----
-
-# Exploring Codebases
-
-## Quick Start
-```
-0. READ gitnexus://repos            → Discover indexed repos (use repo param if multiple)
-1. If "Index is stale" → gitnexus_analyze({repo: "my-app"})
-2. READ gitnexus://repo/{name}/context        → Get codebase overview (~150 tokens)
-3. READ gitnexus://repo/{name}/clusters       → See all functional clusters
-4. READ gitnexus://repo/{name}/cluster/{name} → Deep dive on specific cluster
-```
-
-## When to Use
-- "How does authentication work?"
-- "What's the project structure?"
-- "Show me the main components"
-- "Where is the database logic?"
-
-## Workflow Checklist
-```
-Exploration Progress:
-- [ ] READ gitnexus://repos to discover available repos
-- [ ] READ gitnexus://repo/{name}/context for codebase overview
-- [ ] READ gitnexus://repo/{name}/clusters to list all clusters
-- [ ] Identify the relevant cluster by name
-- [ ] READ gitnexus://repo/{name}/cluster/{name} for cluster details
-- [ ] Use gitnexus_explore for specific symbols
-```
-
-## Resource Reference
-
-### gitnexus://repos
-Discover all indexed repositories. **Read first.**
-```yaml
-repos:
-  - name: "my-app"
-    path: "/home/user/my-app"
-    files: 42
-    symbols: 918
-```
-
-### gitnexus://repo/{name}/context
-Codebase overview for a specific repo.
-```yaml
-project: my-app
-stats:
-  files: 42
-  symbols: 918
-  clusters: 12
-  processes: 45
-tools_available: [list_repos, search, explore, impact, overview, cypher]
-```
-
-### gitnexus://repo/{name}/clusters
-All functional clusters with cohesion scores.
-```yaml
-clusters:
-  - name: "Auth"
-    symbols: 47
-    cohesion: 92%
-  - name: "Database"
-    symbols: 32
-    cohesion: 88%
-```
-
-### gitnexus://repo/{name}/cluster/{clusterName}
-Members of a specific cluster.
-```yaml
-name: Auth
-symbols: 47
-cohesion: 92%
-members:
-  - name: validateUser
-    type: Function
-    file: src/auth/validator.ts
-```
-
-### gitnexus://repo/{name}/process/{processName}
-Full execution trace.
-```yaml
-name: LoginFlow
-type: cross_community
-steps:
-  1: handleLogin (src/auth/handler.ts)
-  2: validateUser (src/auth/validator.ts)
-  3: createSession (src/auth/session.ts)
-```
-
-## Tool Reference (When Resources Aren't Enough)
-
-### gitnexus_explore
-For detailed symbol context with callers/callees:
-```
-gitnexus_explore({name: "validateUser", type: "symbol", repo: "my-app"})
-→ Callers: loginHandler, apiMiddleware
-→ Callees: checkToken, getUserById
-```
-
-### gitnexus_search
-For finding code by query:
-```
-gitnexus_search({query: "payment validation", depth: "full", repo: "my-app"})
-```
-
-## Example: "How does payment processing work?"
-
-```
-1. READ gitnexus://repos
-   → Repos: my-app (918 symbols)
-
-2. READ gitnexus://repo/my-app/context
-   → 918 symbols, 12 clusters
-
-3. READ gitnexus://repo/my-app/clusters
-   → Clusters: Auth, Payment, Database, API...
-
-4. READ gitnexus://repo/my-app/cluster/Payment
-   → Members: processPayment, validateCard, PaymentService
-
-5. READ gitnexus://repo/my-app/process/CheckoutFlow
-   → handleCheckout → validateCart → processPayment → sendConfirmation
-```
+---
+name: gitnexus-exploring
+description: Navigate unfamiliar code using GitNexus knowledge graph
+---
+
+# Exploring Codebases
+
+## Quick Start
+```
+0. READ gitnexus://repos            → Discover indexed repos (use repo param if multiple)
+1. If "Index is stale" → gitnexus_analyze({repo: "my-app"})
+2. READ gitnexus://repo/{name}/context        → Get codebase overview (~150 tokens)
+3. READ gitnexus://repo/{name}/clusters       → See all functional clusters
+4. READ gitnexus://repo/{name}/cluster/{name} → Deep dive on specific cluster
+```
+
+## When to Use
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+
+## Workflow Checklist
+```
+Exploration Progress:
+- [ ] READ gitnexus://repos to discover available repos
+- [ ] READ gitnexus://repo/{name}/context for codebase overview
+- [ ] READ gitnexus://repo/{name}/clusters to list all clusters
+- [ ] Identify the relevant cluster by name
+- [ ] READ gitnexus://repo/{name}/cluster/{name} for cluster details
+- [ ] Use gitnexus_explore for specific symbols
+```
+
+## Resource Reference
+
+### gitnexus://repos
+Discover all indexed repositories. **Read first.**
+```yaml
+repos:
+  - name: "my-app"
+    path: "/home/user/my-app"
+    files: 42
+    symbols: 918
+```
+
+### gitnexus://repo/{name}/context
+Codebase overview for a specific repo.
+```yaml
+project: my-app
+stats:
+  files: 42
+  symbols: 918
+  clusters: 12
+  processes: 45
+tools_available: [list_repos, search, explore, impact, overview, cypher]
+```
+
+### gitnexus://repo/{name}/clusters
+All functional clusters with cohesion scores.
+```yaml
+clusters:
+  - name: "Auth"
+    symbols: 47
+    cohesion: 92%
+  - name: "Database"
+    symbols: 32
+    cohesion: 88%
+```
+
+### gitnexus://repo/{name}/cluster/{clusterName}
+Members of a specific cluster.
+```yaml
+name: Auth
+symbols: 47
+cohesion: 92%
+members:
+  - name: validateUser
+    type: Function
+    file: src/auth/validator.ts
+```
+
+### gitnexus://repo/{name}/process/{processName}
+Full execution trace.
+```yaml
+name: LoginFlow
+type: cross_community
+steps:
+  1: handleLogin (src/auth/handler.ts)
+  2: validateUser (src/auth/validator.ts)
+  3: createSession (src/auth/session.ts)
+```
+
+## Tool Reference (When Resources Aren't Enough)
+
+### gitnexus_explore
+For detailed symbol context with callers/callees:
+```
+gitnexus_explore({name: "validateUser", type: "symbol", repo: "my-app"})
+→ Callers: loginHandler, apiMiddleware
+→ Callees: checkToken, getUserById
+```
+
+### gitnexus_search
+For finding code by query:
+```
+gitnexus_search({query: "payment validation", depth: "full", repo: "my-app"})
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://repos
+   → Repos: my-app (918 symbols)
+
+2. READ gitnexus://repo/my-app/context
+   → 918 symbols, 12 clusters
+
+3. READ gitnexus://repo/my-app/clusters
+   → Clusters: Auth, Payment, Database, API...
+
+4. READ gitnexus://repo/my-app/cluster/Payment
+   → Members: processPayment, validateCard, PaymentService
+
+5. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → handleCheckout → validateCart → processPayment → sendConfirmation
+```