ki-grok/04-plan-mode-review-approve.md

Kapitel 4

Plan Mode – Review und Freigabe

Kern in einem Satz: Plan Mode trennt Ansatz und Code: Der Agent erforscht read-only (außer der Plan-Datei), du kommentierst und freigibst – erst danach darf Implementierung den Diff-Strom füllen.

---

4.1 Warum Plan Mode existiert

Alltagsschmerz: Du sagst „Bau Auth ein“. Der Agent wählt JWT, legt Middleware an, rührt die Session-DB an – und erst im Review merkst du: Das Team nutzt Cookie-Sessions und einen bestehenden Guard. Drei Stunden Rework, obwohl die Anforderung „Auth“ hieß.

Plan Mode erzwingt die Gegenbewegung: Zuerst Ansatz auf eine Seite bringen, dann bauen. Das spart nicht „Token“, sondern falsche Architektur.

Wann es sich lohnt: echte Ambiguität (mehrere vernünftige Wege), unklare Requirements, hoher Blast Radius. Wann nicht: offensichtlicher Bugfix, Rename, Feature das 1:1 bestehende Patterns kopiert, reines Explore (dafür explore-Subagent, Kapitel 5).

{width=90%}

---

4.2 Was Plan Mode technisch tut

Wenn Plan Mode aktiv ist:

1. Der Agent liest und sucht im Code (Patterns, bestehende Utils).
2. Er schreibt den Ansatz in die Plan-Datei.
3. Optional stellt er Klärungsfragen (ask_user_question).
4. Er beendet die Planungsphase mit exit_plan_mode und präsentiert den Plan zur Freigabe.

Die harte Regel: Read-only für fast alles. Edits an der Plan-Datei (plan.md im Session-Verzeichnis) sind auto-approved. Edits an jeder anderen Datei werden abgelehnt – der Tool-Call scheitert mit dem Hinweis, dass nur die Plan-Datei editierbar ist. Das gilt in jedem Permission-Mode, inklusive Always-approve.

Erlaubt in Plan Mode	Blockiert (Edit-Tools)
Lesen, Suchen, Listen	search_replace / Write auf Repo-Dateien
Plan-Datei schreiben	Implementierungs-Diffs im Working Tree
Shell lesen/erkunden (siehe Fallstrick unten)	–

Achtung — zwei getrennte Risiken:

1. Edit-Tools ≠ Shell. Plan Mode blockiert Repo-Edits über Edit-Tools, nicht magisch jede Shell-Redirection. Bash wird nicht als Dateischreiber inspiziert.
2. Parent-Plan ≠ Kind-Gate. Subagents erben die Plan-Mode-Edit-Sperre des Parents nicht. Ein general-purpose-Kind kann schreiben, während der Parent noch plant – und erbt oft den Permission-Mode (inkl. Always-approve). Für reine Recherche: explore / plan / capability_mode: read-only (Kapitel 5–6).

Plan-Datei-Pfad (typisch):

~/.grok/sessions/<encoded-cwd>/<session-id>/plan.md

<encoded-cwd> ist ein kodierter Verzeichnisname, nicht der Literalpfad deines Repos.

Session-plan.md vs. Team-Plan-Doku: Die Datei oben ist session-lokal (Harness-Artefakt). Team-Vorlagen wie vorlagen/PLAN.md.skeleton.md oder beispiele/todo-cli/PLAN.md.example sind Repo-Doku – nicht dieselbe Datei und kein Ersatz für den Plan-Mode-Lifecycle.

Inhalt der Plan-Datei (erwartbar):

• Context – warum die Änderung
• Empfohlener Ansatz (nicht jede Alternative)
• Kritische Dateipfade
• Bestehende Funktionen/Utils zum Wiederverwenden (mit Pfaden)
• Verification – wie du end-to-end testest

---

4.3 Plan Mode betreten

Du willst den Mode setzen, bevor der nächste Prompt fliegt – sonst startet der Agent schon im falschen Gate.

Du startest (user-initiated)

Weg	Wirkung
/plan	Plan Mode Pending – aktiv mit dem nächsten Prompt
/plan <Beschreibung>	Plan Mode + sofortiger Turn mit dieser Beschreibung
Shift+Tab	Mode cyclen: Normal → Plan → Always-approve → Normal (Auto separat: /auto)

Lifecycle (vereinfacht):

Inactive  --(/plan oder Shift+Tab)-->  Pending
Pending   --(erster Prompt)--------->  Active
Active    --(Approve exit_plan_mode)--> Inactive (+ Implementierung)
Active    --(Mode aus, idle)--------->  Inactive
Active    --(Mode aus, Turn läuft)-->  ExitPending → dann Inactive

Agent-initiiert: Der Agent ruft enter_plan_mode auf – du musst zustimmen. Ablehnen = bleibt Normal. Bei Zustimmung springt der Flow oft Inactive → Active (ohne Pending).

Gute Trigger (für dich und den Agenten):

