/nav-graph

name: nav-graph
description: Query project knowledge graph. Search across tasks, SOPs, memories, and concepts. Use when user asks "what do we know about X?", "show everything related to X", or "remember this pattern/pitfall/decision".
allowed-tools: Read, Write, Edit, Bash
version: 1.0.0

Navigator Knowledge Graph Skill

Query and manage the unified project knowledge graph. Surfaces relevant knowledge from tasks, SOPs, system docs, and experiential memories.

Why This Exists

Navigator v6.0.0 introduces the Project Knowledge Graph:

• **Unified search**: Query across all knowledge types with one interface
• **Experiential memory**: Patterns, pitfalls, decisions, learnings persist
• **Context-aware retrieval**: Load only relevant knowledge (~1-2k tokens)
• **Relationship traversal**: Find related concepts and documents

When to Invoke

**Query triggers**:

• "What do we know about X?"
• "Show everything related to X"
• "Any pitfalls for X?"
• "What decisions about X?"
• "Find all knowledge about X"

**Memory capture triggers**:

• "Remember this pattern: ..."
• "Remember this pitfall: ..."
• "Remember we decided: ..."
• "Remember this learning: ..."

**Graph management triggers**:

• "Initialize knowledge graph"
• "Rebuild knowledge graph"
• "Show graph stats"

Graph Location

`.agent/knowledge/graph.json` (~1-2k tokens, loaded on query)

Execution Steps

Step 1: Determine Action

**QUERY** (searching knowledge):

User: "What do we know about authentication?"
→ Query graph by concept

**CAPTURE** (storing memory):

User: "Remember: auth changes often break session tests"
→ Create new memory node

**INIT** (building graph):

User: "Initialize knowledge graph"
→ Build graph from existing docs

**STATS** (viewing graph):

User: "Show graph stats"
→ Display graph statistics

Step 2: Load or Initialize Graph

**Check if graph exists**:

if [ -f ".agent/knowledge/graph.json" ]; then
  echo "Graph exists"
else
  echo "No graph found, will initialize"
fi

**Initialize if not exists**:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_builder.py" \
  --agent-dir .agent \
  --output .agent/knowledge/graph.json

Step 3A: Query Knowledge (If QUERY Action)

**Extract concept from user input**:

User: "What do we know about testing?"
→ Concept: testing

User: "Any pitfalls for auth?"
→ Concept: auth (normalized to authentication)

**Run query**:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action query \
  --concept "testing" \
  --graph-path .agent/knowledge/graph.json

**Display results**:

Knowledge Graph: "testing"

TASKS (3)
  - TASK-30: Task Verification Enhancement (completed)
  - TASK-17: Visual Regression Integration (completed)
  - TASK-11: Project Skills Generation (completed)

MEMORIES (2)
  - PITFALL: "Auth changes break session tests" (90%)
  - PATTERN: "Always run unit tests before integration" (85%)

SOPs (1)
  - visual-regression-setup

FILES (5)
  - skills/backend-test/*
  - skills/frontend-test/*

Load details: "Read TASK-30" or "Show testing memories"

Step 3B: Capture Memory (If CAPTURE Action)

**Parse memory from user input**:

User: "Remember this pitfall: auth changes often break session tests"
→ Type: pitfall
→ Summary: "auth changes often break session tests"
→ Concepts: [auth, testing]

User: "Remember we decided to use JWT over sessions for scaling"
→ Type: decision
→ Summary: "use JWT over sessions for scaling"
→ Concepts: [auth, architecture]

**Determine memory type**:

| User Says | Memory Type | |-----------|-------------| | "pattern", "we use", "approach" | pattern | | "pitfall", "watch out", "careful" | pitfall | | "decided", "chose", "because" | decision | | "learned", "discovered", "realized" | learning |

**Create memory**:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action add-memory \
  --memory-type pitfall \
  --summary "auth changes often break session tests" \
  --concepts "auth,testing" \
  --confidence 0.9 \
  --graph-path .agent/knowledge/graph.json

**Write guarantees (v6.17.0+)**: the backing `.md` is written BEFORE the graph node and failures fail loudly (no more path-points-at-nothing nodes); a failed graph save rolls the file back. Concepts are validated against the graph's concept vocabulary — an unknown concept rejects the write and lists the valid vocabulary. Pass `--allow-new-concept` to register genuinely new concepts instead. Graphs without a curated vocabulary skip validation.

**Decisions may carry a TRIZ contradiction (TASK-72)**. When a decision resolved a real tension (improving A worsened B), record it so future sessions can ask "how did we resolve this kind of problem before":

python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action add-memory --memory-type decision \
  --summary "ship new blocking features OFF by default" \
  --concepts "release,configuration" --confidence 0.95 \
  --contradiction "feature value vs regression risk" \
  --separation condition \
  --principle "dynamization (config toggle)"

All three flags are optional and free text; keep `--contradiction` under ~60 chars ("A vs B") because it is