Systematische Fehlersuche

Überblick

Zufällige Korrekturen verschwenden Zeit und verursachen neue Fehler. Schnellreparaturen verschleiern die zugrunde liegenden Probleme.

Grundprinzip: Finden Sie IMMER die Ursache, bevor Sie Korrekturen vornehmen. Die Behebung von Symptomen ist zum Scheitern verurteilt.

Wer den Wortlaut dieses Prozesses missachtet, verstößt gegen den Geist der Fehlerbehebung.

Das eiserne Gesetz

KEINE BEHEBUNGEN OHNE VORHERIGE UNTERSUCHUNG DER URSACHE

Wenn Sie Phase 1 nicht abgeschlossen haben, dürfen Sie keine Korrekturen vorschlagen.

Anwendungsbereich

Bei JEDEM technischen Problem anwenden:

• Testfehler
• Fehler in der Produktion
• Unerwartetes Verhalten
• Leistungsprobleme
• Fehler beim Build
• Integrationsprobleme

Verwenden Sie dies INSBESONDERE, wenn:

• Sie unter Zeitdruck stehen (in Notfällen ist es verlockend, einfach zu raten)
• „Nur eine schnelle Lösung“ scheint naheliegend
• Sie bereits mehrere Lösungen ausprobiert haben
• Die vorherige Lösung hat nicht funktioniert
• Sie das Problem nicht vollständig verstehen

Überspringe diesen Schritt nicht, wenn:

• das Problem einfach erscheint (auch einfache Fehler haben Ursachen)
• Sie es eilig haben (Eile garantiert Nacharbeit)
• Der Vorgesetzte will, dass es JETZT behoben wird (systematisches Vorgehen ist schneller als wildes Herumprobieren)

Die vier Phasen

Sie MÜSSEN jede Phase abschließen, bevor Sie zur nächsten übergehen.

Phase 1: Untersuchung der Grundursache

BEVOR du IRGENDEINE Korrekturmaßnahme versuchst:

1. Lesen Sie die Fehlermeldungen sorgfältig durch

   • Überspringen Sie keine Fehler oder Warnungen
   • Sie enthalten oft die genaue Lösung
   • Lesen Sie die Stack-Traces vollständig durch
   • Notieren Sie sich Zeilennummern, Dateipfade und Fehlercodes

2. Reproduzieren Sie den Fehler konsistent

   • Können Sie den Fehler zuverlässig auslösen?
   • Was sind die genauen Schritte?
   • Tritt der Fehler jedes Mal auf?
   • Wenn nicht reproduzierbar → sammeln Sie weitere Daten, raten Sie nicht

3. Überprüfe die letzten Änderungen

   • Was hat sich geändert, das dies verursachen könnte?
   • Git-Diff, aktuelle Commits
   • Neue Abhängigkeiten, Konfigurationsänderungen
   • Unterschiede in der Umgebung

4. Beweismaterial in Systemen mit mehreren Komponenten sammeln

   WENN das System aus mehreren Komponenten besteht (CI → Build → Signierung, API → Dienst → Datenbank):

   Bevor Sie Korrekturen vorschlagen, fügen Sie Diagnoseinstrumente hinzu:

   Für JEDE Komponentengrenze:
     - Protokollieren Sie, welche Daten in die Komponente eingehen
     - Protokollieren Sie, welche Daten die Komponente verlassen
     - Überprüfen Sie die Weitergabe von Umgebungs- und Konfigurationsdaten
     - Überprüfen Sie den Zustand auf jeder Ebene
   
   Führen Sie dies einmal aus, um Nachweise darüber zu sammeln, WO der Fehler auftritt
   DANN analysieren Sie die Nachweise, um die fehlerhafte Komponente zu identifizieren
   DANN untersuchen Sie diese spezifische Komponente
   

   Beispiel (mehrschichtiges System):

   # Ebene 1: Workflow
   echo "=== Im Workflow verfügbare Geheimnisse: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Ebene 2: Build-Skript
   echo "=== Umgebungsvariablen im Build-Skript: ==="
   env | grep IDENTITY || echo "IDENTITY nicht in der Umgebung"
   
   # Ebene 3: Signierungsskript
   echo "=== Status des Schlüsselbunds: ==="
   security list-keychains
   security find-identity -v
   
   # Ebene 4: Tatsächliche Signierung
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   Dies zeigt: Welche Ebene versagt (Geheimnisse → Workflow ✓, Workflow → Build ✗)

