Knowledge Graph Skill

Overview

The Knowledge Graph (KG) is a persistent JSON file that stores discoveries from codebase analysis, eliminating redundant exploration and enabling task validation.

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

Key Benefits:

✅ Avoid re-exploring already-analyzed codebases
✅ Validate task dependencies against actual codebase state
✅ Share discoveries across team members
✅ Accelerate task generation with cached context

When to Use

Use this skill when:

spec-to-tasks needs to cache/reuse codebase analysis - Store agent discoveries for future reuse
task-implementation needs to validate task dependencies and contracts - Check if required components exist before implementing
Any command needs to query existing patterns/components/APIs - Retrieve cached codebase context
Reducing redundant codebase exploration - Avoid re-analyzing already-explored code

Trigger phrases:

"Load knowledge graph"
"Query knowledge graph"
"Update knowledge graph"
"Validate against knowledge graph"
"Check if component exists"
"Find existing patterns"

Instructions

Available Operations

1. read-knowledge-graph - Load and parse KG for a specification

Input: Path to spec folder (e.g., docs/specs/001-feature/)
Output: KG object with metadata, patterns, components, APIs

2. query-knowledge-graph - Query specific sections (components, patterns, APIs)

Input: Spec folder, query type, optional filters
Output: Filtered results matching criteria

3. update-knowledge-graph - Update KG with new discoveries

Input: Spec folder, updates (partial KG), source description
Output: Merged KG with new findings

4. validate-against-knowledge-graph - Validate task dependencies against KG

Input: Spec folder, requirements (components, APIs, patterns)
Output: Validation report with errors/warnings

5. validate-contract - Validate provides/expects between tasks

Input: Spec folder, expects (files + symbols), completed dependencies
Output: Satisfied/unsatisfied expectations report

6. extract-provides - Extract symbols from implemented files

Input: Array of file paths
Output: Array of provides with file, symbols, type

7. aggregate-knowledge-graphs - Merge patterns from all specs

Input: Project root path
Output: Global KG with deduplicated patterns

See references/query-examples.md for detailed usage examples.

Examples

Input/Output Examples

Read Knowledge Graph:

Input: /knowledge-graph read docs/specs/001-hotel-search/
Output: {
  metadata: { spec_id: "001-hotel-search", version: "1.0" },
  patterns: { architectural: [...], conventions: [...] },
  components: { controllers: [...], services: [...]}
}

Query Components:

Input: /knowledge-graph query docs/specs/001-hotel-search/ components {"category": "services"}
Output: [{ id: "comp-svc-001", name: "HotelSearchService", type: "service"}]

Update Knowledge Graph:

Input: /knowledge-graph update docs/specs/001-hotel-search/ {
  patterns: { architectural: [{ name: "Repository Pattern"}] }
}
Output: "Added 1 pattern to knowledge graph"

Validate Dependencies:

Input: /knowledge-graph validate docs/specs/001-hotel-search/ {
  components: ["comp-repo-001"]
}
Output: { valid: true, errors: [], warnings: [] }

See references/examples.md for comprehensive workflow examples.

KG Schema Reference

See references/schema.md for complete JSON schema with examples.

Integration Patterns

See references/integration-patterns.md for detailed integration with Developer Kit commands.

Error Handling

See references/error-handling.md for comprehensive error handling strategies and recovery procedures.

Performance Considerations

See references/performance.md for optimization strategies and performance characteristics.

Security

See references/security.md for security considerations, threat mitigation, and best practices.

Best Practices

When to Query KG: Before codebase analysis, task generation, dependency validation

When to Update KG: After agent discoveries, component implementation, pattern discovery

KG Freshness:

< 7 days: Fresh
7-30 days: Stale, warn user
30 days: Very stale, offer regeneration

See references/performance.md and references/security.md for detailed best practices.

Constraints and Warnings

Critical Constraints

Source-Code Safe Operations: Does NOT modify source code files. Only creates/updates knowledge-graph.json files.
Path Validation: Only reads/writes KG files from docs/specs/[ID]/ paths.
No Automatic Code Generation: Caches analysis results, does NOT generate implementation code.

Limitations

Validation Scope: Checks components exist in KG, but cannot verify if they exist in actual codebase if KG is outdated
Freshness Dependency: KG accuracy depends on how recently it was updated
Single-Spec First: Each KG is primarily specific to a single specification
File Size: KG files can grow large (>1MB) for complex specifications

See references/error-handling.md and references/security.md for complete constraints and warnings.

Reference Files

schema.md - Complete JSON schema
query-examples.md - Query patterns
integration-patterns.md - Command integration
error-handling.md - Error handling guide
performance.md - Performance optimization
security.md - Security considerations
examples.md - Practical examples