breakpilot-pwa/.claude/skills/debug-framework.md

Systematisches Debug-Framework

Trigger

Dieses Skill aktivieren bei:

• Fehlermeldungen / Exceptions
• Unerwartetes Verhalten
• Performance-Probleme
• "Es funktioniert nicht"

---

Phase 1: Reproduzieren (5 min max)

Ziel: Bug in einen Test verwandeln

# 1. Exakte Schritte dokumentieren
# 2. Fehlermeldung/Symptom notieren
# 3. Umgebung identifizieren

Fragen:

• Ist der Bug reproduzierbar?
• Tritt er nur in bestimmten Umgebungen auf?
• Seit wann tritt er auf? (letzter Deploy?)

Breakpilot-spezifisch: Welcher Service?

# Container-Status prüfen
ssh macmini "docker compose ps | grep -E '(Exit|unhealthy)'"

# Logs der letzten 5 Minuten
ssh macmini "docker compose logs --since 5m <service-name>"

Symptom	Wahrscheinlicher Service
Login fehlgeschlagen	consent-service, backend
502 Bad Gateway	nginx, upstream-service
Langsame Suche	qdrant, embedding-service
Upload-Fehler	minio, backend
OCR-Fehler	paddleocr-service, klausur-service

---

Phase 2: Hypothesen bilden (5 min max)

3-5 mögliche Ursachen auflisten

#	Hypothese	Wahrscheinlichkeit	Test
1		Hoch/Mittel/Niedrig
2
3

Häufige Ursachen bei Breakpilot

Container/Docker:

• Container nicht gestartet
• Volume-Mount-Problem
• Netzwerk zwischen Containern unterbrochen
• Resource-Limits erreicht

Datenbank:

• Connection Pool erschöpft
• Migration nicht ausgeführt
• Deadlock

API/Backend:

• JWT abgelaufen
• CORS-Fehler
• Rate-Limit erreicht
• Falscher Content-Type

Frontend:

• Cache-Problem (Safari!)
• Build nicht aktualisiert
• Umgebungsvariable fehlt

---

Phase 3: Systematisch eliminieren (10 min max)

Reihenfolge: Schnellste Tests zuerst

# 1. Ist der Service überhaupt erreichbar?
curl -s https://macmini:8000/health | jq

# 2. Container-Logs auf Fehler prüfen
ssh macmini "docker compose logs --tail 50 <service> 2>&1 | grep -iE '(error|exception|failed|traceback)'"

# 3. Datenbank-Verbindung testen
ssh macmini "docker exec breakpilot-pwa-postgres pg_isready"

# 4. Redis/Valkey erreichbar?
ssh macmini "docker exec breakpilot-pwa-valkey valkey-cli ping"

Hypothese testen

Für jede Hypothese:

1. Test definieren (wie prüfen wir das?)
2. Test ausführen
3. Ergebnis: Bestätigt ✅ / Widerlegt ❌

---

Phase 4: Root Cause identifizieren

Nicht das Symptom behandeln!

Schlecht: "Ich starte den Container neu" Gut: "Der Container crashed wegen OOM → Memory-Limit erhöhen"

5-Why-Methode

Problem: API gibt 500 zurück
↓ Warum?
Datenbank-Query failed
↓ Warum?
Connection Pool erschöpft
↓ Warum?
Connections werden nicht freigegeben
↓ Warum?
Exception vor connection.close()
↓ Warum?
Fehlendes try/finally
→ ROOT CAUSE: Fehlendes Resource-Cleanup

---

Phase 5: Fix implementieren

Checkliste vor dem Fix

• Root Cause verstanden (nicht nur Symptom)
• Fix adressiert Root Cause
• Keine Seiteneffekte erwartet
• Test geschrieben, der Regression verhindert

Fix-Template

# VORHER: Bug
def fetch_data():
    conn = get_connection()
    result = conn.query(...)  # Exception hier → Leak!
    conn.close()
    return result

# NACHHER: Fix mit Erklärung
def fetch_data():
    """Fetch data with proper connection handling.
    
    Fixed: Connection leak when query raises exception.
    See: https://macmini:3003/.../issues/123
    """
    conn = get_connection()
    try:
        result = conn.query(...)
        return result
    finally:
        conn.close()  # Immer ausgeführt

---

Phase 6: Regression verhindern

Test schreiben

def test_connection_released_on_error():
    """Regression test for connection leak bug.
    
    Issue: #123
    Root cause: Missing finally block in fetch_data()
    """
    initial_connections = get_pool_size()
    
    with pytest.raises(DatabaseError):
        fetch_data_with_bad_query()
    
    # Connection should be returned to pool
    assert get_pool_size() == initial_connections

Dokumentieren

# Was haben wir gelernt?
# → docs-src/development/debugging-notes.md ergänzen

---

Quick Reference: Breakpilot Debug Commands

# Alle Container-Status
ssh macmini "docker compose ps"

# Logs eines Services (live)
ssh macmini "docker compose logs -f <service>"

# In Container einloggen
ssh macmini "docker exec -it breakpilot-pwa-<service> sh"

# PostgreSQL Query
ssh macmini "docker exec breakpilot-pwa-postgres psql -U breakpilot -d breakpilot_db -c 'SELECT 1'"

# Netzwerk-Debug
ssh macmini "docker exec breakpilot-pwa-backend curl -s http://consent-service:8081/health"

# Resource-Nutzung
ssh macmini "docker stats --no-stream"

# Vault-Status
ssh macmini "docker exec breakpilot-pwa-vault vault status"

---

Anti-Patterns vermeiden

❌ Nicht machen	✅ Stattdessen
Random Code ändern	Hypothese bilden, dann testen
console.log überall	Gezielt an verdächtigen Stellen
Container neustarten und hoffen	Root Cause finden
Stundenlang alleine debuggen	Nach 30 min Hilfe holen
Fix ohne Test	Immer Regression-Test schreiben