/graph-search

name: graph-search
description: Searches the code knowledge graph by function, class, or type using FTS5 full-text search. Use when locating code entities by name or qualified path.

Search Code Knowledge Graph

Search `.gauntlet/graph.db` for code entities by name.

When NOT To Use

• The graph is missing or stale (use `gauntlet:graph-build`)
• Scoring the impact of a change (use `pensive:blast-radius`)

Steps

1. **Accept query**: Get the search term from the user.

2. **Run the query script**:

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/graph_query.py \
       --action search --query "<term>" --limit 20

Optional filters:

• `--kind Function` to search only functions
• `--kind Class` to search only classes

3. **Display results**: Show qualified name, file path, line numbers, and relevance score for each match.

4. **Offer to read**: Ask if the user wants to read the top result's source file.

Query Intelligence

The search engine detects query patterns:

• **PascalCase** (e.g., `UserService`): boosts Class

and Type results

• **snake_case** (e.g., `get_users`): boosts Function

results

• **Dotted path** (e.g., `app.models.User`): boosts

qualified name matches

Prerequisites

The graph must be built first. If `.gauntlet/graph.db` does not exist, suggest running the `graph-build` skill.

Exit Criteria

• [ ] If `.gauntlet/graph.db` does not exist, the skill surfaces

the missing-prerequisite error and suggests `gauntlet:graph-build` rather than failing silently

• [ ] Results display qualified name, file path, line numbers, and

relevance score for each match (up to `--limit` results)

• [ ] Query intelligence applies correct boost: PascalCase boosts

Class/Type results, snake_case boosts Function results, dotted path boosts qualified name matches

• [ ] User is offered to read the top result's source file after

results are shown

• [ ] A `count: 0` result is reported as "not in the graph" only after

`graph_query.py --action status` shows `node_count` above zero. An unbuilt graph, or one built without tree-sitter, answers every query with zero, and that zero says nothing about the codebase