knowledge-graph

Knowledge Graph Skill

Overview

Persistent JSON storage that caches agent discoveries and codebase analysis. Remember findings across sessions, validate task dependencies, query patterns/components/APIs, skip redundant exploration.

Location: docs/specs/[ID-feature]/knowledge-graph.json

---

When to Use

1. Cache results - Before launching expensive codebase analysis, check if findings are already stored
2. Remember findings - After agent exploration, persist discoveries for future use
3. Reuse discoveries - Query existing context to maintain consistency across tasks
4. Validate dependencies - Check if required components/APIs exist before implementing
5. Look up previous work - Find what patterns, components, or APIs were already discovered

---

Instructions

read-knowledge-graph

Read existing Knowledge Graph or initialize empty structure:

Read file_path="docs/specs/001/knowledge-graph.json"

Returns full KG content. If file missing, returns empty structure and creates on first update.

---

query-knowledge-graph

Query specific sections: components, patterns, apis, integration-points, all

Read file_path="docs/specs/001/knowledge-graph.json"

Filter results by section and process in-memory.

---

update-knowledge-graph

# 1. Read existing
Read file_path="docs/specs/001/knowledge-graph.json"

# 2. Deep-merge updates (arrays append by ID, objects preserve existing)
# 3. Update timestamp
Write file_path="docs/specs/001/knowledge-graph.json" content="<merged JSON>"

Deep-merge rules:

• Arrays: append new items, deduplicate by id field
• Objects: preserve existing keys, add/update new keys
• Always update metadata.updated_at to current ISO timestamp

Complete JSON example for update:

{
  "metadata": {
    "spec_id": "001-hotel-search",
    "created_at": "2026-03-14T10:30:00Z",
    "updated_at": "2026-03-23T10:00:00Z",
    "version": "1.0.0"
  },
  "patterns": {
    "architectural": [
      {
        "id": "pat-001",
        "name": "Repository Pattern",
        "convention": "Extend JpaRepository<Entity, ID>",
        "files": ["src/main/java/**/repository/*Repository.java"]
      }
    ]
  },
  "components": {
    "services": [
      {
        "id": "comp-svc-001",
        "name": "HotelService",
        "location": "src/main/java/com/example/hotel/service/HotelService.java",
        "type": "service",
        "methods": [{"name": "searchHotels", "returns": "List<HotelDTO>"}]
      }
    ]
  }
}

---

validate-against-knowledge-graph

# 1. Read KG
Read file_path="docs/specs/001/knowledge-graph.json"

# 2. Check KG contains required IDs
# 3. Verify actual files exist
Grep pattern="src/**/HotelRepository.java"

Report satisfied dependencies and missing components.

---

validate-contract

# 1. Read KG and task expectations
Read file_path="docs/specs/001/knowledge-graph.json"
Glob pattern="src/**/ExpectedFile.java"
Grep pattern="class ExpectedClass|interface ExpectedInterface"

# 2. Match expectations against KG.provides
# 3. Report satisfied/unsatisfied contracts

---

extract-provides

# 1. Find implementation files
Glob pattern="src/**/*.java"

# 2. Extract symbols
Grep pattern="^(public|protected)? (class|interface|enum) " output_mode="content"

# 3. Classify by directory: /entity/ → entity, /service/ → service, /repository/ → repository
# 4. Update KG.provides with {task_id, file, symbols, type, implemented_at}

---

aggregate-knowledge-graphs

# 1. Find all KG files
Glob pattern="docs/specs/*/knowledge-graph.json"

# 2. Read each, extract patterns.architectural and patterns.conventions
# 3. Write merged .global-knowledge-graph.json
Write file_path="docs/specs/.global-knowledge-graph.json" content="<aggregated>"

---

Schema Structure

knowledge-graph.json
├── metadata (spec_id, created_at, updated_at, version, analysis_sources)
├── codebase_context (project_structure, technology_stack)
├── patterns (architectural[], conventions[])
├── components (controllers[], services[], repositories[], entities[], dtos[])
├── provides[] ({ task_id, file, symbols[], type, implemented_at })
├── apis (internal[], external[])
└── integration_points[]

Complete schema with field definitions: See references/schema.md

