Migrate all repos into monorepo context folders
Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp,
Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit,
Projekt-KIQ-HP, teamlandkarte-mcp
Dhive: Jury-Voting
Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation)
Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more
Shared/references: symphony (read-only)
Bahn repos remain available as independent remotes - this monorepo
pulls them in via subtree, the originals are untouched.
This commit is contained in:
@@ -0,0 +1 @@
|
||||
{"specId": "9061ba61-554c-45b6-87f0-88e69adb2038", "workflowType": "requirements-first", "specType": "feature"}
|
||||
@@ -0,0 +1,570 @@
|
||||
# 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
|
||||
|
||||
```mermaid
|
||||
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:
|
||||
|
||||
```yaml
|
||||
# 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`)
|
||||
|
||||
```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`)
|
||||
|
||||
```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`)
|
||||
|
||||
```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`)
|
||||
|
||||
```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`)
|
||||
|
||||
```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`)
|
||||
|
||||
```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`)
|
||||
|
||||
```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`)
|
||||
|
||||
```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](https://github.com/dubzzz/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)
|
||||
@@ -0,0 +1,121 @@
|
||||
# Requirements Document
|
||||
|
||||
## Introduction
|
||||
|
||||
A personal knowledge base system that stores structured information about the user (Andre Knie) and job sharing partners (e.g., Claudia Froldi) in a knowledge graph. The system enables generation of tailored CVs for specific job openings, talk introductions, and other professional documents. It supports iterative knowledge collection through short interview sessions, provides Kiro skills for common tasks, and uses Git for version control and automatic deployment.
|
||||
|
||||
## Glossary
|
||||
|
||||
- **Knowledge_Base**: The structured data store containing all personal and professional information about registered persons, organized as a knowledge graph
|
||||
- **Knowledge_Graph**: A graph-based data structure representing entities (persons, skills, experiences, organizations, roles) and their relationships
|
||||
- **Person_Profile**: A complete record of a person's professional and personal information within the Knowledge_Base
|
||||
- **Job_Sharing_Tandem**: A pair of persons who apply jointly for positions, sharing responsibilities and presenting combined qualifications
|
||||
- **Kiro_Skill**: A reusable Kiro skill file (.md in .kiro/skills/) that automates a specific task such as CV generation or interview collection
|
||||
- **Interview_Session**: A structured, short conversational interaction to collect or update information from the user
|
||||
- **Document_Generator**: The component responsible for producing tailored output documents (CVs, introductions) from Knowledge_Base data
|
||||
- **Source_Document**: An existing file (PDF, DOCX) containing information to be extracted and integrated into the Knowledge_Base
|
||||
- **Deployment_Pipeline**: The Git-based mechanism that enables automatic deployment of the knowledge base and skills upon push
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement 1: Knowledge Graph Data Model
|
||||
|
||||
**User Story:** As a user, I want my professional information stored in a structured knowledge graph, so that relationships between people, skills, experiences, and roles are explicitly represented and queryable.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Knowledge_Graph SHALL represent persons, skills, experiences, organizations, roles, projects, and certifications as distinct entity types
|
||||
2. THE Knowledge_Graph SHALL represent relationships between entities including "has_skill", "worked_at", "collaborated_with", "applied_for", and "partners_with"
|
||||
3. WHEN a new entity is added to the Knowledge_Graph, THE Knowledge_Base SHALL validate that required attributes for the entity type are present
|
||||
4. THE Knowledge_Graph SHALL store temporal information (start date, end date) for time-bound entities such as experiences and roles
|
||||
5. THE Knowledge_Graph SHALL support multiple Person_Profiles within a single Knowledge_Base instance
|
||||
|
||||
### Requirement 2: Person Profile Management
|
||||
|
||||
**User Story:** As a user, I want to maintain detailed profiles for myself and my job sharing partners, so that complete and accurate information is available for document generation.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Knowledge_Base SHALL store the following attributes for each Person_Profile: name, contact details, professional summary, education history, work experience, skills, certifications, languages, and publications
|
||||
2. WHEN a Person_Profile is updated, THE Knowledge_Base SHALL preserve the full history of changes via Git version control
|
||||
3. THE Knowledge_Base SHALL support linking two Person_Profiles as a Job_Sharing_Tandem with shared attributes such as joint competencies and combined experience narrative
|
||||
4. WHEN a Job_Sharing_Tandem is defined, THE Knowledge_Base SHALL store tandem-specific information including shared vision, complementary skills, and collaboration model
|
||||
|
||||
### Requirement 3: Source Document Ingestion
|
||||
|
||||
**User Story:** As a user, I want to import information from existing CVs and documents, so that I do not have to re-enter information already available in files.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN a Source_Document in PDF format is provided, THE Knowledge_Base SHALL extract text content and map it to Knowledge_Graph entities
|
||||
2. WHEN a Source_Document in DOCX format is provided, THE Knowledge_Base SHALL extract text content and map it to Knowledge_Graph entities
|
||||
3. WHEN information is extracted from a Source_Document, THE Knowledge_Base SHALL present the extracted entities to the user for confirmation before persisting
|
||||
4. IF a Source_Document cannot be parsed, THEN THE Knowledge_Base SHALL report the parsing failure with a descriptive error message
|
||||
|
||||
### Requirement 4: Interview Skill for Knowledge Collection
|
||||
|
||||
**User Story:** As a user, I want a Kiro skill that conducts short interview sessions with me, so that I can iteratively add and refine information in my knowledge base through conversation.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Interview_Session Kiro_Skill SHALL ask focused questions covering one topic area per session (e.g., a single role, a single project, a single skill cluster)
|
||||
2. THE Interview_Session Kiro_Skill SHALL limit each session to a maximum of 10 questions to keep interactions short
|
||||
3. WHEN an Interview_Session is completed, THE Kiro_Skill SHALL update the Knowledge_Graph with the collected information
|
||||
4. THE Interview_Session Kiro_Skill SHALL identify gaps in existing Person_Profiles and prioritize questions that fill those gaps
|
||||
5. WHEN the user provides information that contradicts existing Knowledge_Graph data, THE Kiro_Skill SHALL highlight the conflict and ask the user to resolve it
|
||||
|
||||
### Requirement 5: CV Generation Skill
|
||||
|
||||
**User Story:** As a user, I want a Kiro skill that generates CVs tailored to specific job openings, so that my applications highlight the most relevant qualifications for each position.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN a job posting is provided, THE Document_Generator Kiro_Skill SHALL analyze the posting requirements and select relevant entries from the Person_Profile
|
||||
2. THE Document_Generator Kiro_Skill SHALL produce a CV that emphasizes skills and experiences matching the job posting requirements
|
||||
3. WHERE a Job_Sharing_Tandem applies jointly, THE Document_Generator Kiro_Skill SHALL generate a combined tandem CV showing complementary qualifications
|
||||
4. WHERE a Job_Sharing_Tandem applies jointly, THE Document_Generator Kiro_Skill SHALL also generate individual CVs for each partner tailored to the same posting
|
||||
5. THE Document_Generator Kiro_Skill SHALL output CVs in Markdown format suitable for conversion to PDF or DOCX
|
||||
6. WHEN generating a CV, THE Document_Generator Kiro_Skill SHALL include only information present in the Knowledge_Base without fabricating content
|
||||
|
||||
### Requirement 6: Talk Introduction Generation Skill
|
||||
|
||||
**User Story:** As a user, I want a Kiro skill that generates speaker introductions for talks and events, so that I have context-appropriate introductions ready.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN a talk topic and event context are provided, THE Document_Generator Kiro_Skill SHALL generate a speaker introduction highlighting relevant expertise from the Person_Profile
|
||||
2. THE Document_Generator Kiro_Skill SHALL produce introductions in three length variants: short (2-3 sentences), medium (one paragraph), and long (multiple paragraphs)
|
||||
3. THE Document_Generator Kiro_Skill SHALL adapt the tone and emphasis based on the event context (technical conference, business meeting, academic setting)
|
||||
|
||||
### Requirement 7: Iterative Enhancement Workflow
|
||||
|
||||
**User Story:** As a user, I want a structured workflow for regular knowledge base enhancement sessions, so that my information stays current and grows over time.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Knowledge_Base SHALL provide a Kiro_Skill that initiates a review session summarizing recent changes and identifying stale or incomplete information
|
||||
2. WHEN a review session is initiated, THE Kiro_Skill SHALL present a prioritized list of areas needing updates based on time since last review and completeness score
|
||||
3. THE Knowledge_Base SHALL track a completeness score for each Person_Profile based on the proportion of filled attributes and relationship coverage
|
||||
4. WHEN new skills or experiences are added, THE Kiro_Skill SHALL suggest related entities and relationships to maintain graph consistency
|
||||
|
||||
### Requirement 8: Git-Based Version Control and Deployment
|
||||
|
||||
**User Story:** As a user, I want all knowledge base data and skills stored in Git, so that changes are tracked and deployment happens automatically on push.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Knowledge_Base SHALL store all data files, skill files, and configuration in a Git-compatible directory structure
|
||||
2. THE Knowledge_Base SHALL use human-readable file formats (Markdown, YAML, or JSON) for all stored data to enable meaningful Git diffs
|
||||
3. WHEN changes are committed and pushed, THE Deployment_Pipeline SHALL make the updated knowledge base and skills available without manual intervention
|
||||
4. THE Knowledge_Base SHALL include a README documenting the directory structure, available skills, and usage instructions
|
||||
|
||||
### Requirement 9: Knowledge Base File Organization
|
||||
|
||||
**User Story:** As a user, I want a clean and predictable file structure, so that I can navigate and manually edit the knowledge base when needed.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Knowledge_Base SHALL organize data into separate directories for profiles, graph relationships, skills, templates, and generated outputs
|
||||
2. THE Knowledge_Base SHALL use consistent naming conventions across all files (kebab-case for file names, defined schema for data files)
|
||||
3. WHEN a new Kiro_Skill is created, THE Knowledge_Base SHALL place it in the .kiro/skills/ directory following Kiro skill file conventions
|
||||
4. THE Knowledge_Base SHALL maintain an index file listing all entities in the Knowledge_Graph for quick reference
|
||||
@@ -0,0 +1,155 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user