Agent-Introspektion und Debugging

Was macht Agent-Introspektion und Debugging?

Verwende diesen Skill, wenn ein Agentenlauf wiederholt fehlschlägt, Token ohne Fortschritt verbraucht, sich in denselben Tools aufhängt oder von der beabsichtigten Aufgabe abdriftet.

Dies ist ein Workflow-Skill, keine versteckte Laufzeitumgebung. Er lehrt den Agenten, sich systematisch selbst zu debuggen, bevor ein menschlicher Eingriff nötig ist.

Wann aktivieren

• Maximales Tool-Call- / Schleifenlimit erreicht
• Wiederholte Versuche ohne Fortschritt
• Kontextwachstum oder Prompt-Drift, der die Ausgabequalität verschlechtert
• Abweichung zwischen erwartetem und tatsächlichem Dateisystem- oder Umgebungszustand
• Tool-Fehler, die mit Diagnose und einer kleineren Korrekturmaßnahme behebbar erscheinen

Abgrenzung

Diesen Skill aktivieren für:

• Erfassen des Fehlerzustands, bevor blind erneut versucht wird
• Diagnose häufiger agentspezifischer Fehlermuster
• Anwenden eingegrenzter Behebungsmaßnahmen
• Erstellen eines strukturierten, menschenlesbaren Debug-Berichts

Diesen Skill nicht als primäre Quelle verwenden für:

• Funktionsüberprüfung nach Codeänderungen; stattdessen verification-loop verwenden
• Framework-spezifisches Debugging, wenn bereits ein engerer ECC-Skill existiert
• Laufzeitversprechen, die die aktuelle Umgebung nicht automatisch durchsetzen kann

Vierphasen-Schleife

Phase 1: Fehlererfassung

Bevor eine Behebung versucht wird, den Fehler genau erfassen.

Erfassen:

• Fehlertyp, Meldung und Stacktrace, falls verfügbar
• Letzte sinnvolle Tool-Call-Sequenz
• Was der Agent gerade tun wollte
• Aktueller Kontextdruck: wiederholte Prompts, übermäßig große eingefügte Logs, duplizierte Pläne oder ausufernde Notizen
• Aktuelle Umgebungsannahmen: Arbeitsverzeichnis, Branch, relevanter Service-Status, erwartete Dateien

Mindestvorlage zur Erfassung:

## Fehlererfassung
- Sitzung / Aufgabe:
- Verfolgtes Ziel:
- Fehler:
- Letzter erfolgreicher Schritt:
- Letztes fehlgeschlagenes Tool / Befehl:
- Wiederholtes Muster gesehen:
- Zu überprüfende Umgebungsannahmen:

Phase 2: Ursachen-Diagnose

Den Fehler mit einem bekannten Muster abgleichen, bevor etwas geändert wird.

Muster	Wahrscheinliche Ursache	Prüfung
Maximale Tool-Calls / wiederholter gleicher Befehl	Schleife oder kein Exit-Beobachterpfad	Die letzten N Tool-Aufrufe auf Wiederholung prüfen
Kontextüberlauf / nachlassendes Denkvermögen	Unbegrenzte Notizen, wiederholte Pläne, übermäßig große Logs	Aktuellen Kontext auf Duplikate und signalarme Massen prüfen
ECONNREFUSED / Timeout	Dienst nicht verfügbar oder falscher Port	Dienstzustand, URL und Portannahmen prüfen
429 / Kontingenterschöpfung	Wiederholungssturm oder fehlender Backoff	Wiederholte Aufrufe zählen und Abstände prüfen
Datei nach Schreibvorgang fehlt / veralteter Diff	Wettlaufsituation, falsches Arbeitsverzeichnis oder Branch-Abweichung	Pfad, Arbeitsverzeichnis, Git-Status und tatsächliche Dateiexistenz erneut prüfen
Tests schlagen nach "Behebung" immer noch fehl	Falsche Hypothese	Den genauen fehlschlagenden Test isolieren und den Fehler neu herleiten