• „User-Auth einbauen“ / „Add user authentication“ (Session vs. JWT vs. Middleware)
• „Datenpipeline neu schneiden“ / „Redesign the data pipeline“
• „Caching ergänzen“ (Redis vs. in-memory vs. file)
• „Echtzeit-Updates“ (WebSocket vs. SSE vs. Polling)

Schlechte Trigger:

• „Delete-Button am Profil“
• Tippfehler in der README
• Error-Handling an einer bekannten Stelle nachziehen
• „Können wir an Search arbeiten?“ (Startimpuls, kein Plan-Auftrag)

---

4.4 Der Approval-Flow: Preview, Kommentar, Freigabe

Wenn der Agent exit_plan_mode aufruft, liest das Tool plan.md und die TUI öffnet eine scrollbare Preview mit Action-Bar.

Shortcut	Aktion
a	Approve – Plan freigeben und bauen. Mit offenen Kommentaren: approve w/ comments
s	Request changes – Fokus auf Prompt, Revisionsnotizen tippen, Enter senden
c	Comment auf die selektierte Zeile/Range
y	Copy – gesamten Plan in die Zwischenablage
q	Quit plan – Plan verwerfen, Plan Mode aus
Tab	Fokus Preview ↔ Prompt
Esc	Vom Prompt zurück zur Preview (nicht automatisch quit)

Drei Fokus-Zustände:

1. Preview – scrollen, Zeilen für Kommentare wählen
2. Commenting – Inline-Kommentar zur Range (c oder Enter auf Zeile)
3. Prompt – freie Revisionsnotizen

Feedback (Inline, Freeform oder beides) hält Plan Mode aktiv: Der Agent überarbeitet den Plan, du iterierst, bis der Ansatz stimmt.

Leerer Plan: Fehlt plan.md oder ist sie leer, öffnet sich trotzdem die Approval-UI (Empty-State). Du kannst freigeben und bauen, Änderungen fordern oder quitten – in Minimal Mode landet der Empty-Hinweis im Scrollback.

Plan später wieder öffnen: /view-plan (Aliases /show-plan, /plan-view).

---

4.5 Always-approve und Compact unter Plan Mode

• Always-approve bleibt „darunter“ scharf: Nicht-Edit-Tools (Bash, Reads, MCP) können weiter auto-laufen. Datei-Edits am Repo bleiben gesperrt, bis du den Exit freigibst. Nach Approve gilt Always-approve wieder für die Implementierung.
• Status-Flag: während aktiv plan; Always-approve-Flag kommt nach Exit zurück, falls es an war.
• /compact: Plan-Mode-State bleibt erhalten; im kompaktierten Kontext steckt ein Reminder, dass Plan Mode aktiv ist.

Praxisregel: Plan Mode ist kein Ersatz für enge Shell-Deny-Regeln. Unter Always-approve in Plan Mode können riskante Commands weiterlaufen – nur Repo-Edit-Tools bleiben gesperrt.

---

4.6 Der Review-Vertrag (was du im Plan prüfen musst)

Bevor du a drückst, scanne bewusst:

Check	Frage
Scope	Welche Dateien – und was ist explizit out of scope?
Ansatz	Ein empfohlener Weg, nicht fünf unverbindliche Optionen?
Reuse	Nutzt er bestehende Utils/Patterns (mit Pfaden)?
Risiken	Migrationen, Breaking Changes, Feature-Flags?
Verify	Steht ein konkreter Test-/Manual-Check drin?
Größe	Passt das in einen PR – oder muss geschnitten werden?

Gute Kommentar-Beispiele (Inline oder Prompt):

Keine neue Redis-Abhängigkeit – nutze den bestehenden Cache-Client in pkg/cache.
Endpoint unter /v2/… wie die anderen Payments-Routen.
Verification: pytest tests/payments -q und ein manueller 401-Fall.

Schlechtes Approve: „Sieht smart aus“ ohne Dateiliste und Verify – das ist dasselbe wie blindes Diff-Accept in Normal Mode.

---

4.7 Praxis-Sessions

Session A – Feature mit Ambiguität (durchgängig)

cd ~/projects/your-app
grok

/plan

Nächster Prompt (oder direkt /plan …):

Wir brauchen rate limiting für die public API.
Constraints: kein neues Infra-Produkt, bestehende Middleware-Pipeline nutzen,
Konfiguration über Env, Tests grün.
Schreibe einen Implementierungsplan. Noch kein Code im Repo.

Ablauf erwarten: Explore → plan.md → Preview.

Deine Review-Aktion:

1. Scrollen, Dateipfade prüfen.
2. c auf eine Zeile: „In-memory reicht für single-instance; multi-instance später.“
3. Optional Freeform mit s / Prompt.
4. Wenn der revidierte Plan passt: a.
5. Implementierung beobachten; Diffs lesen; Verify-Abschnitt abarbeiten.

Session B – Plan ablehnen und neu schneiden

/plan Baue eine Event-Sourcing-Schicht für alle Domain-Events.

