systematic-debugging

Überblick

Was ist systematic-debugging?

Das systematic-debugging Skill ist ein strukturierter Prozess in vier Phasen zum Debuggen beliebiger technischer Probleme: Testfehler, Produktions-Bugs, flaky Tests, Performance-Probleme, Build-Fehler oder Integrationsfehler.

Statt "einen schnellen Fix" zu versuchen oder sofort an der ersten Fehlerzeile Code zu ändern, zwingt dich dieses Skill dazu, zuerst die eigentliche Ursache zu untersuchen und dann einen langlebigen Fix zu entwerfen und zu validieren. Es basiert auf praxiserprobten Patterns und Skripten aus einem realen Codebase, darunter TypeScript-Helfer für condition-based waiting sowie ein Bash-Skript zum Auffinden von Test-Pollutern.

Grundprinzip und Iron Law

Das Herz von systematic-debugging ist einfach:

• Grundprinzip: Finde immer zuerst die Root Cause, bevor du Fixes versuchst. Fixes, die nur Symptome adressieren, gelten als Fehlschläge.

• The Iron Law:

  NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
  

Wenn die Investigationsphase nicht abgeschlossen ist, schlägst du keine Fixes vor und setzt keine um. Das ist bewusst so gestaltet, dass es Zeitdruck, Ratespiele und "nur dieses eine Mal"-Rationalisierungen standhält.

Für wen ist dieses Skill gedacht?

systematic-debugging richtet sich an:

• Entwickler:innen, die in JavaScript/TypeScript-Projekten arbeiten und verlässliche, reproduzierbare Fixes wollen
• Test- und QA-Engineers, die mit flakigem Verhalten, zufälligen Timeouts und verschmutztem Test-State zu kämpfen haben
• CI/CD- und Tooling-Engineers, die intermittierende Build- oder Integrationsfehler diagnostizieren
• Tech Leads und Reviewer, die einen gemeinsamen, rigorosen Prozess für Debugging-Arbeit etablieren möchten

Am besten passt es, wenn dir hochwertige Root-Cause-Analyse wichtiger ist als das schnelle Pflastern von Symptomen.

Welche Probleme löst es?

Nutze das systematic-debugging Skill, wenn du:

• Testfehler untersuchen musst, die nach "Fixes" immer wieder auftauchen
• Flaky Tests aufspüren willst, die von beliebigen Timeouts oder Race Conditions abhängen
• Unerwartetes Verhalten verstehen möchtest, statt Fehler nur zu unterdrücken
• Performance-Probleme oder langsame, timing-sensitive Abläufe diagnostizieren musst
• Build- oder Integrationsfehler debuggen willst, die nur in CI oder unter Last auftreten
• Herausfinden möchtest, welcher Test den State verschmutzt oder unerwünschte Dateien/Verzeichnisse hinterlässt

Das Repository enthält außerdem:

• condition-based-waiting.md und condition-based-waiting-example.ts, um setTimeout/sleep in TypeScript-Tests durch robustes condition-based waiting zu ersetzen
• defense-in-depth.md für Validierung auf mehreren Ebenen, sodass bestimmte Bug-Klassen strukturell unmöglich werden
• find-polluter.sh, ein Bash-Helfer, um genau den Test zu finden, der unerwünschte Dateien oder State erzeugt
• root-cause-tracing.md, um Fehler entlang der Call Chain bis zur wahren Ursache zurückzuverfolgen

Wann ist systematic-debugging sinnvoll?

systematic-debugging ist besonders geeignet, wenn:

• Du unter Zeitdruck stehst und in Versuchung bist, Fixes zu raten
• Ein Problem immer wieder auftritt, trotz mehrerer Fix-Versuche
• Du einen wiederholbaren Debugging-Workflow für dich oder dein Team willst
• Du eine flaky Test-Suite stabilisieren oder verschmutzte Test-Umgebungen aufräumen möchtest

Es ist weniger geeignet, wenn:

