Orchestrator/privat/CV/.kiro/specs/personal-knowledge-base/design.md

Design Document: Personal Knowledge Base

Overview

This system implements a file-based personal knowledge graph stored entirely in human-readable formats (YAML for structured data, Markdown for prose content) within a Git repository. It provides Kiro skills for CV generation, interview-based knowledge collection, talk introductions, and iterative review workflows.

The architecture follows the "plain text files as database" pattern — entities and relationships are stored as individual YAML files in a well-defined directory structure. Kiro skills read and write these files directly, using the file system as the query layer. Git provides version history, collaboration, and deployment triggers.

Design Decisions

1. YAML over JSON for data files — YAML supports comments, multi-line strings, and produces cleaner diffs. It's more natural for human editing while remaining machine-parseable.
2. One file per entity — Each person, experience, skill, etc. gets its own file. This keeps diffs focused and enables granular version history.
3. Relationships stored inline and in a separate index — Entity files reference related entities by ID. A central graph index provides a queryable overview.
4. Kiro skills as the primary interface — All automated operations (generation, interviews, reviews) are implemented as Kiro skills following the Agent Skills standard.
5. No database or build step — The file system IS the database. No compilation, indexing, or server required.

Architecture

graph TD
    subgraph "Git Repository"
        subgraph "Knowledge Base (kb/)"
            Profiles[profiles/]
            Experiences[experiences/]
            Skills[skills/]
            Orgs[organizations/]
            Projects[projects/]
            Certs[certifications/]
            Tandems[tandems/]
            Graph[graph-index.yaml]
        end
        subgraph "Kiro Skills (.kiro/skills/)"
            InterviewSkill[interview-collect/]
            CVGenSkill[cv-generate/]
            TalkIntroSkill[talk-intro/]
            ReviewSkill[kb-review/]
        end
        subgraph "Templates (templates/)"
            CVTemplate[cv-templates/]
            IntroTemplate[intro-templates/]
        end
        subgraph "Output (output/)"
            GeneratedCVs[cvs/]
            GeneratedIntros[intros/]
        end
    end

    InterviewSkill -->|reads/writes| Profiles
    InterviewSkill -->|reads/writes| Experiences
    CVGenSkill -->|reads| Profiles
    CVGenSkill -->|reads| Experiences
    CVGenSkill -->|reads| Skills
    CVGenSkill -->|reads| Tandems
    CVGenSkill -->|writes| GeneratedCVs
    TalkIntroSkill -->|reads| Profiles
    TalkIntroSkill -->|writes| GeneratedIntros
    ReviewSkill -->|reads| Graph
    ReviewSkill -->|identifies gaps| Profiles

Component Interaction Flow

1. Data Entry: User runs interview skill → skill asks questions → writes YAML entity files → updates graph index
2. Document Generation: User provides job posting → CV skill reads relevant entities → applies template → writes Markdown output
3. Review: User runs review skill → skill reads graph index → calculates completeness → suggests interview topics

Components and Interfaces

1. Knowledge Base Data Layer (kb/)

The core data store. All files are YAML with defined schemas.

Interface: File system read/write. Skills interact by reading and writing YAML files.

Responsibilities:

• Store entity data in schema-compliant YAML files
• Maintain referential integrity via the graph index
• Provide human-navigable directory structure

2. Graph Index (kb/graph-index.yaml)

A single file that lists all entities and their relationships, serving as a queryable overview of the entire knowledge graph.

Interface: Read by skills to discover entities; updated when entities are added/modified.

Responsibilities:

• List all entities with type, ID, and display name
• List all relationships between entities
• Enable quick lookups without scanning all files

3. Interview Collect Skill (.kiro/skills/interview-collect/)

A Kiro skill that conducts focused interview sessions to collect knowledge.

Interface: Conversational — activated by user request or slash command /interview-collect.

Responsibilities:

• Identify gaps in existing profiles
• Ask focused questions (max 10 per session)
• Write collected data to appropriate entity files
• Update graph index with new entities/relationships
• Detect and surface conflicts with existing data

4. CV Generate Skill (.kiro/skills/cv-generate/)

A Kiro skill that produces tailored CVs from knowledge base data.

Interface: Activated with a job posting as input. Outputs Markdown CV files.

