sextant-tool-gitnexus

name	sextant-tool-gitnexus
description	Internal reference injected by sextant sub-skills when .gitnexus/ is detected. Not intended for direct invocation. Provides enhanced tool-call guidance for all sextant workflows: context, impact, query, trace, diff_review, and rename MCP tools.

GitNexus Integration Reference

Provides enhanced tool-call guidance for all sextant workflow steps marked 🔗. This reference is meant to be consulted from an active sextant task skill when GitNexus MCP tools are available.

---

1. What is GitNexus

GitNexus indexes a code repository as a knowledge graph — calls, dependencies, imports, inheritance, and cross-module relationships become queryable structure. Its MCP tools let the agent answer "who uses this?", "what will this change affect?", and "what looks similar?" without relying only on grep and file-by-file reading.

Core value comparison:

Traditional Approach	GitNexus Approach
Grep for function name, read call chain file by file	context returns complete caller/callee graph in one call
Estimate "what changing here will affect" from experience	impact returns layered impact list with confidence scores
Use pydeps / madge to detect circular dependencies	impact both queries dependency direction directly from the graph
Manually search similar implementations	query semantic search + cluster membership
Manually assess impact after git diff	diff_review analyzes actual changed symbols and their graph impact

---

2. MCP Tool Quick Reference

2.1 query — Semantic Search

Use for: finding reference modules, extension points, similar code, config, tests.

query({
  query: string,
  repo?: string
})

Returns: relevant symbols, file paths, line numbers, symbol types, cluster membership.

2.2 context — Symbol Context

Use for: understanding a symbol's neighborhood: callers, callees, inheritance, execution processes, cluster.

context({
  symbol: string
})

Confidence guide:

• >= 0.9: direct/static relationship
• 0.7 - 0.9: high-probability inferred relationship
• < 0.7: possible relationship; manually confirm if important

2.3 impact — Impact Analysis

Use for: risk analysis before changing code.

impact({
  target: string,
  direction: "upstream" | "downstream" | "both",
  minConfidence?: number
})

Interpretation:

• Depth 1 = direct dependents / direct dependencies
• Depth 2+ = indirect impact
• Mixed clusters = likely cross-module impact
• Same symbol in both directions = possible cycle

2.4 trace — Execution Flow Tracing

Use for: following a request or business flow from entry point to endpoint.

trace({
  symbol: string
})

2.5 diff_review — Change Impact Review

Use for: reviewing already-written code based on the actual git diff.

diff_review()

2.6 rename — Graph-Aware Renaming

Use for: safe symbol renaming with graph awareness.

rename({
  symbol: string,
  newName: string
})

---

3. Tool Selection Guide

Need to understand a symbol?
  -> context

Need to know what will break if it changes?
  -> impact upstream

Need to know what it depends on or check dependency direction?
  -> impact downstream / both

Need to follow an execution path?
  -> trace

Need to find similar implementations / extension points / tests?
  -> query

Need to review the actual diff?
  -> diff_review

Need to rename safely?
  -> rename

Common combinations:

Scenario	Call Sequence
Bug localization	query -> context -> trace
Impact assessment	impact upstream -> impact downstream
Find reference module	query -> context
Architecture audit	impact both + context + query
Post-change verification	diff_review + impact upstream

---

4. Workflow Enhancements

This section mirrors the main workflows. Each subsection is the target of the short see tool-gitnexus.md pointers kept in the workflow files.

4.1 Add Feature

Step 1 — Understand Existing Architecture

Goal: find the closest reference module, understand its callers/dependencies, and check for extension points.

query({ query: "<new feature description>" })
context({ symbol: "<core symbol of the best reference module>" })
query({ query: "strategy interface factory registry plugin" })

Use results to answer:

• what cluster the new feature belongs to
• which module is the best structural reference
• whether a reusable extension point already exists

Step 2 — Choose Integration Strategy

Goal: decide whether the feature should integrate via registry, abstraction, event bus, config, or invasive modification.

query({ query: "factory register provider plugin" })
query({ query: "abstract interface strategy base class" })
query({ query: "event bus emit subscribe dispatch" })
context({ symbol: "<candidate extension point>" })

Step 3 — Reference Conventions During Implementation

Goal: look up how similar code handles naming, injection, and error handling without browsing the repo manually.

context({ symbol: "<similar function or class in the reference module>" })

Step 4 — Architecture Compliance Audit

Goal: automate the structural parts of the audit.

impact({ target: "<new module core symbol>", direction: "both" })
query({ query: "<new module feature description>" })
context({ symbol: "<new module core symbol>" })

What this verifies well:

• circular / reverse dependencies
• responsibility overlap
• calls into another module's internals

Still manual:

• naming/style consistency
• new side effects/global state
• whether registration/docs/comments must be updated

4.2 Bug Fix

Step 1 — Reproduce and Locate Root Cause

Goal: move from symptom to origin quickly.

