Clangd Graph RAG

Skill: clangd-graph-rag

This skill enables deep semantic and structural analysis of C/C++ codebases using a pre-built Neo4j GraphRAG. It provides insights into call chains, class hierarchies, macro causality, and type aliases.

Activation

Activate this skill when the user asks questions about:

• Project architecture, module responsibilities, or high-level workflows.
• Call chains (caller/callee relationships) or method overriding.
• C++ inheritance structures and template specializations.
• "Magic symbols" generated by macros or complex typedef/using alias chains.
• Semantic code search (e.g., "Find the logic for packet validation").

Setup Requirements

• A Neo4j database populated by the clangd-graph-rag pipeline.
• The graph_mcp_server.py must be configured as an MCP server.
• Environment variables: NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD.

Core Instructions

1. Orientation & Discovery

• Always start by calling get_project_info and get_graph_schema.
• get_project_info provides the path (absolute project root) and a high-level summary.
• get_graph_schema explains the node labels (e.g., FUNCTION, CLASS_STRUCTURE, MACRO, TYPE_ALIAS) and relationships.
• Paths: All path properties in the graph are relative to the project root.

2. Structural Querying (Cypher)

• Use execute_cypher_query for precise structural analysis.
• Semantic Labels: Prefer specific labels (FUNCTION, METHOD, CLASS_STRUCTURE, MACRO, TYPE_ALIAS) over the generic ENTITY label for efficiency.
• Macros: Follow (s)-[:EXPANDED_FROM]->(m:MACRO) to explain symbols generated by the preprocessor. Check the original_name property on the symbol for the raw invocation text.
• Types: Follow (ta:TYPE_ALIAS)-[:ALIAS_OF]->(t) to resolve alias chains (e.g., MyInt2 -> MyInt -> int).
• Calls: Use SHORTEST path selectors (e.g., MATCH p = SHORTEST 5 (a:FUNCTION)-[:CALLS*]->(b:FUNCTION)) to prevent result set explosion.
• Result Management: Always use LIMIT (e.g., LIMIT 10) on custom queries.

3. Implementation Retrieval

• Precise Reading: Use get_source_code_by_id. It retrieves the exact implementation span (including template headers and bodies) as seen by the compiler.
• File Context: Use get_source_code_by_path only when you need to see the entire surrounding file (e.g., checking includes or global variables).
• Labels: Use get_semantic_label if you are unsure which specific label a node has (besides ENTITY).

4. Semantic Search

• Use search_nodes_for_semantic_similarity for concept-based discovery (e.g., "Where is the error handling for disk I/O?").
• Use the returned summary property to understand a node's purpose without reading its code.

Example Workflow: Resolving a "Magic" Symbol

1. Find: MATCH (n:ENTITY {name: 'SomeMagicName'}) RETURN n.id, n.original_name.
2. Trace: MATCH (n)-[:EXPANDED_FROM]->(m:MACRO) RETURN m.name, m.macro_definition.
3. Analyze: Read m.macro_definition or use get_source_code_by_id on the MACRO node to see the ground-truth definition.
4. Context: Look at n.original_name to see the exact arguments passed to the macro at the expansion site.

Source: 2015xli/clangd-graph-rag — distributed by TomeVault.