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

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

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

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

Welle 2 — Zielbild präzisieren

• Kairo_System_Target_State_v0.2.md — pro Kapitel: Status target | partial | not_started
• Kairo_Corrected_MVP_Roadmap_v0.2.md
• Kairo_MVP_Usability_Recovery_Plan_v0.2.md
• ADP: RoadmapItem_and_Quality_Gate_Model_v0.1.md (neu)
• ADP: Operational_Actor_Interface_Vibe_Coder_v0.1.md (neu — API-Spec)
• Sprint0_Vibe_Coder_Handover_v0.2.md — IA + Operational Interface

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

• Sprint0_Vibe_Coder_Handover_v0.2.md
• Completion Reports: archiv-Banner
• README.md — ehrlicher Produktstand

---

6. Standard-Banner für superseded Dokumente

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

> **⚠ 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