Orchestrator/privat/CV/.kiro/specs/linkedin-profile-revamp/design.md

# Design Document: LinkedIn-Profil-Revamp

## Overview

Dieses Design beschreibt die technische Umsetzung eines neuen Kiro Skills `linkedin-profile` zur automatisierten Generierung und Optimierung von LinkedIn-Profilinhalten aus der bestehenden Knowledge Base. Der Skill erzeugt optimierte Texte für Headline, About-Section und Experience-Beschreibungen, generiert eine Content-Strategie und implementiert ein Tracking-System für LinkedIn-Metriken.

### Design-Entscheidungen

1. **Neuer Kiro Skill statt Standalone-Script** — Folgt dem etablierten Muster der bestehenden Skills (consultant-profile, cv-generate, talk-intro). Ermöglicht interaktive Nutzung und iterative Verfeinerung.
2. **KB als Single Source of Truth** — Alle LinkedIn-Inhalte werden aus den bestehenden YAML-Entities generiert. Keine Duplizierung von Daten.
3. **Tracking als YAML-Entity** — LinkedIn-Metriken werden als neue Entity-Kategorie `kb/tracking/` gespeichert, konsistent mit dem bestehenden Datenmodell.
4. **Markdown-Output mit strukturierten Sektionen** — Output-Dateien enthalten alle generierten Profilsektionen in einem einzigen Dokument, analog zum Talk-Intro-Skill.
5. **Constraint-Validierung zur Generierungszeit** — Zeichenlimits (220 für Headline, 2.600 für About) werden programmatisch validiert, nicht nur als Richtlinie.
6. **Content-Strategie als Template** — Die Content-Strategie wird als wiederverwendbares Template generiert, das quartalsweise aktualisiert werden kann.

## Architecture

```mermaid
graph TD
    subgraph "Knowledge Base (kb/)"
        Profile[profiles/andre-knie.yaml]
        Experiences[experiences/*.yaml]
        Skills[skills/*.yaml]
        Projects[projects/*.yaml]
        Orgs[organizations/*.yaml]
        Tracking[tracking/*.yaml]
    end

    subgraph "Kiro Skill (.kiro/skills/linkedin-profile/)"
        SkillMD[SKILL.md]
    end

    subgraph "Source Modules (src/linkedin/)"
        HeadlineGen[headline-generator.ts]
        AboutGen[about-generator.ts]
        ExperienceGen[experience-generator.ts]
        ContentStrategy[content-strategy.ts]
        TrackingMgr[tracking-manager.ts]
        Constraints[constraints.ts]
    end

    subgraph "Shared Modules (src/)"
        Validate[schemas/validate.ts]
        Types[schemas/types.ts]
        YamlUtils[io/yaml-utils.ts]
        EntityFiles[io/entity-files.ts]
    end

    subgraph "Output (output/linkedin/)"
        ProfileDoc[profile-optimized.md]
        StrategyDoc[content-strategy.md]
        TrackingReport[tracking-report.md]
    end

    SkillMD -->|orchestrates| HeadlineGen
    SkillMD -->|orchestrates| AboutGen
    SkillMD -->|orchestrates| ExperienceGen
    SkillMD -->|orchestrates| ContentStrategy
    SkillMD -->|orchestrates| TrackingMgr

    HeadlineGen -->|reads| Profile
    HeadlineGen -->|reads| Experiences
    AboutGen -->|reads| Profile
    AboutGen -->|reads| Projects
    ExperienceGen -->|reads| Experiences
    ExperienceGen -->|reads| Skills
    ExperienceGen -->|reads| Projects
    ContentStrategy -->|reads| Profile
    TrackingMgr -->|reads/writes| Tracking

    HeadlineGen -->|validates| Constraints
    AboutGen -->|validates| Constraints
    ExperienceGen -->|validates| Constraints

    HeadlineGen -->|uses| EntityFiles
    AboutGen -->|uses| EntityFiles
    ExperienceGen -->|uses| EntityFiles
    TrackingMgr -->|uses| YamlUtils

    HeadlineGen -->|writes| ProfileDoc
    AboutGen -->|writes| ProfileDoc
    ExperienceGen -->|writes| ProfileDoc
    ContentStrategy -->|writes| StrategyDoc
    TrackingMgr -->|writes| TrackingReport
```