5. Datenfluss nachverfolgen

   WENN der Fehler tief in der Aufrufstapel liegt:

   Siehe „root-cause-tracing.md“ in diesem Verzeichnis für die vollständige Technik der Rückverfolgung.

   Kurzfassung:

   • Woher stammt der fehlerhafte Wert?
   • Was hat dies mit dem fehlerhaften Wert aufgerufen?
   • Verfolgen Sie die Kette weiter nach oben, bis Sie die Quelle gefunden haben
   • Beheben Sie das Problem an der Quelle, nicht am Symptom

Phase 2: Musteranalyse

Finden Sie das Muster, bevor Sie das Problem beheben:

1. Finde funktionierende Beispiele

   • Suchen Sie ähnlichen, funktionierenden Code in derselben Codebasis
   • Was funktioniert, das dem defekten Code ähnelt?

2. Mit Referenzen vergleichen

   • Wenn Sie ein Muster implementieren, lesen Sie die Referenzimplementierung GRÜNDLICH durch
   • Nicht nur überfliegen – jede Zeile lesen
   • Verstehen Sie das Muster vollständig, bevor Sie es anwenden

3. Identifizieren Sie Unterschiede

   • Was ist der Unterschied zwischen einer funktionierenden und einer fehlerhaften Lösung?
   • Listen Sie jeden Unterschied auf, egal wie klein er auch sein mag
   • Gehen Sie nicht davon aus, dass „das keine Rolle spielen kann“

4. Verstehen Sie die Abhängigkeiten

   • Welche anderen Komponenten werden dafür benötigt?
   • Welche Einstellungen, Konfigurationen, Umgebungen?
   • Von welchen Voraussetzungen geht es aus?

Phase 3: Hypothese und Testen

Wissenschaftliche Methode:

1. Eine einzige Hypothese aufstellen

   • Klar formulieren: „Ich glaube, X ist die Ursache, weil Y“
   • Schreibe sie auf
   • Sei konkret, nicht vage

2. Minimal testen

   • Nehmen Sie die MÖGLICHST KLEINE Änderung vor, um die Hypothese zu testen
   • Jedes Mal nur eine Variable
   • Korrigieren Sie nicht mehrere Dinge gleichzeitig

3. Überprüfen Sie das Ergebnis, bevor Sie fortfahren

   • Hat es funktioniert? Ja → Phase 4
   • Hat es nicht funktioniert? Formuliere eine NEUE Hypothese
   • Füge KEINE weiteren Korrekturen hinzu

4. Wenn du es nicht weißt

   • Sagen Sie: „Ich verstehe X nicht“
   • Tu nicht so, als wüsstest du es
   • Bitte um Hilfe
   • Recherchiere weiter

Phase 4: Umsetzung

Behebe die Ursache, nicht das Symptom:

1. Erstellen Sie einen fehlgeschlagenen Testfall

   • Möglichst einfache Reproduktion
   • Wenn möglich, automatisierten Test
   • Einmaliges Testskript, falls kein Framework vorhanden ist
   • MUSS vor der Behebung vorhanden sein
   • Nutzen Sie die Superkraft: „testgetriebene Entwicklung “, um korrekte fehlgeschlagene Tests zu schreiben

2. Einzelne Korrektur implementieren

   • Beheben Sie die identifizierte Grundursache
   • JEDES Mal nur EINE Änderung
   • Keine Verbesserungen nach dem Motto „Wenn ich schon mal dabei bin“
   • Keine gebündelten Refactorings

3. Korrektur überprüfen

   • Wird der Test jetzt bestanden?
   • Sind keine anderen Tests fehlgeschlagen?
   • Ist das Problem tatsächlich behoben?

4. Wenn die Korrektur nicht funktioniert

   • STOP
   • Zählung: Wie viele Korrekturversuche haben Sie bereits unternommen?
   • Wenn < 3: Zurück zu Phase 1, erneute Analyse mit neuen Informationen
   • Wenn ≥ 3: STOP und hinterfrage die Architektur (Schritt 5 unten)
   • Versuchen Sie nicht, Lösung Nr. 4 ohne architektonische Diskussion anzuwenden

