Kairo-Jinkendo/docs/product/Kairo_Plan_Mode_Design_v0.1.md

Kairo — Plan-Modus Design v0.1

Status: PO-Arbeitsentwurf (Entscheidung ausstehend)
Stand: 2026-07-10
Bezug: Kairo_PM_Frontend_UI_Concept_v0.1.md §4.3, ADP_AP1_10_Initiative_Archetypes_and_Entity_Field_System_v0.1.md
Auslöser: Planen soll von Tab-Fragmenten zu durchgängiger Programmgestaltung werden — bis Struktur, Gates, Eingang, Arbeitspakete und Tasks

---

1. Leitfrage

Wie soll das Programm aufgebaut sein — von der Vorhabens-Identität bis zur ausführbaren Granularität?

Planen beantwortet Struktur- und Zielfragen. Es committet keine Tagesausführung (das ist Ausführen) und kein Lagebild (das ist Kontrolle).

---

2. Grundsatz: Vorhaben als Wurzel

/plan?initiative={id}&project={optional}

Initiative (Wurzel — immer im Scope)
├── Profil          — Archetyp, Standard- + dynamische Felder
├── Struktur        — Project-Baum (rekursiv)
├── Zielzustände    — Gates / RoadmapItems (Liste + Graph)
├── Eingang         — Backlog (triage → convert)
└── Arbeit          — Actions (+ Tasks ab AP1.5d) im Plan-Kontext

Flache Vorhaben: Actions ohne project_id erscheinen als direkte Kinder der Initiative im Plan-Baum.

Commit-Grenze Plan → Ist:

Objekt	In Plan	Commit-Aktion
BacklogItem	Ja	Convert → Action
Project / Gate	Ja	sofort „Struktur“ (kein separater Commit)
Action	Sichtbar	Anlage = committet
Task	Sichtbar (AP1.5d)	Anlage unter Action

---

3. IA: Von Tabs zur Plan-Outline

3.1 Heute (AP1.9a)

/plan/structure | /plan/gates | /plan/inbox   — drei lose Untertabs

3.2 Ziel (AP1.12)

Eine Planungsseite mit linker Outline (Baum) und rechtem Kontextbereich (Desktop) bzw. Drill-down (Mobile).

┌──────────────────────────────────────────────────────────────┐
│ Modus: Planen    Scope: Portfolio › Vorhaben X › [Projekt Y] │
├──────────────────┬───────────────────────────────────────────┤
│ OUTLINE          │ KONTEXT                                   │
│ ▼ Vorhaben X     │  [Profil-Karte / Mini-Snapshot]           │
│   ▼ Struktur     │  oder                                     │
│     Phase 1      │  [Liste der Kinder des gewählten Knotens] │
│     Phase 2      │  oder                                     │
│   Zielzustände   │  [Graph-Ansicht Gates]                    │
│   Eingang (3)    │                                           │
│   Arbeit (12)    │                                           │
└──────────────────┴───────────────────────────────────────────┘

Routen (evolutionär):

Route	Bedeutung
/plan	Portfolio: „Vorhaben ohne Struktur“, „Gates ohne Kriterien“ (Einstieg)
/plan?initiative=	Outline für ein Vorhaben
/plan?initiative=&node=structure|gates|inbox|work	Outline-Fokus (Query, kein Pflicht-Split)
/gates/:id, /projects/:id	Objekt-Modal / Deep Link (bestehend AP1.9)

Untertabs /plan/structure etc. bleiben als Deep-Link-Aliase mit Redirect auf /plan?initiative=&node=… bis Entfernung in AP1.12.

---

4. Interaktion

4.1 Bearbeiten — Modal (verbindlich)

