Orchestrator/bahn/O2C-Harness/self-review.md

# Self-Review & Pipeline-Überwachung

## Code-Review vor Push

Vor dem Push den eigenen Code reviewen:
- Naming Conventions eingehalten?
- Keine TODOs oder Debug-Code?
- Tests vollständig?
- Doku aktuell?

## Pipeline-Überwachung (Pflicht nach jedem Push)

Nach JEDEM `git push` die Pipeline überwachen mit Polling:

```bash
# Pipeline-Status abfragen (wiederholen bis nicht mehr "running")
glab ci status

# Wenn "running" → 30 Sekunden warten und erneut prüfen
sleep 30
glab ci status

# Bei "failed" → Logs des fehlgeschlagenen Jobs anzeigen
glab ci view
```

### Polling-Schleife (so implementieren):

```bash
# Solange "running" → weiter pollen
while true; do
  STATUS=$(glab ci status 2>&1)
  echo "$STATUS"
  if echo "$STATUS" | grep -q "passed"; then
    echo "Pipeline erfolgreich!"
    break
  elif echo "$STATUS" | grep -qE "failed|canceled"; then
    echo "Pipeline fehlgeschlagen – abbrechen und fixen"
    glab ci cancel
    glab ci view
    break
  fi
  sleep 30
done
```

### WICHTIG:
- `glab ci status` funktioniert OHNE `--wait` Flag
- NICHT die GitLab API direkt aufrufen (kein Zugriff auf Web-UI)
- Einfach `glab ci status` wiederholt aufrufen mit `sleep 30` dazwischen

## Bei Pipeline-Fehler

1. `glab ci view` – Fehlgeschlagenen Job identifizieren
2. Fehler analysieren
3. Fix committen
4. Erneut pushen
5. Pipeline erneut überwachen

## Deployment-Stages

| Branch | Umgebung | Automatisch? |
|--------|----------|-------------|
| Feature-Branch | Preview (Dev) | ✅ Ja |
| main | Produktion | ✅ Ja (nach Merge) |

## Pipeline-Fehler diagnostizieren

### Logs lesen mit glab

```bash
# Jobs der Pipeline auflisten
glab api "projects/:id/pipelines/$(glab ci status 2>&1 | grep -oP '#\K[0-9]+')/jobs"

# Job-Log lesen (Job-ID aus obigem Output)
glab api "projects/:id/jobs/{job_id}/trace"

# Wenn keine Jobs vorhanden (leeres Array []):
# → Kein Runner verfügbar ODER .gitlab-ci.yml fehlerhaft
```

### Häufige Fehler

| Symptom | Ursache | Fix |
|---------|---------|-----|
| Pipeline failed, keine Jobs | YAML-Fehler | `.gitlab-ci.yml` prüfen |
| Job failed: "image not found" | Falsches Docker-Image | DB Container Lib Image nutzen |

## Um Hilfe bitten (statt endlos loopen)

Wenn du nach **3 Versuchen** ein Problem nicht lösen kannst:

1. **STOPPE** – nicht weiter versuchen
2. **Dokumentiere** das Problem klar in einer Nachricht:
   - Was du versucht hast
   - Welcher Fehler auftritt
   - Was du als Ursache vermutest
3. **Schreibe in die Konsole**: `echo "HELP: <deine Frage>"`

Beispiel:
```
Ich komme nicht weiter. Die Pipeline schlägt fehl:
- Symptom: Pipeline failed, keine Jobs werden gestartet
- Versucht: .gitlab-ci.yml angepasst (3x)
- Frage: Wie sieht die korrekte .gitlab-ci.yml für dieses Projekt aus?
```

### Wann um Hilfe bitten:
- Pipeline-Fehler nach 3 Fix-Versuchen
- Zugriffsprobleme (401/403/404)
- Unklare Anforderungen
- Fehlende Credentials oder Konfiguration
- Tool funktioniert nicht wie erwartet

