playbooks

home / skills / adibfirman / dotfiles / gitnexus-guide

gitnexus-guide skill

/claude/.claude/skills/gitnexus-guide

This skill helps you learn and navigate GitNexus tools, resources, and schema, guiding you to the right guide for your task.

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

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

Files (1)
SKILL.md
3.4 KB
---
name: gitnexus-guide
description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
---

# GitNexus Guide

Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.

## Always Start Here

For any task involving code understanding, debugging, impact analysis, or refactoring:

1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
2. **Match your task to a skill below** and **read that skill file**
3. **Follow the skill's workflow and checklist**

> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.

## Skills

| Task                                         | Skill to read       |
| -------------------------------------------- | ------------------- |
| Understand architecture / "How does X work?" | `gitnexus-exploring`         |
| Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
| Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
| Rename / extract / split / refactor          | `gitnexus-refactoring`       |
| Tools, resources, schema reference           | `gitnexus-guide` (this file) |
| Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |

## Tools Reference

| Tool             | What it gives you                                                        |
| ---------------- | ------------------------------------------------------------------------ |
| `query`          | Process-grouped code intelligence — execution flows related to a concept |
| `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
| `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
| `detect_changes` | Git-diff impact — what do your current changes affect                    |
| `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
| `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
| `list_repos`     | Discover indexed repos                                                   |

## Resources Reference

Lightweight reads (~100-500 tokens) for navigation:

| Resource                                       | Content                                   |
| ---------------------------------------------- | ----------------------------------------- |
| `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
| `gitnexus://repo/{name}/clusters`              | All functional areas with cohesion scores |
| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members                              |
| `gitnexus://repo/{name}/processes`             | All execution flows                       |
| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace                        |
| `gitnexus://repo/{name}/schema`                | Graph schema for Cypher                   |

## Graph Schema

**Nodes:** File, Function, Class, Interface, Method, Community, Process
**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS

```cypher
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
RETURN caller.name, caller.filePath
```

Overview

This skill documents GitNexus tools, resources, and the knowledge graph schema for repository-level code intelligence. It is the single reference for which MCP tools to run, where to read lightweight resources, and how to query the graph. Use this guide to map common tasks to the right GitNexus skill and to learn the available CLI/query primitives.

How this skill works

The guide lists available MCP tools (query, context, impact, detect_changes, rename, cypher, list_repos) and links them to concrete outputs you can inspect. It describes lightweight resource endpoints you can open (context, clusters, processes, schema) and includes the core graph node and edge types plus a simple example Cypher snippet. Start by checking repository context for index freshness, then pick the skill that matches your goal.

When to use it

  • When you need to choose the correct GitNexus tool for architecture, debugging, impact analysis, or refactoring.
  • Before running deep queries: to check repository index freshness via the context endpoint.
  • When you want quick, consumable resource pages like clusters, processes, or the repo schema.
  • To discover what graph nodes and relations exist before writing raw Cypher queries.
  • When assessing the blast radius of changes using detect_changes or impact.

Best practices

  • Always read gitnexus://repo/{name}/context first and run npx gitnexus analyze if the index is stale.
  • Match your task to a specific skill (exploring, debugging, refactoring, impact analysis) and follow that skill’s workflow.
  • Use lightweight resource endpoints (clusters, processes, schema) for focused facts before running broad queries.
  • Prefer tool-level primitives (query, context, impact) for common analyses and reserve cypher for custom graph queries.
  • When renaming, use the rename tool to apply coordinated, confidence-tagged edits across files.

Example use cases

  • Investigate why a function is failing: open the process or context page, then run query or debugging skill.
  • Estimate blast radius of a proposed API change: run impact or detect_changes against your diff.
  • Perform a large-scale rename: use the rename tool then validate with context and detect_changes.
  • Explore execution flows for a feature: open processes, follow STEP_IN_PROCESS edges, or run the query tool for grouped flows.
  • Write a custom graph query: read gitnexus://repo/{name}/schema, then run cypher with the provided node/edge types.

FAQ

What should I do if the index is stale?

Run npx gitnexus analyze in the repository root to refresh the index, then re-open gitnexus://repo/{name}/context.

When should I use cypher vs the higher-level tools?

Use query, context, impact, and detect_changes for common analyses. Use cypher only for ad-hoc or complex graph queries not covered by those tools.