knowledge-graph

What this skill does

# 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:

1. **spec-to-tasks needs to cache/reuse codebase analysis** - Store agent discoveries for future reuse
2. **task-implementation needs to validate task dependencies and contracts** - Check if required components exist before implementing
3. **Any command needs to query existing patterns/components/APIs** - Retrieve cached codebase context
4. **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](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](references/examples.md) for comprehensive workflow examples.

## KG Schema Reference

See [references/schema.md](references/schema.md) for complete JSON schema with examples.

## Integration Patterns

See [references/integration-patterns.md](references/integration-patterns.md) for detailed integration with Developer Kit commands.

## Error Handling

See [references/error-handling.md](references/error-handling.md) for comprehensive error handling strategies and recovery procedures.

## Performance Considerations

See [references/performance.md](references/performance.md) for optimization strategies and performance characteristics.

## Security

See [references/security.md](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](references/performance.md) and [references/security.md](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](references/error-handling.md) and [references/security.md](references/security.md) for complete constraints and warnings.

## Reference Files

- [schema.md](references/schema.md) - Complete JSON schema
- [query-examples.md](references/query-examples.md) - Query patterns
- [integration-patterns.md](references/integration-patterns.md) - Command integration
- [error-handling.md](references/error-handling.md) - Error handling guide
- [performance.md](references/performance.md) - Performance optimization
- [security.md](references/security.md) - Security considerations
- [examples.md](references/examples.md) - Practical examples