Add missing Epic 1 and Epic 2 retrospective files
Co-authored-by: Kenearos <86194771+Kenearos@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
parent
7fb96fc7dc
commit
0237b16023
2 changed files with 184 additions and 0 deletions
|
|
@ -0,0 +1,89 @@
|
||||||
|
# Retrospektive — Epic 1: Projekt-Setup & Infrastruktur
|
||||||
|
|
||||||
|
<!-- 🏃 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 1 — Projekt-Setup & Infrastruktur
|
||||||
|
**Status:** Abgeschlossen — 3/3 Stories erledigt
|
||||||
|
**Facilitiert von:** Bob (🏃 Scrum Master)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Epic-Zusammenfassung
|
||||||
|
|
||||||
|
**Ziel:** Vollständig konfiguriertes, lauffähiges Entwicklungsumfeld mit Docker Compose, PostgreSQL, FastAPI-Skeleton und Next.js-Skeleton.
|
||||||
|
|
||||||
|
**Stories abgeschlossen:**
|
||||||
|
- ✅ 1.1: Docker-Compose-Umgebung aufsetzen
|
||||||
|
- ✅ 1.2: Backend-Python-Umgebung & Requirements
|
||||||
|
- ✅ 1.3: Datenbank-Migrationen mit Alembic
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Was lief gut? (Keep)
|
||||||
|
|
||||||
|
**Technische Entscheidungen:**
|
||||||
|
- **Docker Compose** mit drei Services (db, api, frontend) und Health-Checks gewährleistet fehlerfreies Hochfahren — kein Race-Condition zwischen PostgreSQL und FastAPI
|
||||||
|
- **Async-First-Design** durchgehend: `asyncpg` als DB-Treiber, `aiosqlite` für Tests, `pytest-asyncio` mit `asyncio_mode = auto` — das zahlt sich in allen folgenden Epics aus
|
||||||
|
- **Dual-Database-Support**: SQLite für lokale Entwicklung, PostgreSQL für Docker/Produktion — senkt die Einstiegshürde für Entwickler
|
||||||
|
- **Alembic-Migrationen** von Anfang an konfiguriert — Schema-Evolution ist nie ein Nachgedanke
|
||||||
|
- **Named Volumes** (`postgres_data`, `chroma_data`) verhindern Datenverlust bei Container-Neustarts
|
||||||
|
|
||||||
|
**Prozess:**
|
||||||
|
- Story-Reihenfolge war optimal: Docker → Requirements → Migrationen (jede Story baut auf der vorherigen auf)
|
||||||
|
- `.env.example` und `.gitignore` von Anfang an korrekt — keine versehentlichen Secret-Commits
|
||||||
|
- `pytest.ini` mit `asyncio_mode = auto` spart in allen folgenden Stories Boilerplate bei async Tests
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Was lief nicht gut? (Drop / Improve)
|
||||||
|
|
||||||
|
**Technisch:**
|
||||||
|
- `requirements.txt` verwendet `>=`-Versionen statt gepinnte Versionen — Reproduzierbarkeit bei längerer Projektlaufzeit gefährdet. Ein `pip freeze > requirements.lock` wäre sinnvoll
|
||||||
|
- `check_same_thread=False` bei SQLite deaktiviert Thread-Sicherheit — akzeptabel für Tests, aber muss dokumentiert bleiben
|
||||||
|
- Uvicorn `--reload` ist im Dockerfile hard-coded — für Produktions-Builds sollte ein separates Dockerfile oder Multi-Stage-Build verwendet werden
|
||||||
|
- Keine explizite Connection-Pool-Konfiguration für SQLAlchemy — Defaults könnten bei Last nicht ausreichen
|
||||||
|
|
||||||
|
**Prozess:**
|
||||||
|
- Keine automatische CI-Pipeline eingerichtet (GitHub Actions) — Tests müssen manuell ausgeführt werden
|
||||||
|
- `alembic.ini` hat die `sqlalchemy.url` hard-coded — sollte aus Umgebungsvariablen gelesen werden (bereits in `env.py` gefixt)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Lernerkenntnisse
|
||||||
|
|
||||||
|
| Erkenntnis | Anwendung in kommenden Epics |
|
||||||
|
|------------|------------------------------|
|
||||||
|
| Async-First-Design vermeidet teure Refactoring-Runden später | Alle Agent-Nodes in Epic 2 als async-kompatibel designen |
|
||||||
|
| SQLite als Test-DB ermöglicht In-Memory-Tests ohne Docker | Alle Backend-Tests in Epics 2–5 nutzen `aiosqlite` |
|
||||||
|
| Docker Health-Checks sind essentiell bei Multi-Service-Setups | Für Produktion noch Readiness-Probes ergänzen |
|
||||||
|
| `pytest-asyncio` `auto`-Mode spart pro Test 2 Zeilen Boilerplate | Konsistent in allen 125+ Backend-Tests verwendet |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Aktionspunkte für kommende Epics
|
||||||
|
|
||||||
|
| Priorität | Aktionspunkt | Verantwortlich | Status |
|
||||||
|
|-----------|-------------|----------------|--------|
|
||||||
|
| Hoch | Agent-Nodes als reine Funktionen implementieren (State rein → Dict raus) | Dev | Umgesetzt in Epic 2 |
|
||||||
|
| Mittel | `requirements.lock` mit gepinnten Versionen erstellen | Dev | Backlog |
|
||||||
|
| Mittel | Produktions-Dockerfile ohne `--reload` erstellen | Dev | Backlog |
|
||||||
|
| Niedrig | CI-Pipeline mit GitHub Actions aufsetzen | Dev | Backlog |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Nächstes Epic (Preview: Epic 2)
|
||||||
|
|
||||||
|
**Epic 2 — LangGraph Engine Backend** baut direkt auf der Infrastruktur aus Epic 1 auf:
|
||||||
|
- CouncilState TypedDict mit `operator.add`-Reducern (Story 2.1 ✅)
|
||||||
|
- Master-, Critic- und Writer-Agent als reine Node-Funktionen (Stories 2.2–2.4 ✅)
|
||||||
|
- Hartcodierter LangGraph-Graph mit zyklischer Routing-Logik (Story 2.5 ✅)
|
||||||
|
- FastAPI-Endpunkte für Council-Runs (Story 2.6 ✅)
|
||||||
|
|
||||||
|
**Wichtige Brücke:** Die async-Architektur aus Epic 1 (asyncpg, pytest-asyncio) ist das Fundament für alle Backend-Services in Epic 2.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Bob (Scrum Master): "Epic 1 war das stille Fundament-Epic — keine sichtbaren Features, aber absolut kritisch für alles Folgende. Die Entscheidung für Async-First und Dual-Database hat sich in allen 5 Epics ausgezahlt. Saubere Infrastruktur von Anfang an ist kein Luxus, sondern Notwendigkeit."*
|
||||||
|
|
@ -0,0 +1,95 @@
|
||||||
|
# Retrospektive — Epic 2: LangGraph Engine Backend (Phase 1)
|
||||||
|
|
||||||
|
<!-- 🏃 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 2 — LangGraph Engine Backend (Phase 1)
|
||||||
|
**Status:** Abgeschlossen — 6/6 Stories erledigt
|
||||||
|
**Facilitiert von:** Bob (🏃 Scrum Master)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Epic-Zusammenfassung
|
||||||
|
|
||||||
|
**Ziel:** Funktionierender, hartcodierter LangGraph-Graph (Master→Critic→Writer) mit CouncilState, Routing-Logik und FastAPI-Endpunkten. Verifikation via Terminal/Postman.
|
||||||
|
|
||||||
|
**Stories abgeschlossen:**
|
||||||
|
- ✅ 2.1: CouncilState TypedDict implementieren
|
||||||
|
- ✅ 2.2: Master-Agent-Node implementieren
|
||||||
|
- ✅ 2.3: Critic-Agent-Node implementieren
|
||||||
|
- ✅ 2.4: Writer-Agent-Node implementieren
|
||||||
|
- ✅ 2.5: LangGraph-Graph bauen und ausführen
|
||||||
|
- ✅ 2.6: FastAPI-Run-Endpunkte implementieren
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Was lief gut? (Keep)
|
||||||
|
|
||||||
|
**Technische Entscheidungen:**
|
||||||
|
- **TypedDict + `operator.add`-Reducer** für `feedback_history` und `messages` — elegant, typensicher, und verhindert versehentliches Überschreiben akkumulativer Felder
|
||||||
|
- **Numerischer Score als Single Source of Truth** in der Critic-Routing-Logik: `route_decision` wird ausschließlich vom geparsten Score abgeleitet (≥ 8.0 = approve), nicht vom LLM-generierten VERDICT-String. Das eliminiert Inkonsistenzen zwischen Score und Routing
|
||||||
|
- **Safety Valve** (`MAX_ITERATIONS = 5`): Erzwingt Genehmigung nach 5 Iterationen — verhindert Endlosschleifen ohne manuellen Eingriff
|
||||||
|
- **Stateless Agent-Funktionen**: Jeder Agent-Node ist eine reine Funktion (State rein → Dict raus) — perfekt testbar und leicht in den dynamischen Graph-Builder (Phase 3) übernehmbar
|
||||||
|
- **`run_in_executor()`-Pattern** für die Brücke zwischen async FastAPI und synchronem `graph.invoke()` — verhindert Event-Loop-Blocking
|
||||||
|
- **Differenzierte Temperaturen**: Master (0.7 kreativ), Critic (0.2 streng), Writer (0.4 ausgewogen) — jeder Agent hat ein klar definiertes Verhaltensprofil
|
||||||
|
|
||||||
|
**Prozess:**
|
||||||
|
- Story-Reihenfolge State → Agents → Graph → API war logisch perfekt — jede Story baut auf der vorherigen auf
|
||||||
|
- 125 Backend-Tests mit vollständig gemockten LLMs — keine echten API-Aufrufe in CI, schnelle Ausführung
|
||||||
|
- `_parse_critic_response()` als separate Funktion isoliert das fragile Parsing — leicht zu testen und zu verbessern
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Was lief nicht gut? (Drop / Improve)
|
||||||
|
|
||||||
|
**Technisch:**
|
||||||
|
- **LLM-Instanziierung pro Aufruf**: `ChatAnthropic()` wird in jedem Agent-Node neu erstellt — Performance-Overhead bei hoher Auslastung. Ein Singleton oder Dependency-Injection wäre effizienter
|
||||||
|
- **Regex-basiertes Critic-Parsing** (`_parse_critic_response`) ist fragil: Bei nicht-parsbare Antworten fällt der Score auf 0.0 zurück — funktioniert als Fallback, aber log-würdig
|
||||||
|
- **`threading.Lock` in asyncem Code** (`RunStore`): Synchrone Locks auf asyncem Code bergen Deadlock-Risiko. Sollte `asyncio.Lock` verwenden
|
||||||
|
- **In-Memory `RunStore`** wächst unbegrenzt und geht bei Server-Neustart verloren — für Phase 1 akzeptabel, für Produktion nicht
|
||||||
|
- **ThreadPoolExecutor ohne Limit**: `run_in_executor(None, ...)` verwendet den Default-Pool ohne maximale Thread-Anzahl — bei vielen parallelen Runs könnte das System überlastet werden
|
||||||
|
|
||||||
|
**Prozess:**
|
||||||
|
- Kein End-to-End-Test der kompletten Graph-Ausführung mit echtem Zyklusdurchlauf — Unit-Tests decken Einzelteile ab, aber der Integrations-Test fehlt
|
||||||
|
- WebSocket-Endpunkt hat keine Authentifizierung — jeder Client kann sich auf beliebige `run_id`s subscriben
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Lernerkenntnisse
|
||||||
|
|
||||||
|
| Erkenntnis | Anwendung in kommenden Epics |
|
||||||
|
|------------|------------------------------|
|
||||||
|
| `operator.add`-Reducer sind eleganter als manuelle Liste-Append-Logik | Für alle zukünftigen State-Felder, die akkumulieren sollen |
|
||||||
|
| Numerisches Routing statt LLM-VERDICT ist deterministisch und testbar | Im dynamischen Graph-Builder (Phase 3) das gleiche Pattern verwenden |
|
||||||
|
| Stateless Agent-Funktionen sind trivial in dynamische Graphen übertragbar | Phase 3 kann dieselben Node-Funktionen wiederverwenden |
|
||||||
|
| `run_in_executor` ist die Standard-Brücke zwischen async/sync in FastAPI | Für alle CPU-/IO-blockierenden Operationen in Epic 4+ nutzen |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Aktionspunkte für kommende Epics
|
||||||
|
|
||||||
|
| Priorität | Aktionspunkt | Verantwortlich | Status |
|
||||||
|
|-----------|-------------|----------------|--------|
|
||||||
|
| Hoch | In-Memory RunStore durch PostgreSQL-Persistenz ersetzen | Dev | Umgesetzt in Story 5.4 |
|
||||||
|
| Hoch | Dynamischer Graph-Builder für Phase 3 (JSON → LangGraph) | Dev | Umgesetzt in Story 4.1 |
|
||||||
|
| Mittel | LLM-Instanzen cachen oder per Dependency Injection bereitstellen | Dev | Backlog |
|
||||||
|
| Mittel | `threading.Lock` → `asyncio.Lock` im RunStore | Dev | Backlog |
|
||||||
|
| Niedrig | WebSocket-Authentifizierung hinzufügen | Dev | Backlog |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Nächstes Epic (Preview: Epic 3)
|
||||||
|
|
||||||
|
**Epic 3 — Visueller Baukasten Frontend** nutzt die Backend-API aus Epic 2:
|
||||||
|
- React Flow Canvas mit Custom Agent Nodes (Story 3.1 ✅)
|
||||||
|
- Lineare und bedingte Edges (Story 3.2 ✅)
|
||||||
|
- Blueprint-Parser konvertiert Canvas → JSON (Story 3.3 ✅)
|
||||||
|
- Blueprint CRUD verbindet Frontend mit Backend-API (Story 3.4 ✅)
|
||||||
|
|
||||||
|
**Wichtige Brücke:** Die REST-API aus Story 2.6 (`POST /api/councils/run`, `GET /api/councils/run/{run_id}`) wird in Epic 3 vom Frontend konsumiert. Das Blueprint-JSON aus Epic 3 wird ab Epic 4 den hartcodierten Graph aus Story 2.5 ablösen.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Bob (Scrum Master): "Epic 2 ist das technische Herz von CouncilOS. Die Entscheidung, den Critic-Score als numerische Single Source of Truth zu verwenden — nicht den LLM-generierten VERDICT-String — war die wichtigste Architekturentscheidung des gesamten Projekts. Zusammen mit dem Safety Valve und den stateless Agent-Funktionen haben wir ein robustes, testbares, und erweiterbares Fundament geschaffen. 125 Tests sprechen für sich."*
|
||||||
Loading…
Add table
Add a link
Reference in a new issue