query({ query: "<error message keyword or feature description>" })
context({ symbol: "<symbol where the error manifests>" })
trace({ symbol: "<core erroring function>" })

Use results to distinguish:

• bug exposure location
• likely bug origin location
• full request flow if the chain is long

Step 2 — Impact Assessment

Goal: quantify caller impact before editing.

impact({ target: "<bug location symbol>", direction: "upstream" })

Use results to fill:

• caller count
• direct vs indirect impact
• whether the fix crosses clusters/modules

Step 4 — Boundary Validation

Goal: confirm the fix did not radiate unexpectedly.

impact({ target: "<fixed function>", direction: "upstream" })
diff_review()

Still manual:

• reproducing the original bug
• running tests
• judging style consistency

4.3 Modify Feature

Step 1 — Read the Code and Build Context

Goal: replace most manual context gathering with one graph query, then fill remaining semantic gaps manually.

context({ symbol: "<target function or class>" })
query({ query: "<event name / callback name / config keyword>" })
query({ query: "<target symbol> test" })

GitNexus covers well:

• direct callers and dependencies
• related interfaces / inheritance
• process membership
• cluster membership

Still manual:

• design intent from comments / PRs / history
• implicit business contracts

Step 2 — Impact Analysis

Goal: map direct, indirect, and cross-module radiation before changing behavior.

impact({ target: "<change target>", direction: "upstream" })
impact({ target: "<change target>", direction: "downstream" })
diff_review()

Step 3 — Find Extension Paths

Goal: prefer config, extension, or decoration over invasive modification.

query({ query: "<target module> strategy interface factory plugin" })
context({ symbol: "<target function or class>" })

Step 5 — Signature Change Safety Net

Goal: if a public signature changes, generate the caller checklist first.

impact({ target: "<function being modified>", direction: "upstream", minConfidence: 0.8 })

Step 6 — Compliance Audit

Goal: automate the structural checklist.

impact({ target: "<modified symbol>", direction: "both" })
impact({ target: "<modified symbol>", direction: "upstream" })
query({ query: "<shared DTO / Event name>" })
diff_review()

Still manual:

• whether the diff stayed minimal
• style consistency
• tests
• docs / changelog / convention sync

4.4 Requirements Refinement

Step 3 — Architecture Feasibility Assessment

Goal: decide whether the requirement reuses existing code, extends it, or needs new modules.

query({ query: "<feature keywords from the requirement>" })
context({ symbol: "<most likely affected symbol>" })
impact({ target: "<symbol to be modified>", direction: "upstream" })
query({ query: "strategy interface factory registry plugin" })

Step 4 — Task Decomposition

Goal: use a reference module's layering as a breakdown template.

context({ symbol: "<reference module core class>" })

Requirement Change Handling

Goal: estimate rework when requirements change mid-stream.

impact({ target: "<core symbol involved in the change>", direction: "upstream" })
diff_review()

4.5 Code Review

Step 2 — Establish Change Context

Goal: understand the environment around the diff, not just the edited lines.

context({ symbol: "<modified function or class>" })
diff_review()
impact({ target: "<modified symbol>", direction: "upstream" })

Step 3 — Architecture Compliance Review

Goal: automate dependency-direction and boundary checks.

impact({ target: "<new or modified core symbol>", direction: "both" })
context({ symbol: "<new or modified core symbol>" })

Step 4 — DRY Check

Goal: detect likely duplicate implementations.

query({ query: "<functional description of the newly added code>" })

Step 5 — Error Propagation Trace

Goal: inspect where failures travel through the system.

trace({ symbol: "<core function involved in the change>" })

Step 6 — Impact Completeness

Goal: detect unadapted callers and missing synchronized updates.

impact({ target: "<modified function>", direction: "upstream" })
diff_review()

4.6 Write Tests

Step 1 — Analyze the Code Under Test

Goal: build a contract profile of the symbol under test.

context({ symbol: "<function or class under test>" })
trace({ symbol: "<function under test>" })
query({ query: "<module under test> test spec" })

Use results to derive:

• real caller usage patterns
• collaborator/mock candidates
• existing test style and placement

Step 2 — Discover Boundary Scenarios

Goal: extract realistic scenarios from caller behavior and impact hotspots.

context({ symbol: "<function under test>" })
impact({ target: "<function under test>", direction: "upstream" })

Step 4 — Identify External Dependencies to Mock

Goal: classify collaborators into same-module helpers vs external dependencies.

context({ symbol: "<function under test>" })

Step 5 — Find Reference Tests

Goal: follow existing test structure and style.

query({ query: "<module name under test> test" })

4.7 Debug

Step 2 — Identify Paradigm + Isolation Strategy

Goal: map the execution path from entry point to observation point so the isolation direction is correct.

trace({ symbol: "<entry point of the failing flow>" })
context({ symbol: "<symbol where the symptom surfaces>" })

Use results to:

• confirm which layer the observation point belongs to
• identify the boundary immediately above it (the next inward layer to test)

Step 3 — Form and Validate Hypotheses