Im Preview merkst du: zu groß.

# s → Request changes, sinngemäß:
Zu groß für einen PR. Plane nur den Outbox-Pattern-Schritt
für den Order-Service. Kein Rewrite der History.

Oder q und neuer, engerer /plan-Prompt. Trainingsziel: Quit/Revise ist Erfolg, nicht Scheitern.

Session C – Wann du Plan Mode nicht brauchst

# Normal Mode, kein /plan
Im File src/utils/formatDate.ts: Timezone-Bug bei UTC+0.
Repro im Test ergänzen, minimal fixen, tests für formatDate grün.

Trainingsziel: Plan Mode ist ein Skalpell, kein Default für jeden Turn.

Session D – Agent will Plan Mode, du entscheidest

Manchmal schlägt der Agent enter_plan_mode vor.
Approve, wenn die Aufgabe architektonisch ambig ist.
Decline, wenn du schon weißt: „Nur den einen Guard anpassen“ – und den Scope im Prompt festnageln.

---

4.8 So baust du den Workflow im Team nach

1. Definition of Ready: Tickets mit Ambiguität markieren („Plan first“).
2. Session-Start: /plan + Constraints (Stack, Out-of-scope, Verify-Command).
3. Review-SLA: Tech-Lead oder Autor kommentiert Dateiliste und Verify, nicht Stil-Nitpicks.
4. Approve nur mit Verify: ohne Testplan kein a.
5. Implementierung: gleicher Session-Kontext oder frische Session mit „Implementiere den freigegebenen Plan: …“ + Link/Paste der Kernpunkte.
6. PR-Beschreibung: Plan-Ansatz in 5 Zeilen – Reviewer sieht die Entscheidung, nicht nur den Diff.

Optional: Plan-Inhalte, die das Team immer braucht, später in AGENTS.md oder Skills heben (Kapitel 7–8) – nicht den gesamten Plan committen, wenn er session-lokal bleiben soll.

---

4.9 Jetzt selbst machen: Plan-Parcours (25 Minuten)

Jetzt selbst machen

Standard: beispiele/todo-cli (Setup wie Kapitel 2). Eigenes ambiges Feature geht auch.

1. In todo-cli (oder bekanntem Repo) grok starten.
2. /plan und einen ambigen Auftrag mit 3 Constraints – todo-cli-Vorschlag:

/plan Atomare Writes in store.save: zuerst temp-Datei, dann replace.
Constraints: bestehende JSON-Form behalten; Tests grün (pytest -q);
kein neues Framework. Noch kein Repo-Code außer dem Plan.

3. Preview öffnen lassen; mindestens einen Inline-Kommentar (c) setzen.
4. Mit s eine Freeform-Revision schicken; warten auf Plan v2.
5. Plan mit a freigeben oder bewusst mit q verwerfen und enger neu starten.
6. Nach Approve: ersten Implementierungs-Diff lesen, bevor du weitermachst.
7. /view-plan einmal testen.
8. Zweite Mini-Session: klarer Bugfix ohne Plan Mode (z. B. Tippfehler in der README oder ein fehlender Test-Name).

---

4.10 Häufige Fehler

Symptom	Ursache	Fix
Agent „plant“ und editiert trotzdem Dateien	Subagent mit Write-Rechten / Shell-Write	Nur explore/plan; Parent-Plan ≠ Kind-Gate
Plan zu vage	Prompt ohne Constraints	Scope, Stack, Out-of-scope, Verify fordern
Endlos-Iteration	Kommentare ohne Priorität	Max. 3 Änderungswünsche pro Runde
Approve aus Höflichkeit	Review-Vertrag fehlt	Checkliste 4.6
Plan Mode für Tippfehler	Falsches Werkzeug	Normal Mode
Nach Compact „vergisst“ er den Mode	selten; State sollte bleiben	/session-info, Mode-Flag prüfen; ggf. /plan erneut

---

4.11 Checkliste Plan Mode

• Aufgabe hat echte Ambiguität oder hohen Blast Radius
• Constraints und Verify stehen im Prompt
• Preview gelesen (Dateien, Reuse, Risiken)
• Mindestens eine gezielte Korrektur, wenn etwas hakt
• Approve erst nach nachvollziehbarem Verify-Plan
• Subagents während Plan Mode nicht unkontrolliert schreiben lassen
• Always-approve-Risiken (Shell) bewusst

---

Was du jetzt kannst

• Plan Mode betreten, den Lifecycle skizzieren und die Edit-Sperre erklären
• Einen Plan in der Preview kommentieren, revidieren, freigeben oder verwerfen
• Entscheidungskriterien anwenden, wann Plan Mode hilft und wann er stört
• Einen durchgängigen Feature-Flow Plan → Approve → Implementierung fahren

Nächste Schritte

→ Kapitel 05 – Subagents und Parallelität: Kontext-Ventil, Agent-Typen, Personas und parallele Arbeit ohne den Parent zu überfüllen.