• Du nur einmalig schnell Code generieren oder refaktorisieren willst, ohne tiefergehende Untersuchung
• Du außerhalb der beschriebenen technischen Domänen debuggen musst (z. B. rein organisatorische Prozessprobleme)
• Du nicht bereit bist, einem schrittweisen Prozess zu folgen, und ad-hoc-Experimentieren bevorzugst

Wenn dein Ziel "schneller Patch jetzt, Rework später akzeptiert" ist, wird sich dieser Prozess streng anfühlen. Wenn dein Ziel "einmal richtig fixen" lautet, ist systematic-debugging für dich gemacht.

Verwendung

Installation und Setup

Um das systematic-debugging Skill in eine kompatible Agent- oder Tool-Umgebung zu installieren, nutze den bereitgestellten npx-Befehl:

npx skills add https://github.com/obra/superpowers --skill systematic-debugging
``

Dieser Befehl lädt die Skill-Definition sowie die zugehörigen Dokumente und Skripte aus dem `obra/superpowers` Repository unter `skills/systematic-debugging`.

Nach der Installation:

1. Öffne das `systematic-debugging` Skill in deinem Agent oder der Skills-UI.
2. Stelle sicher, dass dein Workspace Zugriff auf dein Projekt-Repository, Testbefehle und Logs hat.
3. Prüfe, ob du die mitgelieferten Markdown-Guides und Skripte sehen kannst:
   - `SKILL.md`
   - `condition-based-waiting.md`
   - `defense-in-depth.md`
   - `root-cause-tracing.md`
   - `find-polluter.sh`

### Wichtige Dateien und Komponenten
Für Installationsentscheidungen und den täglichen Einsatz sind diese Dateien am wichtigsten:

- **`SKILL.md`** – Beschreibt den vollständigen vierphasigen Systematic-Debugging-Prozess, Regeln und Anti-Patterns. Das ist der Kern des Skills.
- **`condition-based-waiting.md`** – Erklärt, wie du beliebige Timeouts in Tests durch condition-based waiting ersetzt.
- **`condition-based-waiting-example.ts`** – TypeScript-Utilities wie `waitForEvent`, die condition-based waiting gegen einen `ThreadManager` und Event-Typen implementieren.
- **`defense-in-depth.md`** – Zeigt, wie du mehrstufige Validierung (Entry Point, Business Logic, Environment Guards, Logging) anwendest, um ganze Bug-Kategorien unmöglich zu machen.
- **`find-polluter.sh`** – Ein Bash-Skript, das Tests iteriert, um herauszufinden, welche Datei einen bestimmten Pfad erzeugt (State-Pollution).
- **`root-cause-tracing.md`** – Führt durch das Zurückverfolgen eines Bugs von der Stack Trace bis zum ursprünglichen Auslöser und dem anschließenden Kombinieren mit Defense-in-Depth.
- **`CREATION-LOG.md`** – Ein Meta-Log, das erklärt, wie das Framework extrahiert und gehärtet wurde; hilfreich für das Verständnis der Designziele, weniger kritisch für die tägliche Nutzung.

Für **JavaScript/TypeScript**-Entwickler:innen lassen sich das TypeScript-Beispiel und das Bash-Skript häufig direkt ins eigene Projekt übernehmen.

### Den vierphasigen Workflow ausführen
Der `systematic-debugging` Prozess ist in vier verpflichtende Phasen gegliedert (in `SKILL.md` beschrieben). Du musst jede Phase abschließen, bevor du zur nächsten weitergehst.

#### Phase 1 – Root-Cause-Investigation
Bevor du Code, Konfiguration oder Tests anfasst:

- **Lies Fehlermeldungen und Logs sorgfältig.**
  - Überfliege keine Stack Traces oder Warnungen.
  - Halte Zeilennummern, Pfade und Error Codes fest.
- **Reproduziere das Problem konsistent.**
  - Etabliere einen minimalen, verlässlichen Reproduktionsbefehl.
  - Notiere, welche Eingaben und Umgebungsfaktoren nötig sind.

In dieser Phase schlägst du keine Fixes vor und implementierst auch keine. Das Ziel ist Verstehen: Was genau schlägt fehl, wo und unter welchen Bedingungen?

