Code index

​

When to use

• Enrich code references with precise symbol-level data (no regex heuristic)
• Map call graphs to SDD artifacts for blast radius analysis
• Detect uncovered execution paths (public symbols with no SDD refs)
• Infer transitive artifact relationships from call graph
• Enable code intelligence features in dashboard, req-change, traceability-check, and reconcile
• Connect GitNexus execution flows to SDD workflows

​

Invocation

/sdd:code-index            # Full mode (GitNexus analysis + SDD mapping)
/sdd:code-index --lite     # Lite mode (regex-based, no AST/call graph)
/sdd:code-index --status   # Check if index is current, report staleness
/sdd:code-index --refresh  # Re-run only for files changed since last index

​

Modes

​

Prerequisites

• A project with source code in src/ (or configurable root)
• Existing SDD artifacts (at least requirements/ and spec/)
• dashboard/traceability-graph.json generated by /sdd:dashboard
• Optional (for Full mode): GitNexus installed (npm install -g gitnexus)

​

How it works

​

Phase 1: Environment check

1. Verify dashboard/traceability-graph.json exists (STOP if missing → suggest /sdd:dashboard)
2. Check GitNexus availability via npx gitnexus --version
   • If available: proceed with Full mode
   • If not available AND mode is Full: present option table (Install GitNexus / Use Lite mode / Cancel)
3. Read current traceability-graph.json into memory

​

Phase 2: Code analysis (Full mode — GitNexus)

1. Run GitNexus analysis: npx gitnexus analyze
2. Query GitNexus MCP for all exported symbols:
   • Use gitnexus_query({ query: "all exported functions and classes" })
   • Collect: name, type, filePath, startLine, endLine, isExported
3. For each symbol, query context:
   • Use gitnexus_context({ name: symbolName }) → callers, callees, processes
4. Scan each symbol’s source location for Refs: annotations:
   • Search backward up to 10 lines for // Refs: or # Refs: comments
   • Extract artifact IDs (REQ-, UC-, INV-*, etc.)

​

Phase 3: Code analysis (Lite mode — Regex)

1. Scan src/**/*.{ts,js,tsx,jsx,py,java,go,rs,cs,rb} for:
   • Function/class/method declarations (regex per language)
   • Refs: annotation comments within 10 lines
2. Build symbol table: name, type, filePath, startLine (no callers/callees/processes)
3. Mark all refs as direct (no inference possible without call graph)

​

Phase 4: SDD mapping

1. For each symbol with Refs: annotations:
   • Map referenced artifact IDs to the traceability graph
   • Create artifactRefs[] entries on the symbol
2. Transitive inference (Full mode only):
   • For each annotated symbol, walk its callers (from GitNexus call graph)
   • For each caller WITHOUT its own Refs: annotation:
     • Infer that the caller implements the same artifacts
     • Add to inferredRefs[] with flag inferred: true
     • Propagation depth: max 2 levels (caller of caller)
3. Process mapping (Full mode only):
   • For each GitNexus execution flow/process:
     • Collect all artifact refs from steps in the flow
     • Map process to SDD artifacts
     • Create processes[] entries
4. Community detection (Full mode only):
   • Group symbols by their GitNexus community assignments
   • Map communities to SDD business domains (from classification)

​

Phase 5: Graph enrichment

{
  "codeIntelligence": {
    "indexed": true,
    "indexedAt": "ISO-8601",
    "engine": "gitnexus" | "regex-lite",
    "engineVersion": "x.y.z",
    "symbols": [...],
    "callGraph": [...],
    "processes": [...],
    "stats": {
      "totalSymbols": N,
      "symbolsWithRefs": N,
      "symbolsWithInferredRefs": N,
      "uncoveredSymbols": N,
      "totalProcesses": N,
      "processesWithRefs": N
    }
  }
}

• For symbols with inferredRefs, add new codeRef entries to target artifacts
• Set inferred: true flag (schema v4 extension)
• Add new relationships: inferred-implements with confidence score
• Update statistics.codeStats with enriched counts

​

Phase 6: Write & report

1. Write updated dashboard/traceability-graph.json
   • Bump $schema to "traceability-graph-v4" if codeIntelligence added
   • Preserve all existing data (backward compatible)
2. Generate enrichment report:

# Code Index Report

## Summary
- Engine: GitNexus v1.x.x / regex-lite
- Indexed at: 2026-03-01T15:00:00Z
- Total symbols: 340
- Symbols with direct refs: 120 (35%)
- Symbols with inferred refs: 80 (24%)
- Uncovered symbols: 140 (41%)
- Execution flows mapped: 45
- Flows with SDD refs: 28 (62%)

## Top Uncovered Symbols
| Symbol | File | Type | Callers | Why Uncovered |
|--------|------|------|---------|---------------|
| processPayment | src/payment/processor.ts | function | 5 | No Refs annotation, no annotated callers |

## Inferred Mappings
| Symbol | File | Inferred From | Artifact | Confidence |
|--------|------|---------------|----------|------------|
| handleLogin | src/routes/auth.ts | calls validateUser | UC-AUTH-001 | 0.9 |

## Recommendations
1. Add `// Refs: UC-PAY-001` to processPayment() — 5 callers will gain coverage
2. ...

3. Output report to code-intelligence/CODE-INDEX-REPORT.md

​

Output artifacts

​

Integration with other skills

​

Constraints

• C-01: Never modify source code files (no auto-injection of Refs: comments)
• C-02: Transitive inference max depth = 2 (beyond 2 levels, confidence too low)
• C-03: Confidence threshold for inferred refs = 0.7 (below this, mark as “suggested” not “inferred”)
• C-04: GitNexus is optional — the skill MUST work in Lite mode without it
• C-05: Preserve all existing graph data — the codeIntelligence block is additive only
• C-06: If traceability-graph.json doesn’t exist, direct user to /sdd:dashboard first

​

Example workflow

​

First-time setup

/sdd:dashboard          # Generate traceability graph
/sdd:code-index         # Enrich with code intelligence

​

After code changes

/sdd:code-index --refresh   # Re-index only changed files
/sdd:dashboard              # Regenerate dashboard with updated data

​

Without GitNexus

/sdd:code-index --lite      # Use regex-based analysis

​

Related skills