its-consulting/KI-Konzil
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
KI-Konzil/_bmad-output/implementation-artifacts/epic-5-retro-2026-03-12.md
copilot-swe-agent[bot] 57e2acadaf feat: add epic retrospectives (3, 4, 5), update sprint status and project context 
Co-authored-by: Kenearos <86194771+Kenearos@users.noreply.github.com>
2026-03-12 22:31:01 +00:00

5.4 KiB
Raw Blame History

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

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!"