# SPEC.md — Personal Knowledge Base

## Purpose

A file-based personal knowledge graph that stores structured professional information in YAML, enabling tailored CV generation, interview-based knowledge collection, speaker introductions, and iterative review workflows. The file system is the database — no build step, no server, no compilation required.

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Data format | YAML (one file per entity) |
| Validation & logic | TypeScript (strict mode) |
| Testing | Vitest + fast-check (property-based) |
| Runtime | Node.js (v24+) |
| Version control | Git |
| Automation | Kiro skills (.kiro/skills/) |

## Architecture

```
project-root/
├── kb/                        # Knowledge base data (YAML entities)
│   ├── profiles/              # Person profiles
│   ├── experiences/           # Work experiences
│   ├── skills/                # Skills
│   ├── organizations/         # Organizations
│   ├── projects/              # Projects
│   ├── certifications/        # Certifications
│   ├── tandems/               # Job sharing tandems
│   └── graph-index.yaml       # Central entity/relationship index
├── templates/                 # Document generation templates
├── output/                    # Generated documents (CVs, intros)
├── sources/                   # Imported source documents
├── src/                       # TypeScript validation and logic
│   ├── schemas/               # Entity interfaces and validation
│   ├── io/                    # YAML serialization and file I/O
│   ├── graph/                 # Graph index management
│   ├── interview/             # Gap and conflict detection
│   ├── cv/                    # Relevance selection and tandem generation
│   ├── intro/                 # Introduction generation
│   └── review/                # Completeness scoring and prioritization
└── .kiro/skills/              # Kiro agent skills
    ├── interview-collect/     # Knowledge collection via interview
    ├── cv-generate/           # Tailored CV generation
    ├── talk-intro/            # Speaker introduction generation
    └── kb-review/             # Knowledge base review
```

## Entity Types

- **Person** — name, contact, summary, education, languages, references to skills/experiences/certifications
- **Experience** — title, organization, dates, description, achievements, skills-used
- **Skill** — name, category, level, years, context
- **Organization** — name, industry, optional parent
- **Project** — name, description, organization, dates, skills-used, persons
- **Certification** — name, issuer, date, expires, person
- **Tandem** — exactly 2 partners, shared-vision, complementary-skills, collaboration-model

## Relationship Types

`has_skill`, `worked_at`, `collaborated_with`, `applied_for`, `partners_with`

## Kiro Skills

| Skill | Purpose |
|-------|---------|
| interview-collect | Focused interview sessions (max 10 questions) to collect/update KB data |
| cv-generate | Tailored CVs matched against job postings; supports tandem applications |
| talk-intro | Speaker introductions in 3 length variants adapted to event context |
| kb-review | Completeness scoring, staleness detection, review prioritization |

## Conventions

- File naming: kebab-case (`<entity-id>.yaml`)
- One file per entity
- Graph index updated on every entity change
- All data human-readable and diffable in Git
- TypeScript interfaces use camelCase (deserialized form of kebab-case YAML)

## Rules

1. Never fabricate content in generated documents — only use data present in the knowledge base.
2. Validate entities against schema before persisting.
3. Enforce temporal consistency (start ≤ end) for time-bound entities.
4. Create and use Kiro skills whenever a task of more than 5 lines of code runs for the second time.

## Correctness Properties

15 formal properties validated via property-based testing (fast-check):

1. Entity serialization round-trip
2. Entity schema validation
3. Temporal consistency
4. Graph index consistency
5. Tandem entity integrity
6. Interview session question limit (≤ 10)
7. Gap detection completeness
8. Conflict detection
9. CV relevance selection ordering
10. Tandem application document set (exactly 3 docs)
11. CV output validity and traceability
12. Introduction length variants (short < medium < long)
13. Completeness score calculation
14. Review prioritization ordering
15. File naming convention (kebab-case)

## Current State

- Directory structure: created
- TypeScript project: initialized, dependencies installed
- Entity interfaces: defined (src/schemas/types.ts)
- Validation, I/O, graph, skills, tests: pending implementation