/graph-build

name: graph-build
description: Builds or updates the code knowledge graph via tree-sitter AST and SQLite. Use when setting up the graph before search or blast-radius analysis.

Build Code Knowledge Graph

Build or update the `.gauntlet/graph.db` knowledge graph for the current codebase.

Steps

1. **Detect target**: Use the current working directory or a user-specified path.

2. **Check for existing graph**: If `.gauntlet/graph.db` exists, run an incremental update. Otherwise, run a full build.

3. **Run the build script**:

For full build:

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph_build.py <dir>

For incremental update:

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph_build.py <dir> --incremental

4. **Report results**: Show the JSON output including files parsed, nodes created, edges created, and duration.

5. **Suggest next steps**: Recommend searching the graph or running blast radius analysis.

When To Use

• At the start of a session to build structural awareness
• After significant code changes to update the graph
• Before running blast radius analysis or flow tracing
• When the user asks about codebase structure

When NOT To Use

• Querying a graph that already exists (use `gauntlet:graph-search`)
• Building the challenge knowledge base (use `gauntlet:extract`)

What Gets Parsed

The graph extracts nodes (File, Class, Function, Type, Test) and edges (CALLS, IMPORTS_FROM, INHERITS, CONTAINS, IMPLEMENTS, TESTED_BY) from 20+ languages including Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, Ruby, and PHP.

Storage

• Database: `.gauntlet/graph.db` (SQLite with WAL mode)
• Auto-creates `.gauntlet/.gitignore` to prevent commits
• Incremental updates use SHA-256 hashing to skip

unchanged files

Exit Criteria

• [ ] `.gauntlet/graph.db` exists and is a valid SQLite file after

the skill completes; `.gauntlet/.gitignore` exists to prevent the database from being committed

• [ ] Build report JSON includes all four keys: `files_parsed`,

`nodes_created`, `edges_created`, `duration`; values are non-zero for non-empty codebases

• [ ] Incremental update path used when `.gauntlet/graph.db` already

exists (script invoked with `--incremental`); full build only on first run

• [ ] Next-step suggestions presented to the user: search the graph

or run blast-radius analysis