### NICHT endlos loopen bei:
- Gleichem Fehler der sich wiederholt
- Timeout/Netzwerk-Problemen
- Fehlenden Berechtigungen

## Pipeline manuell triggern

Wenn nach einem Push keine neue Pipeline startet (alter SHA in `glab ci status`):

```bash
# Pipeline manuell für aktuellen Branch triggern
glab ci create --ref $(git branch --show-current)
```

Dann erneut mit `glab ci status` überwachen.

## Kein Runner verfügbar

Wenn Pipeline failed mit 0 Jobs oder Jobs ewig "pending" bleiben:
- Ursache: Kein Runner mit passenden Tags im Projekt
- Das ist ein Infrastruktur-Problem, kein Code-Problem
- In der MR-Beschreibung vermerken: "Pipeline benötigt Runner mit Tags: group-runner, kubernetes"
- Nicht endlos versuchen zu fixen

## MR-Pipeline überwachen

- MR-Pipeline hat alle Jobs (lint, test, build, deploy)

**Ablauf:**
1. Push auf Feature-Branch
2. MR erstellen (`glab mr create ...`)
3. DANN Pipeline überwachen: `glab ci status` (zeigt MR-Pipeline)
4. Bei Fehler: `glab ci list` → Job-Logs lesen → fixen → pushen
5. MR-Pipeline startet automatisch neu nach Push

**Job-Logs lesen:**
```bash
# Fehlgeschlagene Jobs finden
glab ci list

# Trace eines bestimmten Jobs (non-interaktiv)
glab api "projects/:id/jobs/{job_id}/trace" | tail -50
```

### Signal für Hilfe

Wenn du nicht weiterkommst, schreibe EXAKT dieses Format in die Shell:

```bash
echo "HELP: Pipeline failed mit 0 Jobs - wie soll die .gitlab-ci.yml aussehen?"
```

Das `HELP:` Prefix wird vom Orchestrator erkannt und signalisiert dem Benutzer im Dashboard, dass du Hilfe brauchst. Warte danach auf eine Antwort.

### Pipeline-Status loggen

Beim Überwachen der Pipeline den Status in die Konsole schreiben, damit das Dashboard den Fortschritt zeigt:

```bash
echo "PROMPT: Pipeline überwachen - warte auf MR-Pipeline"
# ... polling ...
echo "PROMPT: Pipeline grün - alle Jobs bestanden"
# oder
echo "PROMPT: Pipeline fehlgeschlagen - Job lint_scm_info failed"
```

### Fortschritt und ETA loggen

Nach jedem abgeschlossenen Arbeitsschritt den Fortschritt melden:

```bash
echo "PROGRESS: 20% - Issues angelegt, starte Implementierung (ETA: 8min)"
echo "PROGRESS: 50% - Backend fertig, starte Frontend (ETA: 5min)"
echo "PROGRESS: 70% - Tests geschrieben, starte Quality Gates (ETA: 3min)"
echo "PROGRESS: 85% - Gepusht, MR erstellt, warte auf Pipeline (ETA: 2min)"
echo "PROGRESS: 100% - Fertig"
```

Format: `PROGRESS: {prozent}% - {was gerade passiert} (ETA: {geschätzte Restzeit})`

Schätze die ETA basierend auf:
- Anzahl verbleibender Issues/Aufgaben
- Bisherige Dauer pro Schritt
- Komplexität der verbleibenden Arbeit

### Referenzen in Logs

Wenn du Issues, MRs oder Pipelines erstellst/referenzierst, gib die URL oder Referenz mit an:

```bash
echo "PROMPT: Issues angelegt: #1 #2 #3 #4 in https://git.tech.rz.db.de/group/project"
echo "PROMPT: MR erstellt: https://git.tech.rz.db.de/group/project/-/merge_requests/1"
echo "PROMPT: Pipeline überwachen: https://git.tech.rz.db.de/group/project/-/pipelines/12345"
```

Das Dashboard macht URLs und #Issue/!MR-Referenzen automatisch klickbar.