Responsibilities:

• Parse job posting requirements
• Select relevant experiences, skills, projects from the knowledge base
• Generate individual CVs and tandem CVs
• Apply templates for consistent formatting
• Never fabricate content — only use data present in the knowledge base

5. Talk Intro Skill (.kiro/skills/talk-intro/)

A Kiro skill that generates speaker introductions.

Interface: Activated with talk topic and event context. Outputs Markdown intro files.

Responsibilities:

• Generate short (2-3 sentences), medium (paragraph), and long (multi-paragraph) variants
• Adapt tone to event context (technical, business, academic)
• Pull relevant expertise from person profile

6. KB Review Skill (.kiro/skills/kb-review/)

A Kiro skill for iterative knowledge base maintenance.

Interface: Activated by user request. Presents review summary and suggestions.

Responsibilities:

• Calculate completeness scores per profile
• Identify stale information (based on last-modified dates)
• Suggest areas for next interview session
• Recommend relationship additions for graph consistency

Data Models

Entity File Schemas

All entity files follow a common header pattern:

# Common header for all entity files
id: <kebab-case-unique-id>
type: <entity-type>
created: <ISO-8601 date>
modified: <ISO-8601 date>

Person Profile (kb/profiles/<person-id>.yaml)

id: andre-knie
type: person
created: 2025-01-15
modified: 2025-09-01

name:
  first: Andre
  last: Knie
  display: Andre Knie

contact:
  email: # optional
  linkedin: # optional
  location: # optional

summary: |
  Multi-line professional summary text.

languages:
  - language: German
    level: native
  - language: English
    level: fluent

education:
  - institution: # name
    degree: # degree title
    field: # field of study
    start: 2000-09
    end: 2004-06

# References to other entities by ID
skills: [skill-id-1, skill-id-2]
experiences: [exp-id-1, exp-id-2]
certifications: [cert-id-1]
publications: []

Experience (kb/experiences/<experience-id>.yaml)

id: db-cargo-innovation-lead
type: experience
created: 2025-01-15
modified: 2025-09-01

title: Lead IT Innovation Development and AI
organization: db-cargo  # reference to organization entity
start: 2023-04
end: null  # null means current

description: |
  Multi-line description of the role and responsibilities.

achievements:
  - Achievement description one
  - Achievement description two

skills-used: [python, machine-learning, team-leadership]
projects: [project-id-1]

Skill (kb/skills/<skill-id>.yaml)

id: python
type: skill
created: 2025-01-15
modified: 2025-01-15

name: Python
category: programming-language  # programming-language | framework | methodology | soft-skill | domain
level: expert  # beginner | intermediate | advanced | expert
years: 8

context: |
  Optional notes on how/where this skill was developed.

Organization (kb/organizations/<org-id>.yaml)

id: db-cargo
type: organization
created: 2025-01-15
modified: 2025-01-15

name: DB Cargo AG
industry: logistics
parent: deutsche-bahn  # optional reference to parent org
website: # optional

Project (kb/projects/<project-id>.yaml)

id: ai-platform-migration
type: project
created: 2025-01-15
modified: 2025-06-01

name: AI Platform Migration
description: |
  Project description.

organization: db-cargo
start: 2024-01
end: 2024-12
skills-used: [python, aws, terraform]
persons: [andre-knie]

Certification (kb/certifications/<cert-id>.yaml)

id: aws-solutions-architect
type: certification
created: 2025-01-15
modified: 2025-01-15

name: AWS Solutions Architect Associate
issuer: Amazon Web Services
date: 2024-03
expires: 2027-03  # optional
person: andre-knie

Job Sharing Tandem (kb/tandems/<tandem-id>.yaml)

id: froldi-knie
type: tandem
created: 2025-01-15
modified: 2025-04-01

partners: [andre-knie, claudia-froldi]

shared-vision: |
  Description of the tandem's shared professional vision.

complementary-skills: |
  How the partners' skills complement each other.

collaboration-model: |
  How the tandem divides and shares work.

combined-narrative: |
  Joint professional narrative for applications.

joint-competencies:
  - competency-description-1
  - competency-description-2

Graph Index (kb/graph-index.yaml)