### Komponenten-Interaktionsfluss

1. **Profil-Generierung**: User aktiviert Skill → Skill liest KB-Entities → generiert optimierte Texte → validiert Constraints → schreibt Output
2. **Content-Strategie**: User fordert Strategie an → Skill analysiert Profil und Themen → generiert Redaktionsplan → schreibt Template
3. **Tracking**: User gibt Metriken ein → Skill speichert als YAML → berechnet Trends → generiert Report

## Components and Interfaces

### 1. LinkedIn Profile Skill (`.kiro/skills/linkedin-profile/`)

Orchestriert die gesamte LinkedIn-Optimierung als Kiro Skill.

**Interface**: Manuell aktiviert durch User-Request.

**Verantwortlichkeiten**:
- Koordination der Generierungsmodule
- Interaktive Verfeinerung mit dem User
- Output-Management

### 2. Headline Generator (`src/linkedin/headline-generator.ts`)

Generiert optimierte LinkedIn-Headlines aus KB-Daten.

**Interface**:
```typescript
interface HeadlineOptions {
  personId: string;
  emphasis?: 'dual-role' | 'ai-expert' | 'leadership';
  variants?: number; // default: 3
}

function generateHeadlines(options: HeadlineOptions): HeadlineResult;

interface HeadlineResult {
  variants: HeadlineVariant[];
  validation: ConstraintValidation;
}

interface HeadlineVariant {
  text: string;
  charCount: number;
  keywords: string[];
  roles: string[];
}
```

**Constraints**:
- Max 220 Zeichen
- Muss beide Rollen enthalten (DB InfraGO + Data Hive Cassel)
- Kein Fachjargon
- Mindestens ein differenzierendes Element

### 3. About Section Generator (`src/linkedin/about-generator.ts`)

Generiert die About-Section mit Hook, Story und CTA.

**Interface**:
```typescript
interface AboutOptions {
  personId: string;
  tone?: 'nahbar' | 'fachlich' | 'inspirierend';
  includeStats?: boolean; // default: true
}

function generateAbout(options: AboutOptions): AboutResult;

interface AboutResult {
  fullText: string;
  charCount: number;
  hookPreview: string; // erste 2 Zeilen (vor "mehr anzeigen")
  sections: {
    hook: string;
    mission: string;
    expertise: string;
    cta: string;
  };
  validation: ConstraintValidation;
}
```

**Constraints**:
- Max 2.600 Zeichen
- Hook in ersten 2 Zeilen sichtbar
- Drei Kernthemen benannt
- Konkrete Belege enthalten
- CTA am Ende

### 4. Experience Generator (`src/linkedin/experience-generator.ts`)

Generiert wirkungsorientierte Experience-Beschreibungen.

**Interface**:
```typescript
interface ExperienceOptions {
  personId: string;
  experienceIds?: string[]; // specific experiences, or all if omitted
  keywords?: string[]; // SEO keywords to include
}

function generateExperiences(options: ExperienceOptions): ExperienceResult[];

interface ExperienceResult {
  experienceId: string;
  title: string;
  organization: string;
  description: string;
  keywords: string[];
  achievements: string[];
  validation: ConstraintValidation;
}
```

**Constraints**:
- Ergebnisse statt Aufgaben
- Relevante Keywords für LinkedIn-Suche
- Messbare Erfolge wo vorhanden

### 5. Content Strategy Generator (`src/linkedin/content-strategy.ts`)

Generiert einen strukturierten Content-Plan.

**Interface**:
```typescript
interface ContentStrategyOptions {
  personId: string;
  quarter: string; // e.g., "2026-Q3"
  existingFormats?: string[]; // podcast, column, etc.
}

function generateContentStrategy(options: ContentStrategyOptions): ContentStrategy;

interface ContentStrategy {
  postingFrequency: string;
  themeCluster: ThemeCluster[];
  weeklyPlan: WeeklySlot[];
  engagementRoutine: EngagementRoutine;
  formatMix: FormatMix;
}
```

### 6. Tracking Manager (`src/linkedin/tracking-manager.ts`)

Verwaltet LinkedIn-Metriken als YAML-Entities.

