forked from abhigyanpatwari/GitNexus
-
Notifications
You must be signed in to change notification settings - Fork 0
Implement skill synchronization system with CI enforcement #5
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
36aaca5
chore: run commands
L1nusB d34a465
docs: add analysis
L1nusB cc9b997
docs: master sync document
L1nusB 15cc8a5
docs: remove dead documents
L1nusB 57beac7
chore: reconcile all skill files to canonical source (Phase 1)
L1nusB 0b1f145
test: add sync-skills TDD tests (Phase 2 — red phase)
L1nusB dcf0962
feat(sync-skills): implement planSync() — Phase 3 complete
L1nusB bfc376d
feat(sync-skills): add per-target manifests and executable sync scrip…
L1nusB 24101a1
ci: add skill-sync-check job to enforce skill file parity — Phase 5 c…
L1nusB ddff5f8
docs: finalize skill-sync master document — Phase 6 complete
L1nusB 25d9c30
fix: address code review findings — MD040 labels, Node 18 compat, Mar…
L1nusB File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,89 +1,86 @@ | ||
| --- | ||
| name: gitnexus-debugging | ||
| description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\"" | ||
| --- | ||
|
|
||
| # 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 "Index is stale" → run `npx gitnexus analyze` in terminal. | ||
|
|
||
| ## 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 | ||
| ``` | ||
| <!-- AUTO-GENERATED FROM gitnexus/skills/gitnexus-debugging.md — DO NOT EDIT --> | ||
|
|
||
| # 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 "Index is stale" → run `npx gitnexus analyze` in terminal. | ||
|
|
||
| ## 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 | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,78 +1,75 @@ | ||
| --- | ||
| 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 | ||
| ``` | ||
| <!-- AUTO-GENERATED FROM gitnexus/skills/gitnexus-exploring.md — DO NOT EDIT --> | ||
|
|
||
| # 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 | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add explicit fence languages in the generated markdown.
These unlabeled fenced blocks trigger markdownlint MD040 repeatedly. Since this file is auto-generated, please fix the canonical skill source or sync step to emit languages like
text,bash, orcypherinstead of patching the derived file directly.Also applies to: 26-34, 50-54, 58-63, 74-86
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 15-15: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents