Agent-Introspektion-Debugging

Was macht Agent-Introspektion-Debugging?

Verwenden Sie diesen Skill, wenn ein Agentenlauf wiederholt fehlschlägt, Token ohne Fortschritt verbraucht, dieselben Werkzeuge in einer Schleife ausführt oder von der beabsichtigten Aufgabe abweicht.

Dies ist ein Workflow-Skill, keine verborgene Laufzeit. Er lehrt den Agenten, sich systematisch selbst zu debuggen, bevor er zu einem Menschen eskaliert.

Wann zu aktivieren

• Maximale Anzahl von Werkzeugaufrufen / Schleifen-Limit-Fehlern
• Wiederholte Versuche ohne Fortschritt
• Kontextwachstum oder Prompt-Drift, der die Ausgabequalität beeinträchtigt
• Diskrepanz zwischen erwartetem und tatsächlichem Dateisystem- oder Umgebungszustand
• Werkzeugfehler, die durch Diagnose und eine kleinere Korrekturmaßnahme behebbar sind

Umfangsgrenzen

Aktivieren Sie diesen Skill für:

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

Verwenden Sie diesen Skill NICHT als primäre Quelle für:

• Funktionsüberprüfung nach Codeänderungen; verwenden Sie verification-loop
• Frameworkspezifisches Debugging, wenn bereits ein engerer ECC-Skill existiert
• Laufzeit-Zusicherungen, die die aktuelle Umgebung nicht automatisch erzwingen kann

Vier-Phasen-Schleife

Phase 1: Fehlererfassung

Bevor Sie versuchen, den Fehler zu beheben, erfassen Sie ihn genau.

Erfassen:

• Fehlertyp, -meldung und Stack-Trace, falls verfügbar
• letzte aussagekräftige Sequenz von Werkzeugaufrufen
• was der Agent tun wollte
• aktueller Kontextdruck: wiederholte Prompts, übermäßig große eingefügte Logs, doppelte Pläne oder ausufernde Notizen
• aktuelle Umgebungsannahmen: Arbeitsverzeichnis, Branch, relevanter Dienststatus, erwartete Dateien

Minimale Vorlage zur Erfassung:

## Fehlererfassung
- Sitzung / Aufgabe:
- Ziel in Bearbeitung:
- Fehler:
- Letzter erfolgreicher Schritt:
- Letztes fehlgeschlagenes Werkzeug / Befehl:
- Wiederholtes Muster gesehen:
- Umgebungsannahmen zu überprüfen:

Phase 2: Ursachendiagnose

Vergleichen Sie den Fehler mit einem bekannten Muster, bevor Sie etwas ändern.

Muster	Wahrscheinliche Ursache	Prüfen
Maximale Werkzeugaufrufe / wiederholter gleicher Befehl	Schleife oder kein Exit-Beobachterpfad	Überprüfen Sie die letzten N Werkzeugaufrufe auf Wiederholung
Kontextüberlauf / verschlechtertes Denken	Unbegrenzte Notizen, wiederholte Pläne, übermäßig große Logs	Überprüfen Sie den aktuellen Kontext auf Duplikate und signalarme Massen
ECONNREFUSED / Timeout	Dienst nicht verfügbar oder falscher Port	Überprüfen Sie Dienststatus, URL und Portannahmen
429 / Kontingenterschöpfung	Wiederholungssturm oder fehlender Backoff	Zählen Sie wiederholte Aufrufe und überprüfen Sie die Wiederholungsabstände
Datei nach Schreibvorgang fehlt / veralteter Diff	Wettlaufsituation, falsches Arbeitsverzeichnis oder Branch-Drift	Pfad, Arbeitsverzeichnis, Git-Status und tatsächliches Vorhandensein der Datei erneut prüfen
Tests schlagen nach "Reparatur" immer noch fehl	Falsche Hypothese	Isolieren Sie den genau fehlschlagenden Test und leiten Sie den Fehler neu her

Diagnosefragen:

• Handelt es sich um einen Logik-, Zustands-, Umgebungs- oder Richtlinienfehler?
• Hat der Agent das eigentliche Ziel aus den Augen verloren und beginnt, die falsche Teilaufgabe zu optimieren?
• Ist der Fehler deterministisch oder vorübergehend?
• Was ist die kleinste umkehrbare Aktion, die die Diagnose validieren würde?

Phase 3: Kontrollierte Wiederherstellung

Stellen Sie den Zustand mit der kleinsten Aktion wieder her, die die Diagnoseoberfläche ändert.

Sichere Wiederherstellungsaktionen:

• Wiederholte Versuche stoppen und die Hypothese erneut formulieren
• Signalarmen Kontext kürzen und nur das aktive Ziel, Hindernisse und Beweise behalten
• Tatsächlichen Dateisystem-/Branch-/Prozesszustand erneut prüfen
• 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 ein hohes Risiko darstellt oder extern blockiert ist

Behaupten Sie keine nicht unterstützten automatischen Heilungsaktionen wie "Agentenzustand zurücksetzen" oder "Umgebungskonfiguration aktualisieren", es sei denn, Sie führen sie tatsächlich mit echten Werkzeugen in der aktuellen Umgebung durch.

Checkliste zur kontrollierten Wiederherstellung:

## Wiederherstellungsaktion
- Gewählte Diagnose:
- Kleinste durchgeführte Aktion:
- Warum dies sicher ist:
- Welcher Beweis würde zeigen, dass die Reparatur funktioniert hat:

Phase 4: Introspektionsbericht

Schließen Sie mit einem Bericht ab, der die Wiederherstellung für den nächsten Agenten oder Menschen nachvollziehbar macht.

## Selbst-Debug-Bericht des Agenten
- Sitzung / Aufgabe:
- Fehler:
- Ursache:
- Wiederherstellungsaktion:
- Ergebnis: Erfolg | Teilweise | Blockiert
- Token-/Zeit-Burn-Risiko:
- Erforderliche Nachverfolgung:
- Präventive Änderung zur späteren Kodierung:

Wiederherstellungs-Heuristiken

Bevorzugte Eingriffe in dieser Reihenfolge:

1. Formulieren Sie das eigentliche Ziel in einem Satz neu.
2. Überprüfen Sie den Weltzustand, anstatt dem Gedächtnis zu vertrauen.
3. Verkleinern Sie den fehlschlagenden Umfang.
4. Führen Sie eine einzelne diskriminierende Prüfung durch.
5. Erst dann wiederholen.

Schlechtes Muster:

• dieselbe Aktion dreimal mit leicht unterschiedlicher Formulierung wiederholen

Gutes Muster:

• Fehler erfassen
• Muster klassifizieren
• eine direkte Prüfung durchführen
• den Plan nur ändern, wenn die Prüfung dies unterstützt

Integration mit ECC

• Verwenden Sie verification-loop nach der Wiederherstellung, wenn Code geändert wurde.
• Verwenden Sie continuous-learning-v2, wenn das Fehlermuster es wert ist, zu einer Intuition oder einem späteren Skill zu werden.
• Verwenden Sie council, wenn es sich nicht um einen technischen Fehler, sondern um Entscheidungsambiguität handelt.
• Verwenden Sie workspace-surface-audit, wenn der Fehler durch widersprüchlichen lokalen Zustand oder Repository-Drift verursacht wurde.

Ausgabestandard

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

Geben Sie immer an:

• das Fehlermuster
• die Ursachenhypothese
• die Wiederherstellungsaktion
• den Beweis, dass die Situation jetzt besser oder immer noch blockiert ist