# Auto-maintained index of all entities and relationships
entities:
  - id: andre-knie
    type: person
    name: Andre Knie
  - id: claudia-froldi
    type: person
    name: Claudia Froldi
  - id: db-cargo
    type: organization
    name: DB Cargo AG
  # ... all entities listed

relationships:
  - from: andre-knie
    to: db-cargo
    type: worked_at
    context: db-cargo-innovation-lead  # optional reference to experience
  - from: andre-knie
    to: claudia-froldi
    type: partners_with
    context: froldi-knie  # reference to tandem
  - from: andre-knie
    to: python
    type: has_skill
  # ... all relationships listed

Directory Structure

project-root/
├── .kiro/
│   ├── skills/
│   │   ├── interview-collect/
│   │   │   └── SKILL.md
│   │   ├── cv-generate/
│   │   │   ├── SKILL.md
│   │   │   └── references/
│   │   │       └── cv-formatting-guide.md
│   │   ├── talk-intro/
│   │   │   └── SKILL.md
│   │   └── kb-review/
│   │       └── SKILL.md
│   ├── steering/
│   │   └── kb-conventions.md
│   └── specs/
│       └── personal-knowledge-base/
├── kb/
│   ├── profiles/
│   │   ├── andre-knie.yaml
│   │   └── claudia-froldi.yaml
│   ├── experiences/
│   ├── skills/
│   ├── organizations/
│   ├── projects/
│   ├── certifications/
│   ├── tandems/
│   │   └── froldi-knie.yaml
│   └── graph-index.yaml
├── templates/
│   ├── cv-individual.md
│   ├── cv-tandem.md
│   └── intro-speaker.md
├── output/
│   ├── cvs/
│   └── intros/
├── sources/
│   └── (imported PDFs/DOCX for reference)
└── README.md

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property 1: Entity serialization round-trip

For any valid knowledge base entity (person, experience, skill, organization, project, certification, or tandem), serializing it to YAML and deserializing the result SHALL produce an equivalent entity with all attributes preserved.

Validates: Requirements 2.1, 8.2

Property 2: Entity schema validation

For any entity with a declared type, the validation function SHALL accept the entity if and only if all required attributes for that type are present and correctly typed. Entities missing required fields SHALL be rejected with an error identifying the missing fields.

Validates: Requirements 1.1, 1.3

Property 3: Temporal consistency

For any time-bound entity (experience, role, project, certification) where both start and end dates are present, the start date SHALL be less than or equal to the end date.

Validates: Requirements 1.4

Property 4: Graph index consistency

For any set of entity files in the knowledge base, the graph index SHALL list exactly those entities (no missing, no extra). All relationships in the graph index SHALL reference entity IDs that exist in the entities list, and all relationship types SHALL be from the defined set.

Validates: Requirements 1.2, 9.4

Property 5: Tandem entity integrity

For any tandem entity, it SHALL reference exactly two existing person profiles as partners, and SHALL contain all tandem-specific fields (shared vision, complementary skills, collaboration model).

Validates: Requirements 2.3, 2.4

Property 6: Interview session question limit

For any interview session generated from any profile state and topic area, the number of questions SHALL not exceed 10.

Validates: Requirements 4.2

Property 7: Gap detection completeness

For any person profile with missing optional or required attributes, the gap detection function SHALL identify all missing attributes. The set of detected gaps SHALL be a superset of the actually missing required fields.

Validates: Requirements 4.4

Property 8: Conflict detection

For any existing entity and a proposed update that changes an existing attribute value, the conflict detection function SHALL flag the conflicting fields.

Validates: Requirements 4.5

Property 9: CV relevance selection

For any job posting with specified skill requirements and any person profile, the CV generator SHALL select only experiences and skills that have non-empty intersection with the posting requirements. Selected items SHALL appear before non-matching items in the output.

Validates: Requirements 5.1, 5.2

Property 10: Tandem application document set

For any tandem application to a job posting, the generator SHALL produce exactly 3 documents: one combined tandem CV referencing both partners, and one individual CV per partner. The tandem CV SHALL contain information from both partner profiles.

Validates: Requirements 5.3, 5.4

Property 11: CV output validity and traceability

For any generated CV, the output SHALL be valid Markdown. Every skill name, organization name, job title, and date mentioned in the CV SHALL be traceable to an entity in the source knowledge base.

