---
name: reflectAgentError
description: Agent-Selbstreflexions-Coach. Aktivieren wenn ein Agent einen Error / Tool-Failure / Exit-Code-Knall trifft. Klassifiziert in 3 Schritten (NORMAL/VERMEIDBAR/TECHNISCH) + ggf. Doku-Eintrag am richtigen Ort. Trigger: "Error reflexion", "warum ist das gescheitert", "Exit-Code", "Tool-Error", "Permission-Denied", "InputValidationError", "fail", "reflectError", "reflectAgentError". Implizit aktiv bei JEDEM Sub-Agent-Spawn (siehe CLAUDE.md "Error-Reflexions-Pflicht").
---

# Skill: reflectAgentError — Agent-Selbstreflexion auf Errors

> **Zweck:** Wenn ein Agent einen Error trifft, soll er kurz reflektieren statt blind weitermachen oder panisch abbrechen. Drei Schritte, max 30-60 Sekunden, intelligent geprompted. Vermeidbares wird dokumentiert — am richtigen Ort, nicht ueberall gleichzeitig.

## Wann aktivieren

**Explizite Trigger (im User- oder Agent-Prompt):**
- "Error reflexion", "reflectError", "reflectAgentError"
- "warum ist das gescheitert"
- "Exit-Code != 0", "Tool-Error", "InputValidationError"
- "Permission-Denied", "Access-Denied"
- "Build failed", "Test failed", "Deploy failed"

**Implizite Trigger:**
- JEDER Agent der einen Tool-Call mit Exit-Code != 0 ODER ToolResult-Error sieht
- JEDER Sub-Agent erbt die Pflicht via Sub-Prompt ("Aktiviere bei Errors Skill reflectAgentError")
- Bei Tool-Failure-Patterns (Permission, FileNotFound, BashTimeout, SyntaxError)

**Nicht aktivieren:**
- Bei Tool-Calls die per Design "leerer Output" zurueckgeben (z.B. `grep` mit 0 Treffern → Exit 1 = NORMAL)
- Wenn Agent eine User-Frage beantwortet und kein Error vorliegt
- Bei reiner Status-Frage ("ist X live?") — `reflectAgentError` ist fuer Errors, nicht fuer Diagnose

## Was dieser Skill bewirkt

3-Schritt-Heuristik (Latenz-Budget: 30s NORMAL / 60s VERMEIDBAR / 120s TECHNISCH):

### Schritt 1 — Klassifizieren (max 30s, max 80 Token Output)

| Klasse | Kriterium | Beispiele |
|--------|-----------|-----------|
| **NORMAL** | Tool tut was es soll, Bedingung nicht erfuellt. KEIN Bug, KEIN Wissens-Defizit. | `grep "xyz" file` → 0 Treffer (Exit 1). `ls dir/` wo Verzeichnis leer (Exit 0 aber leer). `test -f X` → Exit 1 wenn X fehlt (geplante Pruefung). |
| **VERMEIDBAR** | Agent haette mit besserem Wissen anders geprompt/geworkflow't. Kein Code-Bug, eine **Wissens-Luecke**. | `ls _runbooks/ 2>nul` in Bash (CMD-Syntax statt `/dev/null`). Compound-Chain `A && B || C` wo Exit-Code des letzten Befehls durchschlaegt. `Edit`-Tool ohne vorheriges `Read`. `git push` ohne `pull --rebase`. |
| **TECHNISCH** | Echter Bug / Server-Outage / Tool-Permission-Fehler / Cred-Leak / Race-Condition / Infrastruktur-Defekt. | `psql: connection refused` (DB down). `npm: ENOENT` mit korrupten node_modules. `Permission denied` weil Token rotiert. `SegFault`. `Hook failed`. |

**Output von Schritt 1:** EINE Zeile, max 80 Token. Format:
`Klasse: [NORMAL|VERMEIDBAR|TECHNISCH] — [Befehl-Pattern in 5 Worten] — [Lesson in 1 Satz oder "kein Lerntoutput"]`