#### Phase 2 – Musteranalyse
Sobald die Reproduktion zuverlässig ist:

- Verändere jeweils nur einen Faktor (Inputs, Konfiguration, Umgebung), um zu sehen, was das Ergebnis beeinflusst.
- Suche nach Grenzen: Werten oder Bedingungen, bei denen das Verhalten von "passend" zu "fehlerhaft" kippt.
- Nutze Logs, Assertions oder temporäre Instrumentierung, um den fehlerhaften Pfad einzugrenzen.

Am Ende von Phase 2 solltest du die Struktur des Problems und die auslösenden Bedingungen verstanden haben – nicht nur die finale Fehlermeldung.

#### Phase 3 – Hypothese und Design
Jetzt kannst du eine Hypothese formulieren:

- Formuliere klar, was du für die Root Cause hältst (Datenfluss, fehlende Validierung, Timing-Problem, falscher Pfad usw.).
- Entwirf eine **einzelne, fokussierte** Änderung, die genau diese Ursache adressiert.
- Plane, wie du die Hypothese mit deinen Reproduktionsschritten validierst.

Wenn sich die Hypothese als falsch herausstellt, kehrst du zur Investigation/Analyse zurück, statt zusätzliche spekulative Fixes zu stapeln.

#### Phase 4 – Implementierung und Validierung
Erst mit einer klaren Hypothese änderst du Code oder Konfiguration:

- Nimm die kleinstmögliche Änderung vor, die direkt die Root Cause adressiert.
- Führe zunächst die minimale Reproduktion und anschließend die breitere Test-Suite aus.
- Nutze die Hinweise aus:
  - `defense-in-depth.md`, um Validierung auf mehreren Ebenen hinzuzufügen
  - `root-cause-tracing.md`, um sicherzugehen, dass du die tatsächliche Ursache fixst
- Stelle sicher, dass der Fix robust ist (z. B. unter Last, in CI und für in Phase 2 identifizierte Edge Cases).

Wenn der Fix sich nicht wie erwartet verhält, **stapelst** du keine weiteren Änderungen, sondern gehst in die vorherigen Phasen zurück.

### Debugging-Utilities im eigenen Projekt nutzen

#### Condition-based waiting für flaky Tests (JavaScript/TypeScript)
Flaky Tests, die auf `setTimeout` oder `sleep` basieren, brechen oft, wenn Maschinen langsamer, schneller oder unter Last laufen. `condition-based-waiting.md` und `condition-based-waiting-example.ts` zeigen ein besseres Muster: Warte auf die Bedingung, die dir wichtig ist.

Typische Migration:

```typescript
// ❌ Vorher: Timing raten
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();

// ✅ Nachher: auf Bedingung warten
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();

Die bereitgestellte condition-based-waiting-example.ts enthält Helfer wie:

export function waitForEvent(
  threadManager: ThreadManager,
  threadId: string,
  eventType: LaceEventType,
  timeoutMs = 5000
): Promise<LaceEvent> { /* ... */ }

Passe diese Patterns an deine eigene Test-Infrastruktur an:

1. Kopiere oder implementiere die Utilities in den Test-Helpers deines Projekts.
2. Ersetze beliebige setTimeout/sleep-Aufrufe durch condition-based waits.
3. Führe deine Test-Suite erneut aus, um die reduzierte Flakiness zu überprüfen.

Das unterstützt direkt das Ziel von systematic-debugging, Root Causes zu eliminieren, statt Timeouts zufällig zu verlängern.

Test-Pollution mit find-polluter.sh finden

Wenn deine Tests zusätzliche Dateien oder Verzeichnisse hinterlassen oder sonstigen State verschmutzen, hilft dir find-polluter.sh, den verantwortlichen Test zu finden.

Verwendung (aus dem Projekt-Root, Parameter nach Bedarf anpassen):

./find-polluter.sh <file_or_dir_to_check> <test_pattern>

# Beispiel
./find-polluter.sh '.git' 'src/**/*.test.ts'

Das Skript wird:

• Testdateien finden, die zum Pattern passen
• Sie nacheinander mit npm test <file> ausführen
• Nach jedem Lauf prüfen, ob die Ziel-Datei oder das Ziel-Verzeichnis jetzt existiert
• Anhalten und den ersten Test melden, der sie erzeugt hat – inklusive Kommandos, um diesen Test erneut auszuführen und zu inspizieren

Das passt in Phase 1 und Phase 2 von systematic-debugging, weil es eine verlässliche Möglichkeit bietet, State-Pollution zu reproduzieren und zu isolieren.

Defense-in-depth-Validierung anwenden

Wenn deine Investigation einen Bug offenlegt, der durch ungültige Daten oder Annahmen verursacht wurde, empfiehlt defense-in-depth.md, Validierung auf mehreren Ebenen zu platzieren:

• Entry Point Validation – Offensichtlich ungültige Eingaben an den Grenzen (APIs, CLI, UI-Handler) abweisen.
• Business-Logic-Validation – Sicherstellen, dass Daten für bestimmte Operationen sinnvoll sind.
• Environment Guards – Gefährliche Operationen in der falschen Umgebung oder mit falschem Pfad verhindern.
• Diagnostisches Logging – Nützlichen Kontext liefern, falls doch etwas durchrutscht.

Beispiel für die Validierung eines workingDirectory-Arguments:

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  if (!statSync(workingDirectory).isDirectory()) {
    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
  }
  // ... proceed
}

Nutze diese Patterns bei Fixes in Phase 4, um sicherzustellen, dass der Bug nicht leicht über einen anderen Codepfad wieder auftaucht.

Wann du dieses Skill nicht verwenden solltest

Es kann sinnvoll sein, systematic-debugging zu überspringen oder zu verschieben, wenn:

• Du nur prototypisierst und bewusst Wegwerf-Code und Bugs in Kauf nimmst
• Das Problem trivial und vollständig verstanden ist (z. B. ein bekannter Tippfehler, der direkt bei der Entwicklung auffällt) und den vollen Vier-Phasen-Aufwand nicht rechtfertigt
• Du nur einzelne Utilities (wie condition-based waits) brauchst und nicht den gesamten Prozess

Selbst in diesen Fällen ist die Iron Law ein hilfreicher Check: Wenn du merkst, dass du mehrere Rate-Fixes stapelst, ist es Zeit, auf systematic-debugging umzuschalten.

FAQ

Was ändert systematic-debugging konkret in meinem Workflow?

Statt direkt von einer Fehlermeldung zu Code-Edits zu springen, zwingt dich systematic-debugging durch Investigation, Musteranalyse und Hypothese, bevor du implementierst. In der Praxis bedeutet das:

• Du etablierst eine verlässliche Reproduktion, bevor du Code anfasst
• Du variierst Bedingungen, um den Problemraum zu verstehen
• Du implementierst einen fokussierten Fix pro validierter Hypothese

Das Ergebnis sind weniger Reverts, weniger versteckte Regressionen und besser planbare Debugging-Zeiten.

Wie installiere ich das systematic-debugging Skill?

Nutze den npx skills Befehl:

npx skills add https://github.com/obra/superpowers --skill systematic-debugging

Nach der Installation öffnest du das Skill in deinem Agent oder Skills-Verzeichnis und liest SKILL.md für den vollständigen Prozess sowie die ergänzenden Markdown-Dateien für Patterns und Beispiele.

Unterstützt systematic-debugging JavaScript- und TypeScript-Debugging?

Ja. Das Framework selbst ist sprachunabhängig, aber das Repository enthält konkrete JavaScript/TypeScript-orientierte Utilities:

• condition-based-waiting-example.ts für condition-based waiting in Tests
• Patterns in defense-in-depth.md und root-cause-tracing.md, illustriert mit TypeScript-Beispielen
• find-polluter.sh, das standardmäßig von npm test ausgeht und gut mit typischen JS/TS-Testrunnern funktioniert

Du kannst diese Utilities an deine Projektstruktur und Toolchain anpassen.

Kann ich systematic-debugging für flaky Testautomation verwenden?

Ja. Das ist eine der stärksten Einsatzmöglichkeiten. Kombiniere:

• Den Vier-Phasen-Prozess aus SKILL.md, um Flakiness zu untersuchen und zu verstehen
• condition-based-waiting.md und das TypeScript-Beispiel, um Timing-Schätzungen durch condition-based waits zu ersetzen
• find-polluter.sh, um Tests zu finden, die State verschmutzen oder unerwartete Dateien erzeugen

Gemeinsam helfen dir diese Tools, unzuverlässige Tests in stabile, deterministische Checks zu verwandeln.

Ist systematic-debugging nur für Tests oder auch für Produktions-Bugs gedacht?

Der Prozess lässt sich auf jedes technische Problem anwenden:

• Testfehler und Flakiness
• Produktions-Bugs und Incidents
• Performance-Probleme
• Build- und Integrationsfehler

Die Beispiele und Utilities sind stärker auf Test- und Entwicklungs-Workflows zugeschnitten, aber die Phasen und Prinzipien sind ausdrücklich so formuliert, dass sie auch Produktionsszenarien abdecken.

Was ist, wenn ich unter Zeitdruck stehe und nur einen schnellen Fix brauche?

Das Skill ist bewusst so geschrieben, dass es dem "nur ein schneller Fix"-Impuls entgegenwirkt. Es argumentiert, dass:

• Hektisches Vorgehen ohne Root-Cause-Investigation zu Hin-und-her und Rework führt
• Fixes, die nur Symptome behandeln, oft neue Probleme erzeugen

In der Praxis spart es meist Zeit, selbst bei dringenden Incidents ein paar Minuten in Phase 1 und Phase 2 zu investieren.

Muss ich wirklich jedes Mal alle vier Phasen befolgen?

Die Intention von systematic-debugging ist, dass das Überspringen von Phasen die Ausnahme und nicht die Regel ist. Bei kleinen, vollständig verstandenen Problemen (z. B. ein kleiner Refactor, bei dem du den Fehler sofort siehst) kannst du die Schritte verdichten. Aber wenn:

• Das Problem wiederkehrend ist
• Du nicht genau weißt, warum es auftritt
• Frühere Fixes fehlgeschlagen sind

…dann wird der vollständige Vier-Phasen-Prozess dringend empfohlen.

Wie hängen Root-Cause-Tracing und Defense-in-Depth zusammen?

root-cause-tracing.md hilft dir, einen Bug von der sichtbaren Fehlermeldung über die Call Chains bis zum ursprünglichen Auslöser zu verfolgen. defense-in-depth.md zeigt dann, wie du ähnliche Bugs verhinderst, indem du:

• an der tatsächlichen Quelle fixst
• Validierung auf mehreren Ebenen hinzufügst

Wenn zum Beispiel git init im falschen Verzeichnis fehlschlägt, zeigt dir Tracing, welche Funktion den falschen Pfad übergeben hat, und Defense-in-Depth fügt Validierung und Guards hinzu, damit ungültige Pfade früher abgewiesen werden.

Kann ich das Skill nutzen, ohne Code aus dem Repo zu übernehmen?

Ja. Der Kernnutzen von systematic-debugging ist der strukturierte Debugging-Prozess in SKILL.md. Du kannst:

• Die Phasen und Regeln direkt in deiner eigenen Umgebung anwenden
• Investigation- und Analyse-Patterns auf jede Sprache oder jeden Stack übertragen

Die TypeScript- und Bash-Utilities sind optionale Beschleuniger – insbesondere für JS/TS und Unix-ähnliche Umgebungen.

Wo kann ich mir alles ansehen, was in systematic-debugging enthalten ist?

Nach der Installation öffnest du die Files- oder Repository-Ansicht von obra/superpowers unter skills/systematic-debugging. Wichtige Dateien zum Einstieg:

• SKILL.md
• condition-based-waiting.md
• condition-based-waiting-example.ts
• defense-in-depth.md
• root-cause-tracing.md
• find-polluter.sh

Diese Dateien liefern dir den vollständigen systematic-debugging Workflow plus konkrete Tools für Debugging und Test-Stabilisierung.