systematic-debugging

name	systematic-debugging
description	Strukturiertes Debugging mit Root-Cause-Analyse statt Trial-and-Error. Folgt einem systematischen Prozess um Fehlerursachen zu finden und zu beheben. Trigger: "debug", "systematisch debuggen", "root cause", "fehler finden", "bug analysieren", "systematic debugging", "why is this failing"
version	0.1.0

Systematic Debugging — Strukturiertes Fehlersuchen

Strukturierter Debugging-Prozess der Root-Cause-Analyse statt Trial-and-Error verfolgt. Ziel: Die eigentliche Ursache finden und beheben, nicht nur Symptome behandeln.

1. Grundprinzip

Niemals raten. Immer verstehen.

Symptom beobachten
    ↓
Hypothese bilden
    ↓
Hypothese testen (mit minimalem Experiment)
    ↓
Ursache verstehen
    ↓
Fix implementieren
    ↓
Verifizieren (Test schreiben)

2. Debugging-Prozess

2.1 Symptom praezise beschreiben

Bevor du irgendetwas tust, beschreibe das Problem exakt:

• Was: Was passiert? Was sollte stattdessen passieren?
• Wo: Welches Package? Welche Datei? Welche Funktion?
• Wann: Immer? Nur unter bestimmten Bedingungen? Seit wann?
• Fehlermeldung: Exakter Text, Stack Trace

2.2 Reproduzieren

Stelle sicher dass du den Fehler reproduzieren kannst:

cd xhubioTable/<package>
npx vitest run tests/<test>.test.ts
# oder
npm run build
# oder
npm run test

Wenn du den Fehler nicht reproduzieren kannst:

• Sind die Voraussetzungen korrekt? (Dependencies installiert, etc.)
• Ist es ein Flaky Test? (Mehrfach ausfuehren)
• Ist es umgebungsabhaengig?

2.3 Hypothesen bilden

Liste moegliche Ursachen auf:

#	Hypothese	Wahrscheinlichkeit	Wie testen
1	...	Hoch/Mittel/Niedrig	...
2	...	Hoch/Mittel/Niedrig	...
3	...	Hoch/Mittel/Niedrig	...

Beginne mit der wahrscheinlichsten Hypothese.

2.4 Hypothese testen

Teste die Hypothese mit dem kleinsten moeglichen Experiment:

• Einen Log-Output einfuegen
• Einen Breakpoint setzen
• Einen Wert in der Test-Fixture aendern
• Eine Bedingung invertieren

NICHT: Einfach Code aendern und hoffen dass es hilft.

2.5 Root Cause identifizieren

Wenn die Hypothese bestaetigt wird:

• Warum tritt diese Ursache auf?
• Ist es ein Code-Fehler, ein Design-Fehler, oder ein Verstaendnis-Fehler?
• Gibt es weitere Stellen im Code die denselben Fehler haben?

Fuer detaillierte Root-Cause-Analyse: Siehe root-cause-tracing.md

2.6 Fix implementieren

Der Fix soll:

• Die Ursache beheben, nicht das Symptom
• Minimal sein (keine unnoetige Aenderungen)
• Durch einen Test abgesichert sein

1. Test schreiben der den Bug reproduziert (Red)
2. Fix implementieren (Green)
3. Alle existierenden Tests ausfuehren (keine Regression)

2.7 Verifizieren

cd xhubioTable/<package>
npm run test

Alle Tests gruen? Gut. Bug ist gefixt.

3. Haeufige Fehlerquellen in diesem Projekt

Bereich	Typische Ursache	Wo suchen
TypeScript-Fehler	Interface-Aenderung nicht propagiert	Package-Abhaengigkeiten pruefen
Build-Fehler	Fehlende Dependency	package.json, npm install
Import-Fehler	Falscher Pfad oder fehlendes Export	src/index.ts (Exports), tsconfig.json
Test-Fehler	Fixture veraltet oder falscher Mock	tests/fixtures/, Test-Setup
Runtime-Fehler	Null/Undefined nicht behandelt	TypeScript strict pruefen
XLSX-Parser-Fehler	Spalten/Zeilen-Index falsch	Importer und Parser pruefen

4. Debugging-Tools

4.1 TypeScript Compiler

npx tsc --noEmit  # Nur Type-Checking, kein Output

4.2 Vitest im Watch-Modus

npx vitest watch tests/<test>.test.ts  # Automatisch bei Aenderungen

4.3 Vitest mit Logging

npx vitest run tests/<test>.test.ts --reporter=verbose

4.4 Node Debugger

npm run debug  # Build mit sourcemaps + jest/vitest mit --inspect-brk

5. Eskalation

Wenn du nach 3 Hypothesen-Zyklen die Ursache nicht gefunden hast:

1. Zusammenfassen: Was weisst du? Was hast du versucht?
2. User einbeziehen: Beschreibe das Problem und bitte um Input
3. Scope erweitern: Vielleicht liegt die Ursache in einem anderen Package
4. Defense-in-Depth pruefen: Siehe defense-in-depth.md

6. Anti-Patterns beim Debugging

• Shotgun Debugging: Vieles gleichzeitig aendern und hoffen
• Symptom-Behandlung: Fehlermeldung unterdruecken statt Ursache fixen
• Copy-Paste-Fix: StackOverflow-Loesung einfuegen ohne zu verstehen
• Grosse Aenderungen: Halben Code umschreiben statt den Bug zu finden
• Blame Game: "Das Package ist kaputt" statt die Ursache im eigenen Code zu suchen

7. Regeln

• Hypothese vor Aenderung: Immer erst verstehen, dann aendern
• Ein Fix pro Bug: Nicht mehrere Bugs gleichzeitig fixen
• Test fuer jeden Fix: Jeder Bug-Fix bekommt einen Regressionstest
• Aufschreiben: Bei komplexen Bugs die Analyse dokumentieren
• Monorepo-Kontext: Fehler koennen in anderen Packages verursacht werden