Objekt	Trigger	Modal-Inhalt
Initiative	Outline „Profil“ / Stift-Icon	Standardfelder + EFS (AP1.10)
Project	Klick / Stift	Titel, Status, container_kind, Gate-Link, Parent
Gate	Klick / Stift	RoadmapItem + Kriterien (bestehend, polish)
Backlog	Klick	Triage-Felder, Gate-Link, Convert-Button
Action	Klick	ActionForm (bestehend) — oder Link zu /actions/:id
Task	Klick (AP1.5d)	TaskForm

Regel (UI Concept P4): Kein dauerhaftes Inline-Formular in der Outline.

4.2 Reihenfolge

Plattform	Mechanismus	Gilt für
Desktop (≥1024px)	Drag & Drop innerhalb gleicher Elternebene	Projects, Backlog (sort_order), Gates (optional Phase 2)
Mobile / Touch	↑ / ↓ Buttons pro Zeile	gleich

API: PATCH mit sort_order oder dediziertes POST …/reorder — idempotent, tenant-scoped.

4.3 Anlegen

„+“ am elterlichen Knoten in der Outline (nicht globaler FAB ohne Kontext).

---

5. Zielzustände — Graph (Plan-Modell, kein Workflow)

5.0 Abgrenzung (verbindlich)

Der Zielzustands-Graph modelliert Soll-Struktur — welche überprüfbaren Zielpunkte es gibt und wie sie logisch zusammenhängen (sequenziell, parallel, optional, blockierend).

Er ist kein Workflow:

Zielzustands-Graph (Kairo)	Workflow (Mitai Prompt Engine — nicht Kairo-Scope)
RoadmapItem = Quality Gate / Meilenstein / Reifegrad	Prompt-/Pipeline-Knoten
Kanten = Plan-Abhängigkeiten zwischen Gates	Ausführungs-/Verzweigungslogik
Verify = Kriterien + Evidence/Review	LLM-Aufruf, Aggregation, Join
Lesbar in Planen und Kontrolle (Plan vs. Ist)	Admin-Konfiguration für KI
Änderung am Plan = bewusste Planungsentscheidung (+ Audit)	Laufzeit-Orchestrierung

Mitai WorkflowEditorPage: nur UI-Pattern-Referenz (Canvas, Zoom, Pan, Snap) für ein künftiges Zielzustands-Modellierungswerkzeug — keine Übernahme von Workflow-Semantik, Prompt-Knoten oder Runtime.

Guardrail: In Docs, UI und Code nicht „Workflow-Graph“, „Gate-Workflow“ oder „Graph-Workflow“ sagen — korrekt: Zielzustands-Graph, Gate-Map, Plan-Graph.

5.1 Zwei Ansichten (Liste | Graph)

Ansicht	Wann	UI
Liste	Flache Vorhaben, wenige Gates	RoadmapPlanSection (evolviert)
Graph	Komplexe Abhängigkeiten, Parallel-Gates	GateMapView / später Zielzustands-Designer

Umschalter: „Liste | Graph“ im Knoten Zielzustände — Default Liste wenn ≤5 Gates, sonst letzter User-Choice (localStorage pro Initiative).

5.2 Graph-UI — Mitai-Pattern, Kairo-Semantik

Referenz (Pattern only): Mitai Workflow-Editor — Canvas, Zoom, Pan, Snap-to-grid.

Kairo-Scope (Zielzustands-Modell, kein Workflow):

Element	Semantik
Knoten	RoadmapItem (Gate, Meilenstein, Reifegrad)
Kanten	roadmap_item_dependencies → später edge_kind + parallel_group (AP1.4d)
Joint / Split (später)	Plan-Topologie — parallele Stränge, Join-Gates, optionale Äste — nicht Runtime-Verzweigung
Kein	Lifecycle-Workflow, Prompt-Knoten, Mitai-Domäne, Ausführungs-Engine

Heute (AP1.13a/b — MVP-Zwischenstand): read-only Auto-Layout + Kanten auf Gate-Detail; kein grafischer Designer, keine Joint-Knoten, kein Parallel-Join-Modell (→ AP1.4d + Modellierungswerkzeug).