### Schritt 2 — Abwaegen (max 20s, max 50 Token Output)

| Klasse | Doku-Entscheidung |
|--------|-------------------|
| **NORMAL** | Fast immer NEIN. Kein Doku-Eintrag. Weitermachen mit Folge-Aufgabe. |
| **VERMEIDBAR** | Fast immer JA. 1 Eintrag, 1 Ort, 1 Satz. |
| **TECHNISCH** | JA wenn Fix bekannt. NEIN wenn unklar — stattdessen Bericht/Issue an Architekt ("BLOCKED weil X"). |

**Wenn Doku-Entscheidung NEIN → Skill ist hier zu Ende.** Aufgabe wieder aufnehmen.

### Schritt 3 — Ablegen (max 60s, 1 Tool-Call)

Wenn Schritt 2 "JA" sagt, am richtigen Ort ablegen. Entscheidungstabelle:

| Lesson-Typ | Ablage |
|------------|--------|
| Workflow-Schritt war falsch (z.B. push ohne pull) | passendes Runbook `## Learnings`-Sektion (oder `## Run-Log` mit `FIX`-Outcome) |
| Skill-Sub-Prompt war unzureichend | passender Skill `learnings.md` |
| Tool-Syntax-Falle (Plattform/Shell) | `_runbooks/<passend>.md` `## Learnings` ODER `~/.claude/skills/reflectAgentError/learnings.md` als sammelnde Liste |
| Hard-Rule fehlt | CLAUDE.md (NUR mit Lead-Approval — Sub-Agent darf nicht eigenmaechtig editieren — schreibt stattdessen in seinen Welle-Bericht "Empfehlung CLAUDE.md-Eintrag X") |
| User-Profil / nicht-offensichtlicher Fakt | Memory `feedback_*.md` oder `user_*.md` + MEMORY.md-Index |
| Konkrete Befehl-Falle, einmaliger Befund | Runbook `## Run-Log`-Spalte `FIX` + 1-Zeilen-Notiz |

**Format des Eintrags (Pflicht-Schema, ASCII fuer interne Doku):**
```
[YYYY-MM-DD] [Agent/Welle] [NORMAL|VERMEIDBAR|TECHNISCH] [Befehl-Pattern in 5 Worten] -> [Lesson in 1 Satz]
```

Beispiele:
```
[2026-05-13] Sub-Orchestrator E-REFLECT VERMEIDBAR ls 2>nul in Bash -> Bash braucht 2>/dev/null, CMD nicht
[2026-05-13] W-S7-Worker VERMEIDBAR Compound-Chain ohne || true Tail -> letzter Exit-Code schlaegt durch, append || true
[2026-05-13] W-A4-Worker TECHNISCH psql connection refused -> Server-Reboot noetig, Bericht an Architekt
```

## Step-by-Step (Aktivierung im Agent)

1. Agent trifft Error (Exit-Code != 0, Tool-Failure, etc.)
2. Agent invokes mentale 3-Schritt-Heuristik (siehe oben)
3. Bei VERMEIDBAR oder TECHNISCH-mit-Fix: 1 Edit/Write-Tool-Call an Doku-Ort
4. **Folge-Aufgabe wieder aufnehmen** — Reflexion ist KEIN Stop-Punkt, sondern eine 30-60s-Inline-Aktion
5. Wenn TECHNISCH-ohne-Fix: Bericht "BLOCKED weil X, naechster Schritt Y" + weiter mit Rest der Aufgabe oder Stop

## Doktrin

