# Implementation Plan: Personal Knowledge Base

## Overview

File-based personal knowledge graph with YAML entity storage, a graph index, and four Kiro skills. TypeScript for validation logic and property-based tests (fast-check). File system is the database — no build step or server required.

Source of truth: `SPEC.md`

## Tasks

- [x] 1. Set up project structure and core configuration
  - [x] 1.1 Create directory structure for the knowledge base
  - [x] 1.2 Initialize TypeScript project for validation and testing
  - [x] 1.3 Create README.md documenting the project

- [x] 2. Implement entity schemas, validation, and property tests
  - [x] 2.1 Define TypeScript interfaces for all entity types
    - `src/schemas/types.ts`
    - _Requirements: 1.1, 1.2, 2.1_

  - [x] 2.2 Implement entity validation functions
    - `src/schemas/validate.ts`
    - _Requirements: 1.3, 1.4, 9.2_

  - [x] 2.3 Write schema property tests (Properties 1, 2, 3, 15)
    - Single test file: `src/schemas/validate.test.ts`
    - Property 1: Entity serialization round-trip
    - Property 2: Entity schema validation (accepts valid, rejects invalid)
    - Property 3: Temporal consistency (start ≤ end)
    - Property 15: File naming convention (kebab-case)
    - _Requirements: 1.1, 1.3, 1.4, 2.1, 8.2, 9.2_

- [x] 3. Implement YAML serialization and file I/O layer
  - [x] 3.1 Create YAML serialization/deserialization utilities
    - `src/io/yaml-utils.ts`
    - _Requirements: 8.2, 2.1_

  - [x] 3.2 Create entity file management functions
    - `src/io/entity-files.ts`
    - _Requirements: 9.2, 1.5_

- [x] 4. Implement graph index management and property tests
  - [x] 4.1 Create graph index read/write logic
    - `src/graph/index-manager.ts`
    - _Requirements: 1.2, 9.4_

  - [x] 4.2 Implement graph index rebuild from entity files
    - Scan entity directories, rebuild `kb/graph-index.yaml`, detect broken references
    - _Requirements: 1.2, 9.4_

  - [x] 4.3 Write graph property tests (Properties 4, 5)
    - Single test file: `src/graph/index-manager.test.ts`
    - Property 4: Graph index consistency
    - Property 5: Tandem entity integrity
    - _Requirements: 1.2, 2.3, 2.4, 9.4_

- [x] 5. Checkpoint — run all tests, verify green
  - `npm test`

- [x] 6. Implement interview-collect Kiro skill
  - [x] 6.1 Create interview-collect SKILL.md
    - `.kiro/skills/interview-collect/SKILL.md`
    - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 9.3_

  - [x] 6.2 Implement gap detection and conflict detection logic
    - `src/interview/gap-detection.ts`
    - `src/interview/conflict-detection.ts`
    - _Requirements: 4.4, 4.5_

  - [x] 6.3 Write interview property tests (Properties 6, 7, 8)
    - Single test file: `src/interview/interview.test.ts`
    - Property 6: Interview session question limit (≤ 10)
    - Property 7: Gap detection completeness
    - Property 8: Conflict detection
    - _Requirements: 4.2, 4.4, 4.5_

- [x] 7. Implement cv-generate Kiro skill
  - [x] 7.1 Create cv-generate SKILL.md and formatting reference
    - `.kiro/skills/cv-generate/SKILL.md`
    - `.kiro/skills/cv-generate/references/cv-formatting-guide.md`
    - _Requirements: 5.1–5.6, 9.3_

  - [x] 7.2 Implement relevance selection and tandem generation logic
    - `src/cv/relevance-selection.ts`
    - `src/cv/tandem-generator.ts`
    - _Requirements: 5.1, 5.2, 5.3, 5.4_

  - [x] 7.3 Create CV templates
    - `templates/cv-individual.md`
    - `templates/cv-tandem.md`
    - _Requirements: 5.5_

  - [x] 7.4 Write CV property tests (Properties 9, 10, 11)
    - Single test file: `src/cv/cv.test.ts`
    - Property 9: CV relevance selection ordering
    - Property 10: Tandem application document set (exactly 3 docs)
    - Property 11: CV output validity and traceability
    - _Requirements: 5.1–5.6_

- [x] 8. Implement talk-intro Kiro skill
  - [x] 8.1 Create talk-intro SKILL.md and template
    - `.kiro/skills/talk-intro/SKILL.md`
    - `templates/intro-speaker.md`
    - _Requirements: 6.1, 6.2, 6.3, 9.3_

  - [x] 8.2 Implement introduction generation logic
    - `src/intro/intro-generator.ts`
    - _Requirements: 6.1, 6.2, 6.3_

  - [x] 8.3 Write intro property test (Property 12)
    - Single test file: `src/intro/intro.test.ts`
    - Property 12: Introduction length variants (short < medium < long)
    - _Requirements: 6.2_

- [x] 9. Implement kb-review Kiro skill
  - [x] 9.1 Create kb-review SKILL.md
    - `.kiro/skills/kb-review/SKILL.md`
    - _Requirements: 7.1, 7.2, 7.3, 7.4, 9.3_

  - [x] 9.2 Implement completeness scoring and prioritization logic
    - `src/review/completeness-score.ts`
    - `src/review/prioritization.ts`
    - _Requirements: 7.2, 7.3_

  - [x] 9.3 Write review property tests (Properties 13, 14)
    - Single test file: `src/review/review.test.ts`
    - Property 13: Completeness score calculation
    - Property 14: Review prioritization ordering
    - _Requirements: 7.2, 7.3_

- [x] 10. Checkpoint — run all tests, verify green
  - `npm test`

- [x] 11. Wire everything together
  - [x] 11.1 Create KB conventions steering file
    - `.kiro/steering/kb-conventions.md`
    - _Requirements: 9.2, 9.4_

  - [x] 11.2 Create seed data (graph-index.yaml + profile stub)
    - `kb/graph-index.yaml` (empty)
    - `kb/profiles/andre-knie.yaml` (minimal valid profile)
    - _Requirements: 1.5, 9.1_

  - [x] 11.3 Wire skills to reference shared validation logic
    - _Requirements: 9.3_

- [x] 12. Final checkpoint — run all tests, verify green
  - `npm test`

## Notes

- Property tests consolidated into per-module test files (fewer files, same coverage)
- SPEC.md is the source of truth; README.md is user-facing documentation
- Seed data (11.2) runs after validation logic exists so it can be validated
- AGENTS.md git workflow (branch, PR) applies at commit time