Phase 2 — Zielzustands-Modellierungswerkzeug (PO):

• Drag-Drop-Designer für Gates, Kanten, Parallelgruppen, Joins
• Bearbeitung nur im Plan-Kontext (Modal/Designer — nicht Inline-CRUD-Wand in der Outline)
• Verify / Kriterien / Evidence weiterhin auf Gate-Detail — nicht im Graph als CRUD-Omnibus

5.3 Plan-Graph vs. Ist — parallel betrachten (Zielbild)

Problem (mehrfach in Kairo erlebt): Wenn Plan und Ist in demselben mutable Objekt verschmelzen (Status-Dropdown, Freitext-DoD, Graph = nur aktueller Stand), ist nicht nachvollziehbar, was geplant war, was tatsächlich passiert ist und wann der Plan angepasst wurde.

Regel:

Schicht	Inhalt	Änderbarkeit
Plan-Graph (Soll)	Knoten, Kanten, Kriterien-Definition, Parallel-/Join-Topologie	Planung; Revision mit Audit/Decision
Ist-Overlay	Gate-Status (reached/moved/…), Kriterien-Status, Evidence, Journey-Events	Ausführung, Review, Verify, Reopen
Historie	Plan-Revisionen, Ist-Ereignisse, Abweichungen Plan↔Ist	append-only / audit

Review-Ablauf (Kontrolle / Journey — Ziel):

1. Plan-Graph und Ist-Overlay **parallel** anzeigen (nicht eins collapsed)
2. Abweichungen sichtbar: Gate erreicht aber Kriterium waived; optionaler Ast nicht genommen; Plan-Kante obsolet
3. Entscheidung: Plan anpassen (Zielzustand revidieren) — mit Begründung — ODER Ist dokumentieren (Decision/moved/discarded)
4. Plan-Graph **ordentlich** nachziehen — nicht stillschweigend den Ist-Stand als neuen Plan überschreiben

Technische Folge (spätere Pakete):

• AP1.4d: Graph Engine Read Models (blocked, ready, fulfillment_ratio) aus Plan-Kanten + Ist-Status
• AP1.4e+: Methodenprofile (Erfüllungsgrad vs. hartes reached)
• AP1.14 (vorgeschlagen): Plan-Snapshot / Plan-Revision + Ist-Overlay in UI (Kontrolle: „Plan | Ist | Diff“); Graph-Designer Phase 2

Heute: Ein Graph, Status am selben Knoten — Ist vermischt mit Plan. Truth Table: ◐. Das ist bewusster MVP-Zwischenstand, kein Zielbild.

5.4 Backend

Baut auf AP1.4d (Graph Engine read models) auf — UI AP1.13 nach 4d oder parallel wenn read APIs vorhanden.

---

6. Ebenen bis Workpackage & Task

Ebene	Typ	Plan-Outline-Knoten	Tiefe
0	Initiative	Wurzel	1
1	Project	rekursiv	max. 5 (bestehend)
2	RoadmapItem	Zielzustände (Graph/Liste)	parallel zur Struktur
3	BacklogItem	Eingang	flach unter Initiative
4	Action	Arbeit	unter Project oder Initiative
5	Task	(AP1.5d)	unter Action, UI max. ~3

Plan-Baum „Arbeit“: Zeigt committete Actions + Tasks (read-heavy); Anlage öffnet Modal. Filter: optional nur „ohne Project“ / „unter gewähltem Project“ (Scope ?project=).

---

7. Scope-Breadcrumb (AP1.9b — Zuverlässigkeit)

Problem: Klick auf Vorhaben im Breadcrumb führt immer nach /control/status — in Planen falsch.

Regel: Mittlerer Breadcrumb-Klick ist modus-sensitiv:

