structure-graph

name	structure-graph
description	GitNexus is a conditional accelerator, not a default navigation tool. Use it early only when the task already signals large-repo, cross-module, blast-radius, or unclear-flow uncertainty. Every candidate must be verified with rg/Probe before reading deeply or editing.

Structure Graph Skill (Conditional Accelerator)

Purpose

GitNexus is not a routine navigation tool, but rather a conditional accelerator to narrow down candidates early when dealing with structural or dependency uncertainties. To minimize context bloat and prevent reasoning pollution, all candidates returned by GitNexus must be verified before reading them deeply or editing them.

---

When to Use (and when not to)

• Use early if the task involves:
  • Large, unfamiliar codebases or unclear flow entry points.
  • Cross-cutting module changes or DTO/API/Event/Config/Interface changes.
  • Analyzing the "blast radius" (downstream impact) of a proposed change.
• Do NOT use for:
  • Small, localized, or well-defined tasks (e.g., finding a class or simple keyword). Use the regular search ladder (ripgrep / Probe only) to keep the context clean.

---

Tool Division (ADR-006)

• ripgrep / Probe (Ground Truth): Always the final source verification.
• GitNexus (Code Structure Candidate Generator): Best for compile-time topology (imports, symbols, call graphs, static dependencies).
• Graphify (Multimodal/Non-code Graph): Used only when query needs non-code context (docs, PDFs, diagrams, architecture notes).
• Tests / Framework Evidence (Runtime Confirmation): Critical for dynamic runtime wiring (Spring DI, AOP, events, @Conditional beans, reflection), which static graphs cannot prove.

---

How it Works

1. Generate Candidates: Run GitNexus CLI to generate structure hints. Use Graphify only when the task requires non-code context such as docs, PDFs, diagrams, or architecture notes.
2. Verify Before Reading Deeply: Run a quick ripgrep or Probe to verify the candidate exists and is relevant:

   rg -n "candidateSymbol" path/from/graph
   

3. Targeted Reading & Optional Edits: Open and read only the verified files. Edit only if the task requires it.
4. Runtime Validation: Confirm dynamic behavior using compilation and test suites.

---

Rules

• GitNexus is a conditional accelerator, not a default navigation tool.
• GitNexus output is a candidate list, not evidence. Every candidate must be verified with rg/Probe before reading deeply or editing.
• Keep graph tools off the default path; their absence must not block work.
• Prefer read-only GitNexus operations. Do not use graph output as edit authority.
• Treat runtime-flow results as lower-confidence; confirm Spring DI, AOP, events, @Conditional beans, reflection, and config-driven behavior with tests or framework-aware evidence.
• Prefer GitNexus CLI over GitNexus MCP by default. GitNexus MCP is opt-in only; do not keep it attached as an always-on context provider unless the user explicitly requests it.
• When running gitnexus analyze, preserve Sober's custom spine and skills and avoid embedding cost by default:
  • use gitnexus analyze --skip-agents-md --skip-skills --skip-embeddings, or
  • configure "skipContextFiles": true, "skipSkills": true, and "embeddings": false in .gitnexusrc:

    {
      "skipContextFiles": true,
      "skipSkills": true,
      "embeddings": false
    }