# 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