---
name: graph-rag-c8a81cd65180
description: Relationship-aware retrieval using graph traversal, entity anchors, community expansion, and hybrid vector plus graph search. Use when chunk similarity alone misses paths, entities, or subsystem context.
metadata:
  category: user-invoked
disable-model-invocation: true
---

Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.

# Graph RAG

## Overview

Use graph-native retrieval when the answer depends on relationships, not just similar text. Graph RAG works well for entity-heavy systems, architecture questions, causal chains, and multi-hop queries that plain vector retrieval often misses.

## When to Use

- The user asks how two concepts connect
- The answer depends on paths, dependencies, or neighborhoods
- Important context is split across multiple files or documents
- Vector search returns individually relevant chunks but weak overall explanations
- You already have entities, references, or graph structure available

## Retrieval Patterns

### Entity Anchor Retrieval

Resolve the question to known entities first, then retrieve around them.

### Neighborhood Expansion

Expand one or two hops across relevant relations only.

### Path Retrieval

Find the path between two anchors when the question is about connection or causality.

### Community Retrieval

Pull the subsystem or cluster around the anchor when local context matters more than one edge.

### Hybrid Retrieval

Use vector search to find candidate anchors, then use the graph to expand and explain.

## Process

### Step 1: Classify the Question

Graph RAG is a fit when the question is one of these:
- connection: "how is A related to B?"
- path: "how does data get from A to B?"
- neighborhood: "what else is involved with A?"
- subsystem: "what belongs to this area?"

If the question is simple lookup, plain retrieval may be enough.

### Step 2: Resolve Anchors

Identify entities, files, symbols, tables, or services named in the question.

If anchor resolution is fuzzy:
- use semantic search first
- rank candidates
- keep the confidence visible

### Step 3: Expand With Bounded Traversal

Expand only across relations that matter to the question:
- imports
- calls
- references
- belongs_to
- decided_by
- documented_in

Bound the retrieval:
- max depth
- max nodes
- relation allowlist

### Step 4: Build Prompt Context

Assemble context as structured evidence, not a raw graph dump:

```markdown
## Anchors
- AuthController
- SessionToken

## Relevant Path
AuthController -> AuthService -> TokenStore -> sessions table

## Supporting Evidence
- src/auth/controller.ts:42
- src/auth/service.ts:88
- src/data/token-store.ts:21
- docs/decisions/2026-01-15-auth.md:12
```

### Step 5: Answer With Relationship Context

The answer should explain:
- what the relevant nodes are
- how they connect
- which evidence supports the path
- where uncertainty remains

## Selection Guide

| Question Shape | Retrieval Strategy |
|---|---|
| direct lookup | vector or keyword only |
| entity + neighbors | anchor + neighborhood expansion |
| how A connects to B | anchor + path retrieval |
| subsystem overview | anchor + community retrieval |
| fuzzy question with named concepts | hybrid vector + graph |

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "Vector search already found the files" | File relevance is not the same as relationship explanation. |
| "Dump the whole graph into the prompt" | Large raw graphs waste context and hide the important path. |
| "More hops is better" | Unbounded traversal quickly turns into noise. |

## Verification

- [ ] The question actually needs relationship-aware retrieval
- [ ] Anchors are resolved with visible confidence
- [ ] Traversal is bounded by depth and relation type
- [ ] Prompt context contains paths and evidence, not a raw graph dump
- [ ] The final answer explains both the conclusion and the connection path

## Anti-Rationalization Table

| Excuse | Counter |
|--------|---------|
| "Vector search already found the files" | File relevance is not the same as relationship explanation. |
| "Dump the whole graph into the prompt" | Large raw graphs waste context and hide the important path. |
| "More hops is better" | Unbounded traversal quickly turns into noise. Bound the expansion. |
| "Graph RAG is overkill for this question" | If the question involves connections, graph retrieval is the right tool. |
| "I'll skip anchor resolution and just expand" | Without anchors, expansion is random. Resolve anchors first for targeted retrieval. |


---
Source attribution: v1truv1us
Original project: https://github.com/v1truv1us/ai-eng-system/blob/eaff192b6e8bcb204a1f1b132b98f748a9b4572e/skills/graph-rag/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2025 John Ferguson

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: v1truv1us
Original project: https://github.com/v1truv1us/ai-eng-system/blob/eaff192b6e8bcb204a1f1b132b98f748a9b4572e/skills/graph-rag/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Development & Engineering, Product Management
Roles: Data Analyst, Data Scientist, Market Research Analyst, ML / AI Engineer, Product Manager
Specialties: API, Database
Tools: Graph Database
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 3c9494f2bfa91bd762de4bafc45cb3fbb0d1a6b3b9b71b61bb97ed3328328f62