Graph Build

---
name: graph-build
description: '[Code Intelligence] Use when building, updating, or syncing the code knowledge graph. Flag: --scope={full|update|sync} (default auto-detect).'
version: 1.0.0
---

## Quick Summary

**Goal:** [Code Intelligence] Build, update, or sync the code review knowledge graph. Parses codebase with Tree-sitter into a structural graph (functions, classes, imports, calls, tests) stored in SQLite. Enables blast-radius analysis and graph-powered code review. `--scope` selects the lifecycle operation — `full` (rebuild), `update` (working-tree changes; folds former `/graph-update`), `sync` (committed git changes + working-tree update; folds former `/graph-sync`) — default auto-detects from graph status.

**Workflow:**

1. **Detect** — classify request scope and target artifacts.
2. **Execute** — apply required steps with evidence-backed actions.
3. **Verify** — confirm constraints, output quality, and completion evidence.

**Key Rules:**

- **Scope flag** (see [Scope Mode](#scope-mode---scope)): default (no flag) auto-detects via `status` (full if never built, else incremental); `--scope=full` forces rebuild; `--scope=update` = uncommitted working-tree changes (CLI `update`, folds `/graph-update`); `--scope=sync` = committed git changes then working-tree update (CLI `sync` + `update`, folds `/graph-sync`).
- MUST ATTENTION keep claims evidence-based (`file:line`) with confidence >80% to act.
- MUST ATTENTION keep task tracking updated as each step starts/completes.
- NEVER skip mandatory workflow or skill gates.

## Prerequisites

Requires Python 3.10+ with: `pip install tree-sitter tree-sitter-language-pack networkx`

## Scope Mode (`--scope=`)

| `--scope`         | CLI verb(s)                        | What it does                                                              | Former skill    |
| ----------------- | ---------------------------------- | ------------------------------------------------------------------------- | --------------- |
| _(none, default)_ | `status` → `build` or `update`     | Auto-detect: full build if never built, else incremental update           | —               |
| `full`            | `build --json`                     | Force full rebuild (ignore existing graph)                                | —               |
| `update`          | `update --json`                    | Re-parse uncommitted working-tree changes (staged/unstaged)               | `/graph-update` |
| `sync`            | `sync --json` then `update --json` | Sync committed git changes (last_synced_commit → HEAD), then working tree | `/graph-sync`   |

Default (no `--scope`) auto-detects from `status`. `update` = working-tree changes (base `HEAD~1`, options `--base`/`--repo`). `sync` = committed changes + chained working-tree `update` (the sync→update chain is preserved). Pick `--scope` FIRST (default auto-detect), then run the matching branch.

**Automatic HEAD reconciliation (independent of this skill).** Two hooks call the CLI `sync` directly, so a manual run is rarely needed just because HEAD moved:

| Hook | Fires | Catches |
| ---- | ----- | ------- |
| `graph-session-init` | SessionStart (`startup\|resume`) | Commits that landed while the session was away |
| `graph-prompt-sync` | UserPromptSubmit | A `git pull` / `checkout` / `merge` performed MID-session — gated on a cheap `git rev-parse HEAD` compare, so Python spawns only when HEAD actually moved |

The `graph-auto-update` PostToolUse hook covers file EDITS; these two cover HEAD MOVES. Between them the graph should already be current — reach for a manual `--scope=sync` only to force the issue or after a rebase/force-push.

## Steps

### Default (auto-detect) — build or incremental update

1. **Check availability** — Run via Bash:

    ```bash
    python .claude/scripts/code_graph status --json
    ```

    - If error (Python/deps missing): show install instructions and stop
    - If `last_updated` is null: graph never built → proceed with full build
    - If `last_updated` exists: graph exists → proceed with incremental update

2. **Build or update** — Run via Bash:
    - Full build: `python .claude/scripts/code_graph build --json`
    - Incremental: `python .claude/scripts/code_graph update --json`

3. **Report results** from JSON output:
    - Files parsed, nodes created, edges created
    - Languages detected
    - Any errors encountered
    - Build type (full vs incremental)

### `--scope=full` — force full rebuild

```bash
python .claude/scripts/code_graph build --json
```

Always does a complete reparse (ignores existing graph). Report: files parsed, nodes/edges created, languages, build type.

### `--scope=update` — uncommitted working-tree changes (folds `/graph-update`)

```bash
python .claude/scripts/code_graph update --json
```

Diffs the working tree against a base commit (default `HEAD~1`), re-parses changed/added files, removes deleted files from the graph, then re-runs the API + implicit connectors. Options: `--base <commit>` (default `HEAD~1`), `--repo <path>`. Report: files updated/added/deleted, or "Working tree clean — graph already up to date".

### `--scope=sync` — committed git changes + working tree (folds `/graph-sync`)

1. **Sync committed changes** via Bash:

    ```bash
    python .claude/scripts/code_graph sync --json
    ```

    Diffs `last_synced_commit` → HEAD, re-parses changed/added files, removes deleted files, re-runs connectors, stores new HEAD. If it reports `full_rebuild_fallback` (unreachable commit after rebase/force-push), a full rebuild was triggered — inform the user.

2. **Update working tree** (chained — former graph-sync step 4) via Bash:

    ```bash
    python .claude/scripts/code_graph update --json
    ```

3. **Report:** files synced/added/modified/deleted, then working-tree update results (or "working tree clean").

> **Older checkout is a deliberate no-op.** When HEAD is an ANCESTOR of the graph's `last_synced_commit` — you checked out an older branch or commit the graph already covers — `sync` returns `{"reason": "graph_ahead_skipped"}` and changes nothing: no re-parse, and `last_synced_commit` is NOT dragged backwards. This is intentional. `git diff A..B` succeeds in BOTH directions, so without the guard an older checkout would silently rewrite the graph to the older tree. **Trade-off to know:** while sitting on that older branch the graph describes the newer tree, so it can report symbols the checked-out code does not have; run `--scope=full` if you need the graph to match an older branch exactly. Diverged branches are NOT "behind" (neither commit is an ancestor of the other) and still sync normally.

> **sync vs update:** `sync` detects **committed** changes only (`last_synced_commit` → HEAD; use after pull/merge/checkout). `update` detects **working-tree** changes (staged/uncommitted, mid-session). No `--files` flag on `sync`/`update` (auto-detected from git); there is no `incremental` subcommand (use `update`).

## When to Use

- First time setting up graph for a project
- After major refactoring or branch switches
- If graph seems stale or out of sync
- Graph auto-updates via the PostToolUse hook (file edits) and auto-syncs via the SessionStart / UserPromptSubmit hooks (HEAD moves), so manual builds are rarely needed

## Notes

- Graph stored at `.code-graph/graph.db` (SQLite, auto-gitignored)
- Supported: Python, TypeScript, JavaScript, Vue, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++
- Initial build: ~10s for 500 files. Incremental: <2s

## Connectors (Auto-Run)

After build/update, graph connectors run automatically if configured in `project-config.json`:

- **API Endpoints**: Frontend HTTP calls matched to backend routes (`graphConnectors.apiEndpoints`)
- **Implicit Connections**: Entity events, message bus, command events (`graphConnectors.implicitConnections`)

See `/graph-connect-api` and `.claude/docs/code-graph-mechanism.md` for details.

## DB Performance Indexes

The graph database includes optimized indexes created automatically on first build:

- `idx_nodes_name` — fast node name lookups for search
- `idx_edges_kind_source` — composite index for filtered edge queries (kind + source)
- `idx_edges_kind_target` — composite index for filtered edge queries (kind + target)

These indexes are defined in the init schema and auto-create in any new project on first `graph build`.

## Auto-Connect After Build

After building, the CLI automatically runs:

1. **API connector** — detects frontend HTTP calls matching backend route definitions
2. **Implicit connector** — detects behavioral relationships (entity events, bus messages, command events) based on rules in `project-config.json → graphConnectors.implicitConnections[]`

This creates edges for MESSAGE_BUS, TRIGGERS_EVENT, PRODUCES_EVENT, TRIGGERS_COMMAND_EVENT, and API_ENDPOINT — enabling full system flow tracing via the `trace` command.

## Describe (AI-Friendly Command Reference)

Run `python .claude/scripts/code_graph describe --json` to get MCP-style structured descriptions of all available CLI commands, their parameters, and usage. Useful for AI agents to discover graph capabilities programmatically.

## Valid CLI Subcommands

`build`, `update`, `status`, `blast-radius`, `query`, `connections`, `trace`, `search`, `find-path`, `batch-query`, `sync`, `export`, `export-mermaid`, `connect-api`, `connect-implicit`, `review-context`, `describe`

`migrate-paths` is also available to convert existing databases built with absolute file paths into repo-relative storage without reparsing the repository.

### Common Mistakes (DO NOT USE)

| Invalid Command         | Correct Alternative                                               |
| ----------------------- | ----------------------------------------------------------------- |
| `incremental`           | `update --json` (incremental is the default behavior of `update`) |
| `update --files <list>` | `update --json` (auto-detects changed files via git diff)         |
| `build --files <list>`  | `build --json` (always does full rebuild)                         |
| `sync --files <list>`   | `sync --json` (auto-detects from git)                             |
| `file_summary`          | `connections <file> --json`                                       |

---

# Build Graph

Build or incrementally update the persistent code knowledge graph for this repository.

<!-- SYNC:ai-mistake-prevention -->

> **AI Mistake Prevention** — Failure modes to avoid on every task:
>
> **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting.
> **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing.
> **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first.
> **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done.
> **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect.
> **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard.
> **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk.
> **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure.
> **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.

<!-- /SYNC:ai-mistake-prevention -->

<!-- SYNC:critical-thinking-mindset -->

> **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
> **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

<!-- /SYNC:critical-thinking-mindset -->

<!-- SYNC:critical-thinking-mindset:reminder -->

**MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.

<!-- /SYNC:critical-thinking-mindset:reminder -->

<!-- SYNC:ai-mistake-prevention:reminder -->

**MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.

<!-- /SYNC:ai-mistake-prevention:reminder -->

<!-- SYNC:project-protocol-overlay -->

> **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `<protocols-dir>/<Name>.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`.
>
> Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently.

<!-- /SYNC:project-protocol-overlay -->

<!-- SYNC:project-protocol-overlay:reminder -->

**MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `<protocols-dir>/<Name>.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user.

<!-- /SYNC:project-protocol-overlay:reminder -->

## Closing Reminders

**Protocols in force (concise digest of the SYNC/shared blocks this skill carries) — MUST ATTENTION honor each canonical body:**

- **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity.
- **Critical Thinking:** traced `file:line` proof per claim, confidence >80%, NEVER guess as fact.

- **MANDATORY IMPORTANT MUST ATTENTION** break work into small todo tasks using `TaskCreate` BEFORE starting
- **MANDATORY IMPORTANT MUST ATTENTION** search codebase for 3+ similar patterns before creating new code
- **MANDATORY IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act)
- **MANDATORY IMPORTANT MUST ATTENTION** add a final review todo task to verify work quality

**[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.