Aktiver Modus	Klick „Vorhaben X“
/plan/*	/plan?initiative=X
/control/*	/control/status?initiative=X
/work/*	/work/today?initiative=X
Objekt-Route	passender Modus aus Objekttyp (/projects/ → Plan, /actions/ → Work)

Portfolio-Klick: Scope leeren, Modus beibehalten.

Technik: ProgramScopeBar liest useLocation + Modus-Registry; kein hardcoded /control/status.

---

8. Implementierungspakete

AP1.9b   Scope-Breadcrumb modus-sensitiv; Scope-Sync bei Deep Links härten
AP1.12a  Plan-Outline Shell (Desktop Split / Mobile Drill-down)
AP1.12b  Modal-Edit für Project, Backlog, Initiative-Profil (Standardfelder)
AP1.12c  Reorder: sort_order API + DnD (Desktop) + ↑↓ (Mobile)
AP1.12d  Outline-Knoten „Arbeit“ (Actions listen, Link zu Detail)
AP1.13a  GateMapView read-only (Layout aus Dependencies)
AP1.13b  Kanten-CRUD auf Gate-Detail (kein Designer)
AP1.4d    Graph Engine: parallel_group, edge_kind, blocked/ready
AP1.14    Plan-Snapshot / Ist-Overlay / Plan-Revision (vorgeschlagen)
AP1.15    Zielzustands-Modellierungswerkzeug (Designer, Mitai-Pattern)
AP1.15a   Designer MVP (Pan/Zoom, Kanten, Layout)
AP1.15b   Designer UX (Drag-Kanten, Gate anlegen, Klick-Panel)
AP1.15c   Join/Branch-Topologie (parallel_group, optional_branch, Engine) — deferred, vorbereitet
AP1.5d   Tasks in Outline-Knoten „Arbeit“
AP1.10   Archetyp + EFS für Initiative-Profil-Modal (parallel ab 10a)

Empfohlene Reihenfolge:

9b → 12a → 12b → 10a/10c (Profil) → 12c → 12d → 5d → 13a → 13b

---

9. Nicht-Ziele (Scope Lock)

• Kein Sprint-/Capacity-Planning in Planen (später Team-Modus-Erweiterung)
• Kein Inline-CRUD aller Gates in der Outline-Liste
• Kein Mitai-Workflow-Clone (auch kein „Workflow-Graph“ — nur Zielzustands-Graph)
• Kein Plan=Ist-Collapse (Status/Freitext ersetzt nicht Plan-Revision + Ist-Historie)
• Kein Steering pro Project-Ebene (ADP Recursive Containers)

---

10. Erfolgskriterien (PO)

1. PO kann ein Vorhaben wählen und in einer Ansicht Struktur, Gates, Eingang und Arbeit sehen.
2. Bearbeitung läuft nur im Modal — Outline bleibt übersichtlich.
3. Project-Reihenfolge per DnD (Desktop) änderbar.
4. Gates mit Abhängigkeiten im Zielzustands-Graph darstellbar (AP1.13); Designer + Plan/Ist-Parallelität folgen (AP1.4d, AP1.14+).
5. Breadcrumb-Klick auf Vorhaben bleibt im Modus Planen.

---

11. PO-Freigabe

• Outline statt drei Tabs (AP1.12) angenommen
• Modal-Edit + DnD/↑↓ OK
• GateMap / Zielzustands-Designer (Mitai-Pattern only) Scope OK
• Plan-Graph vs. Ist-Overlay parallel (AP1.14) OK
• AP1.9b Breadcrumb-Regel OK

---

Referenzen

• docs/architecture/ADP_AP1_10_Initiative_Archetypes_and_Entity_Field_System_v0.1.md
• docs/architecture/ADP_AP1_9_PM_Work_Modes_Frontend_IA_v0.1.md
• docs/reference/design-principles/mitai/PROMPT_ENGINE_DESIGN_PRINCIPLES.md (WorkflowEditor-Referenz)