Diagnosefragen:

• Handelt es sich um einen Logikfehler, Zustandsfehler, Umgebungsfehler oder Richtlinienverstoß?
• Hat der Agent das eigentliche Ziel aus den Augen verloren und beginnt, die falsche Teilaufgabe zu optimieren?
• Ist der Fehler deterministisch oder transient?
• Was ist die kleinste reversible Aktion, die die Diagnose bestätigen würde?

Phase 3: Eingegrenzte Behebung

Mit der kleinsten Aktion beheben, die die Diagnosefläche verändert.

Sichere Behebungsmaßnahmen:

• Wiederholte Versuche stoppen und die Hypothese neu formulieren
• Signalarmen Kontext entfernen und nur das aktive Ziel, Hindernisse und Belege behalten
• Tatsächlichen Dateisystem-/Branch-/Prozesszustand erneut prüfen
• Die Aufgabe auf einen fehlschlagenden Befehl, eine Datei oder einen Test eingrenzen
• Von spekulativem Denken zu direkter Beobachtung wechseln
• An einen Menschen eskalieren, wenn der Fehler mit hohem Risiko verbunden oder extern blockiert ist

Keine nicht unterstützten automatischen Heilungsmaßnahmen behaupten (z. B. "Agenten-Status zurücksetzen" oder "Umgebungskonfiguration aktualisieren"), es sei denn, sie werden tatsächlich durch reale Tools in der aktuellen Umgebung ausgeführt.

Checkliste für eingegrenzte Behebung:

## Behebungsmaßnahme
- Gewählte Diagnose:
- Kleinste durchgeführte Aktion:
- Warum dies sicher ist:
- Welcher Beleg würde beweisen, dass die Behebung funktioniert hat:

Phase 4: Introspektionsbericht

Mit einem Bericht abschließen, der die Behebung für den nächsten Agenten oder Menschen nachvollziehbar macht.

## Agent-Selbst-Debug-Bericht
- Sitzung / Aufgabe:
- Fehler:
- Ursache:
- Behebungsmaßnahme:
- Ergebnis: Erfolg | Teilweise | Blockiert
- Token-/Zeit-Kostenrisiko:
- Erforderliche Nachverfolgung:
- Vorbeugende Änderung zur späteren Kodierung:

Behebungsheuristiken

Diese Maßnahmen in der angegebenen Reihenfolge bevorzugen:

1. Das eigentliche Ziel in einem Satz neu formulieren.
2. Den Weltzustand überprüfen, anstatt dem Gedächtnis zu vertrauen.
3. Den Umfang des Fehlers verkleinern.
4. Eine einzelne unterscheidende Prüfung durchführen.
5. Erst dann erneut versuchen.

Schlechtes Muster:

• Dieselbe Aktion dreimal mit leicht unterschiedlicher Formulierung wiederholen

Gutes Muster:

• Fehler erfassen
• Das Muster klassifizieren
• Eine direkte Prüfung durchführen
• Den Plan nur ändern, wenn die Prüfung dies stützt

Integration mit ECC

• Nach einer Behebung, bei der Code geändert wurde, verification-loop verwenden.
• Wenn das Fehlermuster es wert ist, in eine Intuition oder einen späteren Skill umgewandelt zu werden, continuous-learning-v2 verwenden.
• Wenn das Problem kein technischer Fehler, sondern eine Entscheidungsambiguität ist, council verwenden.
• Wenn der Fehler durch widersprüchlichen lokalen Zustand oder Repository-Abweichung entstanden ist, workspace-surface-audit verwenden.

Ausgabestandard

Wenn dieser Skill aktiv ist, nicht einfach mit "Ich habe es behoben" enden.

Immer angeben:

• das Fehlermuster
• die Ursachenhypothese
• die Behebungsmaßnahme
• den Beleg, dass sich die Situation verbessert hat oder immer noch blockiert ist