5. Wenn 3 oder mehr Korrekturmaßnahmen fehlgeschlagen sind: Hinterfragen Sie die Architektur

   Muster, das auf ein Architekturproblem hindeutet:

   • Jede Korrektur deckt an anderer Stelle einen neuen gemeinsamen Zustand, eine neue Kopplung oder ein neues Problem auf
   • Die Korrekturen erfordern eine „umfassende Refaktorisierung“, um sie umzusetzen
   • Jede Korrektur verursacht an anderer Stelle neue Symptome

   HALTEN Sie inne und hinterfragen Sie die Grundlagen:

   • Ist dieses Muster grundsätzlich solide?
   • Halten wir „nur aus reiner Trägheit daran fest“?
   • Sollten wir die Architektur umgestalten oder weiterhin nur Symptome beheben?

   Besprechen Sie dies mit Ihrem menschlichen Partner, bevor Sie weitere Korrekturen vornehmen

   Dies ist KEINE gescheiterte Hypothese – dies ist eine falsche Architektur.

Warnsignale – STOPP und befolge den Prozess

Wenn Sie sich dabei ertappen, zu denken:

• „Erst mal eine schnelle Lösung, später untersuchen“
• „Probier einfach mal, X zu ändern, und schau, ob es funktioniert“
• „Füge mehrere Änderungen hinzu und führe Tests durch“
• „Den Test überspringen, ich überprüfe das manuell“
• „Es ist wahrscheinlich X, das werde ich beheben“
• „Ich verstehe es nicht ganz, aber das könnte funktionieren“
• „Das Muster sieht X vor, aber ich werde es anders anpassen.“
• „Hier sind die Hauptprobleme: [listet Lösungen auf, ohne sie zu untersuchen]“
• Lösungsvorschläge, bevor der Datenfluss nachverfolgt wurde
• „Noch ein weiterer Korrekturversuch“ (obwohl bereits 2+ versucht wurden)
• Jede Korrektur deckt an anderer Stelle ein neues Problem auf

ALL dies bedeutet: STOP. Zurück zu Phase 1.

Wenn drei oder mehr Korrekturversuche fehlgeschlagen sind: Hinterfrage die Architektur (siehe Phase 4.5)

Signale Ihres menschlichen Partners, dass Sie es falsch machen

Achte auf diese Umlenkungen:

• „Passiert das nicht?“ – Du hast eine Annahme getroffen, ohne sie zu überprüfen
• „Wird uns das zeigen …?“ – Du hättest weitere Beweise sammeln sollen
• „Hör auf zu raten“ – Du schlägst Lösungen vor, ohne die Situation zu verstehen
• „Denk mal ganz gründlich darüber nach“ – Hinterfrage die Grundlagen, nicht nur die Symptome
• „Wir kommen nicht weiter?“ (frustriert) – Dein Ansatz funktioniert nicht

Wenn du diese Aussagen hörst: HÖR AUF. Kehre zu Phase 1 zurück.

Häufige Rationalisierungen

Kurzanleitung

Wenn der Prozess „keine Grundursache“ ergibt

Wenn eine systematische Untersuchung ergibt, dass das Problem tatsächlich umgebungsbedingt, zeitabhängig oder extern ist:

1. Haben Sie den Prozess abgeschlossen
2. Dokumentieren Sie Ihre Untersuchungsergebnisse
3. Implementieren Sie geeignete Maßnahmen (Wiederholversuch, Timeout, Fehlermeldung)
4. Fügen Sie Überwachungs- und Protokollierungsmaßnahmen für zukünftige Untersuchungen hinzu

Aber: 95 % der Fälle, in denen „keine Ursache“ festgestellt wird, sind auf unvollständige Untersuchungen zurückzuführen.

Unterstützende Techniken

Diese Techniken sind Teil der systematischen Fehlersuche und in diesem Verzeichnis verfügbar:

• root-cause-tracing.md – Verfolgen Sie Fehler rückwärts über den Aufrufstapel, um den ursprünglichen Auslöser zu finden
• defense-in-depth.md – Fügen Sie nach dem Auffinden der Grundursache Validierungen auf mehreren Ebenen hinzu
• condition-based-waiting.md – Beliebige Timeouts durch bedingte Abfragen ersetzen

Verwandte Fähigkeiten:

• superpowers:test-driven-development – Zum Erstellen eines fehlgeschlagenen Testfalls (Phase 4, Schritt 1)
• superpowers:verification-before-completion – Vor der Erfolgsmeldung überprüfen, ob die Korrektur funktioniert hat

Auswirkungen in der Praxis

Aus Debugging-Sitzungen:

• Systematischer Ansatz: 15–30 Minuten bis zur Behebung
• Zufälliger Ansatz bei der Fehlerbehebung: 2–3 Stunden mühsames Herumprobieren
• Erfolgsquote beim ersten Versuch: 95 % gegenüber 40 %
• Neu entstandene Fehler: Nahezu null gegenüber häufig