Kairo-Jinkendo/docs/product/DOCUMENTATION_REVISION_PROGRAM_v0.2.md

# Kairo — Documentation Revision Program v0.2

**Status:** aktives Überarbeitungsprogramm  
**Stand:** 2026-07-05  
**Auslöser:** Product Owner: Zielbild-Dokumente unzureichend, falsch oder irreführend; große Distanz zur Vision nach AP1.1b

---

## 1. Ziel des Programms

Alle Produkt- und Architektur-Dokumente so überarbeiten, dass:

1. **Vision, Zielbild und Ist-Stand** klar getrennt sind
2. Kein Dokument so tut, als wäre **RoadmapItem / Gates / Plan-Ist** schon produktiv
3. Implementierungs-Agenten **nicht** wieder flache CRUD-UI als MVP verkaufen
4. Die **Product Owner Vision** (IA, Gates, Hierarchie, Journey) führend ist
5. Historische Sprint-Docs **archiviert** bleiben, aber nicht mehr irreführen

---

## 2. Diagnose — warum die Distanz zur Vision so groß wirkt

### 2.1 Dokumenten-Drift

| Problem | Beispiel |
|---------|----------|
| **Zielbild ohne Ist-Kennzeichnung** | Target State beschreibt RoadmapItem; UI zeigt `milestones`-CRUD |
| **MVP-Roadmap suggeriert Nähe zum Ziel** | AP0.8 „Milestone minimal“ las sich wie „Meilenstein fertig“ |
| **Usability Recovery optimierte falsche Fläche** | AP1.1b verbesserte InitiativeDetail statt IA zu spalten |
| **Mehrere konkurrierende „führende“ Docs** | Product Reset, Spec, Canonical OM, Target State, Recovery Plan |
| **Completion Reports = Erfolg** | Technisch grün, produktlich nicht visionstauglich |
| **Begriffe inkonsistent** | Maßnahme = Action = Projekt? Unklar |

### 2.2 Implementierungs-Drift

```text
Dokumentiert:  Initiative → Project → Roadmap → Backlog → Action → Task
Implementiert: Initiative → [parallel CRUD-Sektionen] → Action
```

### 2.3 Irreführende Erfolgssignale

- Steering Snapshot v2 wirkt wie „Steuerung fertig“
- Meilenstein-Formular mit `goal_description` wirkt wie „Gate-Modell“
- Canonical OM listet Objekte, die **existieren**, aber **nicht ihre Rolle im Plan/Ist** erfüllen

---

## 3. Neue Dokumenten-Schichten

```text
Schicht A — Vision & Product Direction     ← Product Owner Wahrheit
Schicht B — Canonical Operating Model      ← Fachliches Regelwerk
Schicht C — Target State / Architecture    ← Technisches Nordstern-Zielbild
Schicht D — Implementation Truth Table     ← Was existiert wirklich (living doc)
Schicht E — Roadmap & Assignments          ← Nächste Pakete, ehrlich priorisiert
Schicht F — Sprint History                 ← Completion Reports (historisch, banner)
Schicht G — Reference / Design Principles  ← Nicht automatisch Scope
```

**Regel:** Schicht A–D vor jeder größeren Implementierung lesen. Schicht F nie als Zielbild missverstehen.

---

## 4. Dokumenten-Inventar & Revisionsstatus

### 4.1 Schicht A — Vision (neu / überarbeitet)

| Dokument | Status | Aktion |
|----------|--------|--------|
| `Kairo_Vision_and_Product_Direction_v0.2.md` | ✓ **neu, führend** | Pflege bei PO-Feedback |
| `Kairo_Product_Definition_and_MVP_Reset_v0.1.md` | ⚠ veraltet | → v0.2 oder Superseded-Banner; Inhalte in Vision v0.2 |
| `Jinkendo_Kairo_Product_Spec_v0.2.md` | ⚠ Referenz | Banner: Spec ≠ Ist; Konflikt → Vision v0.2 |
| `Kairo_MVP_Usability_Recovery_Plan_v0.1.md` | ⚠ teilweise falsch | → v0.2: IA-first, kein InitiativeDetail-Patching |

### 4.2 Schicht B — Operating Model

| Dokument | Status | Aktion |
|----------|--------|--------|
| `Kairo_Canonical_Operating_Model_v0.1.md` | ⚠ unvollständig | → **v0.2**: Plan/Ist, Gates, IA, Hierarchie |
| `Kairo_Canonical_Operating_Model_v0.2.md` | ✓ neu | Pflege synchron zu Vision |

### 4.3 Schicht C — Architecture / Target State

| Dokument | Status | Aktion |
|----------|--------|--------|
| `Kairo_System_Target_State_v0.1.md` | ✓ inhaltlich gut | → v0.2: explizite „Not implemented“-Markers pro § |
| `Kairo_Universal_Steering_Engine_Decision_v0.1.md` | ✓ Referenz | Cross-Ref zu Vision; kein MVP-Scope |
| `Kairo_Target_Architecture_Method_Driven_..._v0.1.md` | ✓ Referenz | Phase C klar markieren |
| `Kairo_Method_Design_Principles_v0.1.md` | ✓ Referenz | — |
| `Kairo_Core_Model_Decision_v0.2.md` | ✓ Referenz | — |
| `ADP_AP1_0_Steering_Foundation_Scope_Lock_v0.1.md` | ✓ gültig | Ergänzen: IA-Scope-Lock bis RoadmapItem-ADP |
| `Kairo_Operating_Model_Steering_Bridge_v0.1.md` | prüfen | Mit v0.2 OM abgleichen |
| `Kairo_Current_State_Gap_Analysis_AP0.1_AP0.6b_v0.1.md` | ⚠ veraltet | → **v0.2** bis AP1.1b |