- **Reflexion ist nie blockierend.** Sie ist eine Inline-Aktion zwischen Tool-Calls, nicht ein eigener Loop.
- **Kein Doku-Spam bei NORMAL.** Faustregel: wenn jeder gleiche Tool-Call denselben Output haette → NORMAL → kein Eintrag.
- **1 Eintrag, 1 Ort.** Nicht in 3 Runbooks + Memory + CLAUDE.md gleichzeitig. Single-Source-of-Truth.
- **Latenz-Budget einhalten.** Bei NORMAL: 0 Tool-Calls. VERMEIDBAR: 1. TECHNISCH-mit-Fix: max 2. Bei mehr → Bericht statt Doku.
- **Lesson muss actionable sein.** Kein "achte besser auf X" → stattdessen "bei Pattern Y nutze Z statt W".
- **Sub-Agent-Vererbung:** Pflicht-Prefix in Spawn-Prompts: "Bei Errors: aktiviere Skill reflectAgentError fuer 3-Schritt-Klassifikation."

## Anti-Patterns

- **Lange Romane schreiben:** Max 1 Absatz Reflexion, nicht 5.
- **Bei NORMAL trotzdem dokumentieren:** Spam. NORMAL = weitermachen.
- **User-Chat-Notification ohne Doku-Eintrag:** Verpufft. Wenn die Lesson wertvoll ist, ablegen.
- **Reflexion blockierend ausfuehren:** Agent darf nicht in Reflexions-Loop haengen. Inline, dann weiter.
- **CLAUDE.md-Edit ohne Lead-Approval:** Sub-Agents schreiben Empfehlungen in ihren Welle-Bericht — der Lead entscheidet ob CLAUDE.md geaendert wird.
- **Multi-Ort-Duplikation:** Wenn Lesson in Runbook X und Skill Y und Memory Z gleichzeitig landet, geht eine Stelle veraltet. EIN Ort, klar gewaehlt.
- **Generische "fix Code"-Lesson:** "Bug fixen" hilft nicht. Konkrete Pattern-Lesson hilft.

## Boundaries

- **Reflexion ist KEIN Excuse fuers Aufgeben.** Reflektieren → loggen → Aufgabe weitermachen.
- **Reflexion ist KEIN Debugger.** Bei tiefem TECHNISCH-Bug: kurz klassifizieren, dann normale Debug-Pipeline.
- **Sub-Agent darf KEINE Lead-Entscheidungen treffen.** CLAUDE.md-Aenderungen, Memory-Konsolidierung, Skill-Architektur — Empfehlung an Lead, nicht Selbst-Edit.

## Latenz-Doktrin

- **Klassifikation < 30s LLM-Time.** Wenn du laenger brauchst um NORMAL/VERMEIDBAR zu unterscheiden, ist es wahrscheinlich VERMEIDBAR (Bauchgefuehl).
- **Bei klar NORMAL: 0 Tool-Calls.** Inline-Gedanke, weiter.
- **Bei VERMEIDBAR: 1 Tool-Call (Write/Edit).**
- **Bei TECHNISCH-mit-Fix: max 2 Tool-Calls.**
- **Mehr als 2 Tool-Calls → der Error ist nicht reflektions-tauglich**, sondern Diagnose-tauglich. Skill verlassen, normale Debug-Pipeline.

## Voraussetzungen

- Agent hat soeben einen Error / Exit-Code != 0 / Tool-Failure begegnet
- Working Directory bekannt
- Doku-Ziel (Runbook / Memory / Skill) zugreifbar

## Pflege

Dieser Skill ist **lebendig**. Bei jedem nicht-trivialen Error-Reflexions-Run:
1. Eintrag in `learnings.md` (max 5 Run-History-Eintraege, FIFO)
2. `last-output.md` ueberschreiben mit aktuellem Beispiel
3. Bei neuem Pattern: ggf. eine Beispiel-Zeile in der NORMAL/VERMEIDBAR/TECHNISCH-Tabelle ergaenzen
4. Bei Major-Update: Eval-Run-Eintrag

## Chained Skills

- **Upstream Caller:** Jeder Agent (via implizite CLAUDE.md-Doktrin oder explizit) — siehe `context/handoff.md`
- **Downstream:** `cleanup-after-welle` konsolidiert am Welle-Ende ggf. Reflexions-Lessons in Runbook-`## Learnings`
- **Parallel:** `thinkLikeUser` — die Reflexion folgt User-Persona-Default (sofort handeln statt fragen)