Goal: narrow the boundary between "correct" and "incorrect" using graph structure rather than grepping.

context({ symbol: "<current observation point>" })
impact({ target: "<current observation point>", direction: "downstream" })

Use results to:

• identify whether the layer's inputs are already wrong (move the observation point inward)
• find collaborators that share state with the failing symbol (relevant for concurrency/async bugs)

Still manual:

• adding print/log statements for runtime observation
• reproducing intermittent or environment-specific failures
• git bisect for regression localization

4.8 Ship / PR Preparation

Step 1 — Assess Change Scope

Goal: understand what the diff actually changed at the symbol level, not just lines.

diff_review()

Use results to:

• classify the change type (behavior vs structural vs config)
• identify changed public interfaces automatically

Step 2 — Pre-Ship Checklist

Goal: find callers that are not covered by the test suite to include in the post-merge verification list.

impact({ target: "<modified symbol>", direction: "upstream" })

Use results to populate:

• "callers not covered by CI" in the Post-Merge Verification Checklist

Still manual:

• CHANGELOG entry
• version bump
• checking for debug-only code

4.9 Sprint Planning

Step 1 — Parse Inputs

Goal: identify which existing modules are involved and where the integration points are.

query({ query: "<requirement keywords>" })
context({ symbol: "<most likely entry point or affected symbol>" })

Step 2 — Dependency Analysis

Goal: determine the correct task ordering from the actual dependency graph rather than architectural assumptions.

impact({ target: "<module to be changed>", direction: "both" })

Use results to:

• confirm which modules are leaf nodes (migrate/change first) vs core nodes (change last)
• detect whether any planned task would create a circular dependency

Step 3 — Task Specification

Goal: identify likely files for each task without manual repo browsing.

context({ symbol: "<symbol central to the task>" })
query({ query: "<task description keywords>" })

4.10 Migration

Step 1 — Migration Scope Scan

Goal: enumerate every file that references the old API or type without manual grep.

query({ query: "<old API name / deprecated symbol name>" })
impact({ target: "<old API symbol>", direction: "upstream" })

Use results to build the migration inventory — the upstream impact list is the file enumeration.

Step 3 — Migration Order Planning

Goal: derive the correct leaf-first order from the dependency graph.

impact({ target: "<old API symbol>", direction: "both" })

Use results to:

• identify modules with no upstream dependents (safe to migrate first)
• identify the core module (most upstream dependents — migrate last)
• detect circular dependencies that complicate ordering

Step 4 — Per-Module Validation

Goal: after each module is migrated, confirm the graph is still structurally correct.

impact({ target: "<migrated symbol>", direction: "both" })
diff_review()

4.11 Security Audit

Dimension 1 — Input Validation

Goal: trace from public entry points to find paths where external input reaches the logic layer without passing through a validation boundary.

trace({ symbol: "<API endpoint handler or route>" })
context({ symbol: "<entry point handler>" })

Use results to identify:

• all layers the request data flows through before reaching logic
• whether any path bypasses the entry-layer validation

Dimension 2 — Authentication and Authorization

Goal: verify that all paths to a protected resource pass through the auth check.

impact({ target: "<protected resource symbol>", direction: "upstream" })
context({ symbol: "<auth middleware / authorization function>" })

Use results to enumerate:

• all upstream callers of the protected resource
• whether any caller path bypasses the auth middleware or authorization check

Still manual:

• verifying that session tokens are excluded from logs
• checking that both AuthN and AuthZ (not just one) are enforced

---

5. When Not to Use GitNexus

• Lightweight tasks where reading the file directly is faster
• Understanding design intent from comments, PRs, or git history
• Inferring business semantics or product meaning
• Replacing actual test execution

---

6. Common Misuse

Misuse	Consequence	Correct Approach
Trust low-confidence graph edges without checking	False positives or missed dynamic behavior	Manually confirm confidence < 0.7 when it matters
Only look upstream	Miss reverse dependencies	Use both for architecture reviews
Use query where context is needed	Get snippets without relationships	Search first, then deep-dive with context
Forget the index may be stale	Results diverge from current code	Re-run analysis after large structural changes
Use diff_review without a diff	Empty or misleading result	Ensure there is an actual git diff

---

7. Index Timeliness

GitNexus is a snapshot, not a live parser. Re-index after large refactors, many added files, or when graph output disagrees with the code.

npx gitnexus analyze
npx gitnexus analyze --force

---

8. Mapping to Skill Principles

Skill Principle/Rule	GitNexus Tool	Verification Method
SRP / no layer-crossing calls	context	Check whether callees cross layer boundaries
OCP / extend rather than modify	query	Search for existing extension points
DIP / avoid hard-coded construction	context	Inspect whether dependencies are pulled directly
DRY / avoid duplicate implementations	query	Search for similar implementations
Dependency direction	impact both	Look for reverse dependencies
Circular dependency detection	impact both	Look for cycles in both directions
Module boundary rules	context	Ensure callees do not include another module's internals