# Retrospektive — Epic 5: Tools & God Mode (Phase 4)

<!-- 🏃 Facilitiert von BMAD SM Skill — Agent: Bob (Scrum Master) -->
<!-- Skill Command: /bmad-agent-bmm-sm → [ER] Epic Retrospective -->
<!-- Workflow: _bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml -->

**Datum:** 2026-03-12
**Epic:** Epic 5 — Tools & God Mode (Phase 4)
**Status:** Abgeschlossen — 4/4 Stories erledigt
**Facilitiert von:** Bob (🏃 Scrum Master)

---

## 1. Epic-Zusammenfassung

**Ziel:** Tavily-Web-Suche, PDF-Reader mit ChromaDB, und Human-in-the-Loop via `interrupt_before`.

**Stories abgeschlossen:**
- ✅ 5.1: Tavily Web-Suche als Agent-Tool
- ✅ 5.2: PDF-Upload & ChromaDB-Ingestion
- ✅ 5.3: God Mode — Human-in-the-Loop
- ✅ 5.4: Run-Verlauf (History)

---

## 2. Was lief gut? (Keep)

**Technische Entscheidungen:**
- **LangChain `@tool`-Decorator** macht Tool-Implementierungen direkt LLM-kompatibel — kein Adapter-Boilerplate nötig
- **Lazy Imports** in `web_search.py` und `pdf_reader.py` verhindern `ImportError` wenn Pakete fehlen oder API-Keys nicht gesetzt sind
- **`create_web_search_tool()` / `create_pdf_search_tool()` Factory-Pattern** ermöglicht bedingtes Tool-Binding — Tools werden nur gebunden wenn die Voraussetzungen erfüllt sind
- **LangGraph `interrupt_before`** — God Mode funktioniert ohne eigenes Pause-Protokoll; der LangGraph-Mechanismus übernimmt das gesamte State-Handling
- **ChromaDB `_collection_cache`** verhindert mehrfache Client-Initialisierungen pro Request
- **`council_runs`-PostgreSQL-Tabelle** mit `status`, `final_draft`, `critic_score` ermöglicht vollständigen Run-Verlauf ohne In-Memory-Abhängigkeit

**Prozess:**
- Story 5.4 (History) konnte parallel zu 5.3 (God Mode) entwickelt werden — keine Abhängigkeit
- Alle Tool-Tests sind vollständig gemockt — kein Tavily-/ChromaDB-Aufruf in CI nötig
- God-Mode-Tests mit LangGraph-Checkpointer komplett gemockt — stabile Tests

---

## 3. Was lief nicht gut? (Drop / Improve)

**Technisch:**
- `_collection_cache` in `pdf_reader.py` ist ein Modul-Level-Dict — bei hoher Last und vielen Collections könnte Speicher wachsen; TTL fehlt
- `god_mode_states`-Dict in `dynamic_graph_builder.py` ist In-Memory — bei Server-Neustart gehen alle pausierten God-Mode-Runs verloren
- PDF-Chunks mit `words`-basiertem Split beachtet keine semantischen Grenzen (Sätze, Absätze) — könnte zu abgeschnittenen Kontexten führen
- `POST /api/councils/upload-pdf` speichert keine Referenz auf die Collection-Zuordnung zu einem Blueprint

**Prozess:**
- Story 5.3 (God Mode) war die komplexeste Story des gesamten Projekts — hätte in zwei Sub-Stories aufgeteilt werden können (Backend God Mode / Frontend Overlay)

---

## 4. Lernerkenntnisse

| Erkenntnis | Anwendung / Empfehlung |
|------------|----------------------|
| LangGraph's `interrupt_before` ist sehr einfach zu aktivieren — aber die State-Persistenz (Checkpointer) ist der eigentliche Komplexitätspunkt | Für Produktions-God-Mode: `PostgresSaver`-Checkpointer statt In-Memory verwenden |
| Tool-Factory-Pattern trennt Konfiguration (API-Key prüfen) von Ausführung (Tool aufrufen) | Für zukünftige Tools immer Factory-Funktion + @tool-Funktion getrennt implementieren |
| ChromaDB-Collections sollten an einen Blueprint-Run gebunden sein | `collection_name = f"run_{run_id}"` wäre eine sauberere Isolation |
| `UploadFile.content_type` ist browser-abhängig | Immer auch Dateiendung prüfen als Fallback (`filename.endswith(".pdf")`) |

---

## 5. Post-MVP Backlog

| Priorität | Verbesserung | Kategorie |
|-----------|-------------|-----------|
| Hoch | `PostgresSaver`-Checkpointer für God Mode (Persistenz über Neustarts) | Tech Debt |
| Hoch | PDF-Collection pro Blueprint-Run isolieren | Feature |
| Mittel | Sentence-basierter Text-Splitter statt Word-basiertem | Quality |
| Mittel | `god_mode_states`-Dict durch Redis oder DB ersetzen | Scalability |
| Niedrig | CORS `allow_origins` via `ALLOWED_ORIGINS`-Env konfigurierbar machen | Security |
| Niedrig | `_collection_cache` TTL / maximale Collection-Anzahl | Stability |

---

## 6. Projekt-Abschluss-Retrospektive

**Alle 5 Epics abgeschlossen. Das MVP von CouncilOS ist implementiert.**

### Was das Projekt gelehrt hat:

1. **LangGraph's Zyklus-Unterstützung** ist der Kern des Mehrwerts — kein anderes Framework ermöglicht so einfach echte Feedback-Schleifen
2. **BMAD-Method** hat die Planung strukturiert und sichergestellt, dass Backend-First-Reihenfolge eingehalten wurde
3. **TypedDict + `operator.add`-Reducer** ist ein elegantes Muster für akkumulativen State — keine Race Conditions möglich
4. **Factory-Pattern für Tools** und **`@tool`-Decorator** von LangChain ermöglichen saubere, testbare Tool-Integration
5. **WebSockets + `interrupt_before`** sind das Fundament für eine responsive, interaktive AI-Erfahrung

### Quantitative Zusammenfassung:
- **5 Epics, 18 Stories** — alle `done`
- **125 Backend-Tests** (pytest, alle grün, LLMs vollständig gemockt)
- **26 Frontend-Tests** (vitest, alle grün)
- **0 echte API-Calls in Tests**

---

*Bob (Scrum Master): "Epic 5 schließt das MVP ab. Besonders beeindruckend: God Mode mit LangGraph's `interrupt_before` war konzeptuell elegant und in der Praxis überraschend einfach zu implementieren. Das BMAD-Method-Vorgehen — Zyklen über Story→Dev→Review — hat die Codequalität nachhaltig verbessert. Herzlichen Glückwunsch zum CouncilOS-MVP!"*