Validates: Requirements 5.5, 5.6

Property 12: Introduction length variants

For any talk introduction generation request, the system SHALL produce exactly three variants where the character count satisfies: short < medium < long.

Validates: Requirements 6.2

Property 13: Completeness score calculation

For any person profile, the completeness score SHALL equal the ratio of filled attributes to total defined attributes (including relationship coverage). A profile with all attributes filled SHALL score 1.0, and an empty profile SHALL score close to 0.0.

Validates: Requirements 7.3

Property 14: Review prioritization ordering

For any set of entities with varying last-modified dates and completeness scores, the review prioritization SHALL rank entities with lower completeness scores and older modification dates higher than entities with higher completeness and recent modifications.

Validates: Requirements 7.2

Property 15: File naming convention

For any entity ID in the knowledge base, the corresponding file name SHALL match the pattern <entity-id>.yaml where entity-id consists only of lowercase letters, numbers, and hyphens (kebab-case).

Validates: Requirements 9.2

Error Handling

File System Errors

Error Condition	Handling Strategy
Entity file not found	Return descriptive error with entity ID and expected path
YAML parse error	Return error with file path, line number, and parse message
Schema validation failure	Return list of missing/invalid fields with expected types
Duplicate entity ID	Reject creation, report existing entity location
Broken relationship reference	Log warning, include in review skill's integrity report

Document Generation Errors

Error Condition	Handling Strategy
Empty profile (no data to generate from)	Return error explaining minimum data requirements
Job posting cannot be parsed	Return error with guidance on expected posting format
Template not found	Fall back to built-in default template, log warning
Referenced entity missing during generation	Skip the reference, add note to output indicating gap

Interview Session Errors

Error Condition	Handling Strategy
Conflicting data detected	Present both values to user, ask for resolution
Session interrupted (user stops early)	Persist any data collected so far, mark session incomplete
Invalid user input (wrong format)	Re-ask the question with format guidance

Source Document Ingestion Errors

Error Condition	Handling Strategy
PDF cannot be read	Report parsing failure with file name and error details
DOCX cannot be read	Report parsing failure with file name and error details
Extracted data ambiguous	Present multiple interpretations to user for selection

Testing Strategy

Property-Based Testing

Library: fast-check (TypeScript/JavaScript) — chosen because Kiro skills execute in a Node.js environment and fast-check provides excellent arbitrary generators for structured data.

Configuration: Minimum 100 iterations per property test.

Tag format: Each test tagged with Feature: personal-knowledge-base, Property {N}: {title}

Property-based tests will cover:

• Entity serialization round-trips (Property 1)
• Schema validation logic (Property 2)
• Temporal consistency checks (Property 3)
• Graph index integrity (Property 4)
• Tandem entity validation (Property 5)
• Interview question limits (Property 6)
• Gap detection (Property 7)
• Conflict detection (Property 8)
• CV relevance selection (Property 9)
• Tandem document generation (Property 10)
• CV traceability (Property 11)
• Introduction length ordering (Property 12)
• Completeness scoring (Property 13)
• Review prioritization (Property 14)
• File naming validation (Property 15)

Unit Tests (Example-Based)

Unit tests cover specific scenarios and edge cases not suited for PBT:

• Multiple profiles coexist without conflict (Req 1.5)
• Source document extraction with known sample files (Req 3.1, 3.2)
• Extraction presents confirmation before persisting (Req 3.3)
• Corrupted file produces descriptive error (Req 3.4)
• Interview session covers single topic (Req 4.1)
• Interview writes collected data to graph (Req 4.3)
• Talk intro references relevant expertise (Req 6.1)
• Tone adaptation for different contexts (Req 6.3)
• Relationship suggestions use valid types (Req 7.4)

Integration Tests

• Git version control preserves profile history (Req 2.2)
• Deployment pipeline triggers on push (Req 8.3)
• End-to-end: import PDF → extract → confirm → persist → generate CV

Smoke Tests

• Review skill activates and produces output (Req 7.1)
• All expected directories exist (Req 9.1)
• Skills are in .kiro/skills/ with valid SKILL.md (Req 9.3)
• README exists with required sections (Req 8.4)
• Git repository is valid (Req 8.1)