### 4.4 Schicht D — Truth Table

| Dokument | Status | Aktion |
|----------|--------|--------|
| `Kairo_Implementation_Truth_Table_v0.1.md` | ✓ **neu** | Bei jedem AP aktualisieren |

### 4.5 Schicht E — Roadmap

| Dokument | Status | Aktion |
|----------|--------|--------|
| `Kairo_Corrected_MVP_Roadmap_v0.1.md` | ⚠ irreführend | → **v0.2**: ehrliche Phasen DOC/IA/Gates/Hierarchie |
| Sprint Assignments AP1.x | historisch + aktiv | Neue Assignments referenzieren Vision v0.2 |

### 4.6 Schicht F — Sprint History

| Dokument | Status | Aktion |
|----------|--------|--------|
| `Sprint0_AP0_*_Completion_Report_*.md` | historisch | Standard-Banner oben |
| `Sprint1_AP1_*_Assignment_*.md` | teils aktiv | AP1.1b als „UX patch, not vision“ einordnen |

### 4.7 Agenten-Konfiguration

| Dokument | Status | Aktion |
|----------|--------|--------|
| `CLAUDE.md` | ⚠ veraltet | Lesereihenfolge → Vision v0.2 |
| `.cursor/rules/kairo-architecture.mdc` | ⚠ veraltet | Doc-Priorität + Stop CRUD-Wand |
| `Kairo_Architecture_References_v0.1.md` | ⚠ veraltet | → v0.2 |

---

## 5. Revisions-Wellen

### Welle 1 — Anker (2026-07-05) ✓ gestartet

- [x] `Kairo_Vision_and_Product_Direction_v0.2.md`
- [x] `DOCUMENTATION_REVISION_PROGRAM_v0.2.md` (dieses Dokument)
- [x] `Kairo_Canonical_Operating_Model_v0.2.md`
- [x] `Kairo_Implementation_Truth_Table_v0.1.md`
- [x] Superseded-Banner auf v0.1-Kern docs
- [x] `CLAUDE.md` + `.cursor/rules` aktualisieren

### Welle 2 — Zielbild präzisieren

- [x] `Kairo_System_Target_State_Implementation_Map_v0.2.md` — pro Kapitel: Status target | partial | done
- [x] `Kairo_Corrected_MVP_Roadmap_v0.2.md`
- [x] `Kairo_MVP_Usability_Recovery_Plan_v0.2.md`
- [x] `Kairo_Current_State_Gap_Analysis_v0.2.md`
- [x] ADP: `ADP_RoadmapItem_and_Quality_Gate_Model_v0.1.md`
- [x] ADP: `ADP_Operational_Actor_Interface_Vibe_Coder_v0.1.md`
- [x] `Sprint0_Vibe_Coder_Handover_v0.2.md`
- [x] `Sprint1_AP1_2c_IA_Skeleton_Assignment_v0.1.md`

### Welle 3 — Architektur-Konsolidierung

- [ ] Target Architecture / Universal Steering Engine — Duplikate reduzieren, ein Master-Index
- [ ] `Kairo_Operating_Model_Steering_Bridge_v0.2.md`
- [ ] Method Design Principles — explizite MVP-Abgrenzung

### Welle 4 — Sprint & Handover

- [x] `Sprint0_Vibe_Coder_Handover_v0.2.md` (→ Welle 2)
- [ ] Completion Reports: archiv-Banner
- [ ] README.md — ehrlicher Produktstand

---

## 6. Standard-Banner für superseded Dokumente

Am Anfang superseded v0.1-Dateien einfügen:

```markdown
> **⚠ Superseded (2026-07-05):** Dieses Dokument ist nicht mehr führend.
> Verwende stattdessen `[Neues Dokument](pfad)`.
> Inhalt bleibt als historische Referenz erhalten.
```

---

## 7. Qualitätskriterien für überarbeitete Docs

Jedes Kern-Dokument muss enthalten:

1. **Status** (führend | Referenz | historisch | superseded)
2. **Stand** und **Ersetzt**-Hinweis
3. Explizite **Nicht-Scope**-Abschnitte
4. Wo relevant: **Ist vs. Ziel**-Tabelle
5. Verweis auf **Truth Table** für Implementierungsstand
6. Keine Formulierung, die CRUD-Listen als Steuerung verkauft

---

## 8. Product Owner Review-Gates

Vor Abschluss Welle 2:

- [ ] PO bestätigt: Begrifflichkeit (Arbeitspaket, Gate, Plan/Ist) stimmt
- [ ] PO bestätigt: IA-Zielbild (§7 Vision) stimmt
- [ ] PO bestätigt: Roadmap-Reihenfolge (IA vor Gate-Schema) stimmt

Erst danach: **AP1.2c** (IA-Skeleton) implementieren.

---

*Führendes Vision-Dokument: `Kairo_Vision_and_Product_Direction_v0.2.md`*