nixos-config/docs/review/board-review-pipeline-context-overhead.md

# Bericht: Aufwand zur Kontextbeschaffung in dieser Session

Deine Ausgangsnachricht war ein einziger Satz, ohne Job-ID, ohne Fehlermeldung, ohne Dateiverweis:

> „ein review ist auf fehlgeschlagen im intent board pipeline Intent: Isolierte Worktrees und parallele Builder-Jobs für das Board"

Alles Weitere musste ich mir selbst erarbeiten. Grobe Zählung der tatsächlichen Tool-Aufrufe (Bash/Read/Grep/Edit/Write/etc.) über die gesamte Session: **rund 80**, davon der überwiegende Teil reine Kontextbeschaffung, bevor überhaupt eine Korrektur möglich war.

## Phase 1 — Wo ist die Karte, wo ist der Fehler? (~9 Aufrufe)
- `git status` + Intent-Dokument lesen, um den Slug zu identifizieren
- Verzeichnisstruktur suchen (`find -iname "*board*"`) — der Prompt nannte keinen Pfad
- `hostname` prüfen, ob überhaupt auf blunix gearbeitet wird (wo der Live-State liegt)
- `/var/lib/board-agent/{inbox,processing,failed,done}` durchsuchen, bis die passende JSON-Datei auftauchte
- Die eigentliche Fehlermeldung stand am Ende in einer einzelnen Zeile: „Reviewer lieferte keinen ===REVIEW-REPORT===-Block."

## Phase 2 — Code lesen, um die Fehlermeldung überhaupt einzuordnen (~20 Aufrufe)
Die Fehlermeldung allein sagt nichts darüber, *warum* der Marker fehlte. Nötig war:
- `worker.py` komplett lesen (Prompt-Templates, `parse_claude_response`, `extract_review_report`, `run_review`, `process_job`) — ~460 Zeilen
- `trigger.py` und `README.md` gegenlesen, um zu verstehen, welche Phasen/Spalten es gibt und ob es einen „Retry"-Mechanismus gibt (gibt es nicht)
- `test_board_agent.py` an mehreren Stellen lesen, um zu verifizieren, ob `phase="review"` nach einem Review absichtlich stehen bleibt oder ein Bug ist (war Absicht — steht so in den Tests)
- Mehrere `journalctl`-Läufe mit falschen Zeitfenstern (leere Ergebnisse), bis das richtige Zeitfenster und die richtige Journal-Zeile gefunden waren — der Log-Eintrag selbst enthielt aber nur dieselbe knappe Fehlermeldung, keine Rohausgabe des Modells

## Phase 3 — Root Cause: die eigentliche Modellantwort rekonstruieren (~15 Aufrufe)
`worker.py` druckt die Modellantwort nur bei Erfolg — bei einem Fehler ist sie nirgends gespeichert außer im Claude-Transkript selbst. Also:
- `~/.claude/projects/-home-drone-nixos-config-agents/` durchsuchen nach der passenden `.jsonl`-Sitzung anhand des Zeitfensters
- Mehrfach mit `grep -o`/`wc -l` die Anzahl von `===REVIEW-REPORT===` vs. `===END-REVIEW-REPORT===` gezählt, um zu verifizieren, ob der Marker überhaupt geschrieben wurde
- `python3`/`python`/`node` waren auf blunix gar nicht im Pfad verfügbar — Umstieg auf `jq`, um JSON aus der Transkript-Datei zu extrahieren
- damit die tatsächliche, vollständige, aber unabgeschlossene Review-Antwort wiederhergestellt

## Phase 4 — Erster Recovery-Versuch, Blockade, Rückfrage (~5 Aufrufe)
- Bericht manuell nach `docs/review/…md` geschrieben
- Versuch, `state.json` per `jq` zu korrigieren → **vom Auto-Mode-Classifier blockiert** (Live-Service-State außerhalb des Repos)
- Rückfrage per `AskUserQuestion` → Entscheidung für einen echten Retry über die Pipeline statt manueller Reparatur

## Phase 5 — Retry #1, gleicher Fehler, zweite Fehleranalyse (~8 Aufrufe)
- Neuen Job in `/var/lib/board-agent/inbox/` geschrieben
- **Fehlgeschlagene Monitor-Bedingung** (systemd meldet bei Oneshot-Services nie „active", sondern „activating" → falsches „DONE" nach 3 Sekunden, während der Job noch lief) — Wartelogik musste korrigiert und neu aufgesetzt werden
- Zweites Transkript gefunden und ausgewertet → **exakt derselbe Fehler**, damit als reproduzierbar (2/2) bestätigt
- Erneute Rückfrage → Entscheidung, den Root Cause im Code zu fixen

## Phase 6 — Fix, Test, Deploy, Verifikation (~15 Aufrufe)
- `extract_review_report()` in `worker.py` robuster gemacht (Fallback ohne Closing-Marker)
- Regressionstest ergänzt, volle Testsuite (58 Tests) über `nix-shell` laufen lassen
- `predeploy-check`-Skill für blunix gestartet → `nix eval` scheiterte zunächst mit `path:`-Präfix, Umstellung auf `.`
- `nix build` + `nix store diff-closures` → Diff zeigte **keine** Änderung an, obwohl der Code sich geändert hatte (bekannte Einschränkung von `diff-closures` bei unversionierten eigenen Skript-Derivationen — falscher Alarm, erst über `ExecStart`-Pfad-Vergleich aufgelöst)
- Deploy erfolgte durch den Nutzer selbst („switched") — verifiziert über den geänderten `ExecStart`-Store-Pfad und einen `grep` auf den neuen Code-Kommentar, da `/run/current-system` textuell gleich aussah

## Phase 7 — Retry #2, endlich sauber (~4 Aufrufe)
- Dritten Job requeued, korrekt auf „fertig" gewartet, Ergebnis geprüft → lief durch, mit einem echten (neuen) Befund: fehlende Testabdeckung für die neue Concurrency-Logik in `trigger.py`.

## Fazit
Von den ~80 Aufrufen entfielen **grob 45–50 allein auf Kontextbeschaffung und Root-Cause-Diagnose**, bevor überhaupt eine Korrektur möglich war — das liegt vor allem daran, dass die Pipeline keine zentrale, aussagekräftige Fehlerquelle hat: die Fehlermeldung in `state.json`/journal ist bewusst knapp gehalten, die eigentliche Modellantwort landet nur bei Erfolg irgendwo, und bei einem Fehler existiert sie ausschließlich verstreut im Claude-Session-Transkript. Zwei zusätzliche Reibungspunkte kosteten weitere Zyklen: kein `python3` im Pfad auf blunix, und eine falsche Annahme über `systemctl is-active`-Semantik bei Oneshot-Services, die zu einer verfrühten Fehlmeldung führte.