---
name: fehler-diagnostizieren
description: Diagnostiziert Bugs, fehlschlagende Tests, falsche Ergebnisse und Performance-Regressionen durch Reproduktion, Minimierung, falsifizierbare Hypothesen und gezielte Messung. Verwenden, wenn etwas kaputt, unerwartet, instabil oder langsam ist und die Ursache noch nicht belastbar feststeht.
---

# Fehler diagnostizieren

Finde zuerst die Ursache. Ändere nicht auf Verdacht mehrere Stellen und erkläre
ein verschwundenes Symptom nicht vorschnell zum Fix.

## Fachliche Grundlage

Die offizielle [Git-Bisect-Dokumentation](https://git-scm.com/docs/git-bisect)
beschreibt die systematische Eingrenzung einer Regression zwischen einem guten
und einem fehlerhaften Zustand. Dieselbe Idee gilt auch für Eingaben,
Konfigurationen und Systemgrenzen.

## Ablauf

1. Halte erwartetes und tatsächliches Verhalten, Umgebung, Zeitpunkt und
   Auswirkungen fest. Schütze personenbezogene Daten und Secrets in Logs.
2. Baue die engste ausführbare Feedbackschleife, die genau das Symptom erkennt:
   bevorzugt Test, reproduzierbarer API-Aufruf, kontrollierte Eingabe oder
   Browserablauf.
3. Führe sie aus und bestätige, dass sie aus dem richtigen Grund fehlschlägt.
   Bei sporadischen Fehlern erhöhe und messe zuerst die Reproduktionsrate.
4. Minimiere Eingabe, Daten, Konfiguration und Schritte einzeln, solange das
   Symptom erhalten bleibt.
5. Formuliere zwei bis fünf priorisierte, falsifizierbare Hypothesen. Zu jeder
   Hypothese gehört eine erwartete Beobachtung.
6. Prüfe jeweils nur eine Hypothese mit der kleinsten nötigen Messung,
   Instrumentierung oder Zustandsänderung. Bei Performanceproblemen zuerst
   eine reproduzierbare Baseline messen.
7. Benenne Ursache, auslösende Bedingung und begünstigende Faktoren getrennt.
   Wenn nur eine Diagnose verlangt wurde, implementiere keinen Fix.
8. Bei beauftragter Behebung: Überführe die minimale Reproduktion mit
   `testgetrieben-entwickeln` in einen Regressionstest, implementiere den
   kleinsten Fix und prüfe auch das ursprüngliche Szenario.
9. Entferne temporäre Instrumentierung und sensible Diagnosedaten. Halte kurz
   fest, was den Fehler künftig verhindert oder früher sichtbar macht.

## Grenzen

- Keine produktive Instrumentierung, Datenkopie oder externe Änderung ohne
  ausdrückliche Freigabe.
- Keine Hypothese als Ursache ausgeben, solange ihre Vorhersage nicht geprüft
  wurde.
- Wenn keine belastbare Reproduktion möglich ist, benenne die versuchten Wege
  und bitte gezielt um fehlende Logs, Eingaben oder Umgebungszugriffe.

## Fertig, wenn

- das Symptom reproduzierbar und möglichst minimiert ist.
- die Ursache durch Beobachtung statt Vermutung belegt ist.
- Diagnoseartefakte keine unnötigen sensiblen Daten enthalten.
- bei einer Behebung Regressionstest und ursprüngliches Szenario erfolgreich
  geprüft wurden.