---

Error Handling

Scenario	Handling
File not found	Return empty KG; creates on first update
Invalid JSON	Raise error; offer to recreate from analysis
Merge conflicts	Deep-merge preserves existing, adds new with timestamps
Write failure	Log error; continue without caching (non-blocking)

Update workflow:

1. Read: Read → docs/specs/[ID]/knowledge-graph.json
2. Validate update JSON structure
3. Deep-merge updates into KG object
4. Write: Write → same path
5. Verify write succeeded

---

Best Practices

Before expensive operations:

• Query KG first to check for cached analysis
• If fresh (< 7 days), skip redundant exploration
• Offer user choice: use cached or re-explore

After discoveries:

• Update KG immediately after agent analysis completes
• Include source agent/timestamp in metadata
• Batch similar updates, avoid per-operation writes

Freshness guidelines:

• < 7 days: Fresh, safe to use
• 7-30 days: Consider regenerating

• 30 days: Stale, re-analysis recommended

---

Examples

Cache Agent Discoveries (Complete Workflow)

# Step 1: Check existing KG
Read file_path="docs/specs/001/knowledge-graph.json"

# Step 2: Analyze codebase (agent task)
Glob pattern="src/main/java/**/*.java"
Grep pattern="public (class|interface) " output_mode="content"

# Step 3: Build update with discoveries
Write file_path="docs/specs/001/knowledge-graph.json" content="{
  \"metadata\": {
    \"spec_id\": \"001-hotel-search\",
    \"created_at\": \"2026-03-14T10:30:00Z\",
    \"updated_at\": \"2026-03-23T10:00:00Z\",
    \"version\": \"1.0.0\",
    \"analysis_sources\": [{\"agent\": \"general-code-explorer\", \"timestamp\": \"2026-03-23T10:00:00Z\"}]
  },
  \"patterns\": {
    \"architectural\": [{
      \"id\": \"pat-001\",
      \"name\": \"Repository Pattern\",
      \"convention\": \"Extend JpaRepository<Entity, ID>\"
    }]
  },
  \"components\": {
    \"services\": [{
      \"id\": \"comp-svc-001\",
      \"name\": \"HotelService\",
      \"location\": \"src/main/java/com/example/hotel/service/HotelService.java\",
      \"type\": \"service\"
    }],
    \"repositories\": [{
      \"id\": \"comp-repo-001\",
      \"name\": \"HotelRepository\",
      \"location\": \"src/main/java/com/example/hotel/repository/HotelRepository.java\",
      \"type\": \"repository\"
    }]
  }
}"

Validate Task Dependencies

# Read KG and task requirements
Read file_path="docs/specs/001/knowledge-graph.json"

# Verify components exist in codebase
Grep pattern="src/main/java/com/example/hotel/repository/HotelRepository.java"
Grep pattern="src/main/java/com/example/hotel/service/HotelService.java"

# Report validation result
# If all found: "All dependencies satisfied, proceed with implementation"
# If missing: "Warning: HotelService not found. Create it first?"

Query for Context Before Task Generation

# Load KG to get cached context
Read file_path="docs/specs/001/knowledge-graph.json"

# Present summary to user:
# "Found cached analysis (2 days old):
#  - Patterns: Repository Pattern, Service Layer
#  - Components: HotelService, HotelController
#  - Conventions: naming with *Controller/*Service/*Repository
#  Use cached context for task generation?"

More examples: See references/query-examples.md

---

Constraints and Warnings

Critical Constraints:

• Read-only on source code; only creates/updates knowledge-graph.json
• Only reads/writes KG files from docs/specs/[ID]/ paths
• Does NOT generate implementation code automatically

Limitations:

• Validation checks KG only; cannot verify actual codebase if KG outdated
• KG accuracy depends on freshness; re-explore if > 7 days old
• Cross-spec learning only via aggregate operation

Warnings:

• KG > 30 days old may not reflect current codebase state
• Validator may report false negatives if KG predates implementation
• Merge strategy preserves existing values; explicit overwrite required to replace

---

See Also

• references/schema.md - Complete JSON schema with field definitions
• references/query-examples.md - Query patterns and integration examples
• references/integration-patterns.md - Command integration details