**Interface**:
```typescript
interface TrackingEntry {
  id: string;
  type: 'linkedin-tracking';
  date: string; // ISO date
  metrics: {
    profileViews: number;
    searchAppearances: number;
    connectionRequests: number;
    postImpressions?: number;
    engagementRate?: number;
    comments?: number;
    reposts?: number;
  };
  posts?: PostMetric[];
}

interface PostMetric {
  title: string;
  date: string;
  format: 'text' | 'carousel' | 'video' | 'newsletter';
  impressions: number;
  engagementRate: number;
  comments: number;
  reposts: number;
  isBestPractice?: boolean;
}

function addTrackingEntry(entry: TrackingEntry): void;
function getWeeklyReport(weekOf: string): WeeklyReport;
function getMonthlyTrend(month: string): MonthlyTrend;
```

### 7. Constraint Validator (`src/linkedin/constraints.ts`)

Validiert LinkedIn-spezifische Constraints.

**Interface**:
```typescript
interface ConstraintValidation {
  valid: boolean;
  errors: ConstraintError[];
  warnings: ConstraintWarning[];
}

interface ConstraintError {
  field: string;
  constraint: string;
  actual: string | number;
  limit: string | number;
}

function validateHeadline(text: string): ConstraintValidation;
function validateAbout(text: string): ConstraintValidation;
function validateExperience(text: string): ConstraintValidation;
```

## Data Models

### LinkedIn Tracking Entity (`kb/tracking/<date>.yaml`)

```yaml
id: linkedin-2026-w28
type: linkedin-tracking
created: 2026-07-13
modified: 2026-07-13

date: 2026-07-13
period: weekly

metrics:
  profile-views: 142
  search-appearances: 38
  connection-requests: 12
  post-impressions: 4500
  engagement-rate: 4.2
  comments: 23
  reposts: 8

posts:
  - title: "KI in der Bahn — was wirklich funktioniert"
    date: 2026-07-10
    format: text
    impressions: 2100
    engagement-rate: 5.1
    comments: 14
    reposts: 5
    is-best-practice: true
  - title: "Carousel: 5 Fehler bei der KI-Einführung"
    date: 2026-07-12
    format: carousel
    impressions: 2400
    engagement-rate: 3.8
    comments: 9
    reposts: 3
    is-best-practice: false
```

### LinkedIn Profile Output (`output/linkedin/profile-optimized.md`)

```markdown
# LinkedIn-Profil — Dr. Andre Knie
Generated: 2026-07-13

## Headline (Variante 1)
[Generated headline text]

## Headline (Variante 2)
[Generated headline text]

## About Section
[Generated about text]

## Experience: Experte für Digitalisierung — DB InfraGO
[Generated experience description]

## Experience: Gründer & Geschäftsführer — Data Hive Cassel
[Generated experience description]

...
```

### Content Strategy Output (`output/linkedin/content-strategy.md`)

```markdown
# Content-Strategie LinkedIn — Q3 2026
Generated: 2026-07-13

## Posting-Frequenz
2 Beiträge pro Woche (Di + Do)

## Themen-Cluster
1. Innovation & Technologie (40%)
2. Mensch & Kultur (35%)
3. Verantwortung (25%)

## Wochenplan
...

## Engagement-Routine
...

## Format-Mix
...
```

### Erweiterung Graph Index

```yaml
# Neue Entity-Typen in graph-index.yaml
entities:
  - id: linkedin-2026-w28
    type: linkedin-tracking
    name: LinkedIn Tracking KW28 2026
```

### Directory Structure (Erweiterungen)

```
project-root/
├── kb/
│   └── tracking/              # NEU: LinkedIn-Metriken
│       ├── linkedin-2026-w28.yaml
│       └── linkedin-2026-w29.yaml
├── src/
│   └── linkedin/              # NEU: LinkedIn-Module
│       ├── headline-generator.ts
│       ├── about-generator.ts
│       ├── experience-generator.ts
│       ├── content-strategy.ts
│       ├── tracking-manager.ts
│       ├── constraints.ts
│       └── linkedin.test.ts
├── output/
│   └── linkedin/              # NEU: LinkedIn-Outputs
│       ├── profile-optimized.md
│       ├── content-strategy.md
│       └── tracking-report.md
└── .kiro/
    └── skills/
        └── linkedin-profile/  # NEU: LinkedIn Skill
            └── SKILL.md
```