systematic-debugging

Überblick über den systematic-debugging-Skill

Der systematic-debugging-Skill ist ein strukturierter Debugging-Workflow für Agents und Entwickler, die weniger Fixes per Rätselraten und schneller belastbare Root-Cause-Analysen wollen. Die zentrale Regel ist einfach: erst untersuchen, dann Code ändern. Genau deshalb passt er besonders gut zu fehlgeschlagenen Tests, flaky Verhalten, Produktionsfehlern, Build-Problemen und Integrationsfehlern, bei denen ein „schneller Fix“ die eigentliche Ursache eher verdeckt.

Für wen der systematic-debugging-Skill am besten geeignet ist

Nutze systematic-debugging, wenn du:

• immer wieder Fixes siehst, die scheitern oder nur einen Teil des Problems lösen
• unter Zeitdruck debuggen musst
• einen AI-Assistenten dazu bringen willst, erst sauber zu untersuchen statt Symptome zu patchen
• einen wiederholbaren Prozess für Bugs, flaky Tests und unerwartetes Verhalten suchst

Besonders nützlich ist der Skill, wenn das Problem auf den ersten Blick offensichtlich wirkt, du aber noch nicht weißt, warum es tatsächlich auftritt.

Welchen Job der Skill in der Praxis wirklich erfüllt

Die eigentliche Aufgabe ist nicht „einen Fix liefern“. Sie ist:

1. das Problem reproduzieren,
2. die Ursache zurückverfolgen,
3. immer nur eine Erklärung auf einmal testen,
4. erst dann einen gezielten Fix umsetzen.

Das klingt zunächst langsamer, reduziert in der Praxis aber meist Nacharbeit, fehlgeschlagene Patches und neue Bugs, die durch bloßes Raten entstehen.

Was systematic-debugging anders macht

Die meisten gewöhnlichen Prompts springen direkt vom Symptom zur Lösung. Der systematic-debugging skill ist bewusst darauf ausgelegt, genau das nicht zu tun. Das Repo setzt klar auf einen Workflow im Stil eines „Iron Law“: keine Fixes ohne vorherige Root-Cause-Untersuchung.

Auch die begleitenden Dateien machen den Skill deutlich praktischer als eine generische Debugging-Checkliste:

• root-cause-tracing.md hilft, wenn der sichtbare Fehler weit von seiner eigentlichen Ursache entfernt ist
• condition-based-waiting.md hilft bei flaky asynchronen Tests, die durch willkürliche Delays instabil werden
• defense-in-depth.md hilft dabei, aus einmaligen Validierungsfixes strukturelle Absicherung zu machen
• find-polluter.sh hilft, Tests zu isolieren, die Dateien oder Zustand hinterlassen

Welche Problemtypen besonders gut zu systematic-debugging passen

systematic-debugging for Debugging ist besonders geeignet für:

• fehlgeschlagene Tests, die du noch nicht erklären kannst
• flaky Tests in CI
• Bugs, bei denen frühere Fixes nicht dauerhaft gehalten haben
• Fehler, die tief im Stack auftauchen
• kaputten Zustand, geleakte Dateien, falsche Pfade, Race Conditions und Timing-Probleme

Wann dieser Skill weniger gut passt

Lass ihn nur weg, wenn die Aufgabe gar kein echtes Debugging ist, zum Beispiel:

• geradlinige Feature-Entwicklung
• Routine-Refactorings ohne fehlschlagendes Verhalten, das erklärt werden muss
• rein kosmetische Änderungen

Selbst dann gilt: Wenn du auf „unerwartetes Verhalten“ reagierst, ist systematic-debugging meist der sicherere Startpunkt.

So nutzt du den systematic-debugging-Skill

Installationskontext für systematic-debugging

Wenn du das in diesem Ökosystem übliche Skills-CLI-Muster verwendest, installierst du den Skill so:

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

Danach kannst du ihn aus deiner Agent-Umgebung aufrufen oder den Prozess manuell nutzen, indem du die Quelldateien im Skill-Ordner liest.

Diese Dateien solltest du zuerst lesen

Für einen schnellen, signalstarken systematic-debugging guide lies in dieser Reihenfolge:

1. skills/systematic-debugging/SKILL.md
2. skills/systematic-debugging/root-cause-tracing.md
3. skills/systematic-debugging/condition-based-waiting.md
4. skills/systematic-debugging/defense-in-depth.md
5. skills/systematic-debugging/find-polluter.sh

Warum genau diese Reihenfolge:

• SKILL.md beschreibt den verpflichtenden Vier-Phasen-Workflow
• root-cause-tracing.md hilft, wenn Symptome erst weit downstream sichtbar werden
• condition-based-waiting.md liefert ein konkretes Fix-Muster für flaky asynchrone Tests
• defense-in-depth.md hilft dabei, den finalen Fix robuster zu machen
• find-polluter.sh ist ein praktisches Hilfsmittel, um Test-Pollution zu isolieren

Welche Eingaben der Skill von dir braucht

Die Qualität der systematic-debugging usage hängt stark von den Informationen ab, die du mitgibst. Gib dem Skill:

• die exakte Fehlermeldung
• den Stack Trace
• Reproduktionsschritte
• erwartetes versus tatsächliches Verhalten
• Umgebungsdetails wie OS, Runtime, Test Runner, nur CI oder nur lokal
• aktuelle Code-Änderungen
• ob das Problem deterministisch oder flaky ist
• was du bereits ausprobiert hast

Ohne diese Informationen steigt die Wahrscheinlichkeit, dass das Modell spekuliert.

So machst du aus einem groben Bug Report einen starken Prompt

Schwacher Prompt:

Test is failing. Help fix it.

Stärkerer Prompt:

Use systematic-debugging on this failing test. Do not propose a fix until root cause investigation is complete. Here is the exact error, stack trace, reproduction command, recent changes, and the one behavior difference between local and CI. Identify likely root causes, suggest the minimum investigation steps, and keep hypotheses separate.

Dieser Prompt funktioniert besser, weil er zuerst Untersuchungsergebnisse verlangt und erst danach an die Umsetzung geht.

Ein praxistaugliches Prompt-Template

Nutze für systematic-debugging usage diese Struktur:

• Issue: was fehlgeschlagen ist
• Reproduction: exakter Befehl oder genaue Schritte
• Evidence: Logs, Trace, Screenshots, fehlschlagende Assertion
• Scope: lokal, CI, ein Rechner, alle Umgebungen
• Recent changes: Commits, Dependency-Bumps, Config-Änderungen
• Constraints: API darf nicht geändert werden, minimaler Patch nötig, Deadline usw.
• Request: erst Root Cause untersuchen, dann genau einen Fix vorschlagen

Beispiel:

Use systematic-debugging for this Jest failure. Repro: npm test src/foo.test.ts. Error: Timeout waiting for TOOL_RESULT event after 5000ms. It fails in CI and under parallel runs, not always locally. We recently changed thread event handling. First investigate root cause, then propose one focused fix and one validation plan.

Den Vier-Phasen-Workflow in der richtigen Reihenfolge anwenden

Das Repo basiert auf vier Phasen. Praktisch nutzt du sie so:

1. Root-Cause-Untersuchung
   Lies den Fehler sorgfältig, reproduziere ihn zuverlässig, prüfe, was sich geändert hat, und sammle Belege.
2. Pattern Analysis
   Achte auf Muster bei Timing, Umgebung, Input-Struktur, State-Leaks oder entlang der Call Chain.
3. Hypothesis Testing
   Formuliere immer nur eine Erklärung auf einmal und teste sie. Vermeide es, mehrere Variablen gleichzeitig zu ändern.
4. Implementation
   Erst wenn die Belege eine Ursache stützen, setzt du den Fix um und verifizierst ihn.

Wenn Phase 1 schwach ist, wird jeder spätere Schritt schlechter.

So nutzt du systematic-debugging bei flaky Tests

Das Repo ist hier ungewöhnlich praxisnah. Wenn ein Test auf sleep, setTimeout oder beliebige Waits angewiesen ist, schau dir condition-based-waiting.md und condition-based-waiting-example.ts an.

Die entscheidende Umstellung:

• schlechtes Muster: raten, wie lange asynchrone Arbeit wohl braucht
• besseres Muster: auf die Bedingung warten, die die Fertigstellung wirklich belegt

Das ist wichtig, weil viele scheinbar „zufällige“ Fehler in Wahrheit Race Conditions sind, die von Timing-Vermutungen verdeckt werden.

So gehst du vor, wenn das Symptom erst downstream auftaucht

Wenn der Fehler tief im Stack erscheint oder weit von der Stelle entfernt ist, an der die falschen Daten entstanden sind, nutze root-cause-tracing.md. Der Workflow ist:

• die unmittelbar fehlschlagende Zeile identifizieren
• einen Caller nach oben gehen
• weiter zurückverfolgen, bis du den Punkt findest, an dem der falsche Zustand erstmals auftaucht
• an der Quelle fixen, nicht nur an der Absturzstelle

Das ist einer der wertvollsten Teile des systematic-debugging skill, weil viele Bugs nur Symptome eines früher entstandenen ungültigen Zustands sind.

So verwendest du den Polluter-Finder

Für Tests, die Dateien, Verzeichnisse oder Zustand hinterlassen, lohnt sich ein Blick in find-polluter.sh, bevor du dir selbst irgendeine Schleife improvisierst.

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

Beispiel aus dem Skript:
./find-polluter.sh '.git' 'src/**/*.test.ts'

Das ist besonders nützlich, wenn der Fehler nicht vom sichtbar fehlschlagenden Test selbst verursacht wird, sondern von versteckter Test-Pollution.

Ein typischer Workflow, der die besten Ergebnisse liefert

Ein zuverlässiger Ablauf für systematic-debugging install und den ersten Einsatz:

1. den Skill installieren
2. SKILL.md lesen
3. exakte Fehlerbelege sammeln
4. den Agenten erst untersuchen lassen, ohne direkt zu fixen
5. die Hypothese mit der stärksten Beleglage auswählen
6. nur diese eine Hypothese testen
7. einen gezielten Fix umsetzen
8. Validierung oder Defense-in-Depth ergänzen, wenn der Bug aus ungültigen Daten oder mehreren Eintrittspfaden entstanden ist

So vermeidest du den häufigsten Fehler: Code zu ändern, bevor du den eigentlichen Fehler verstanden hast.

Was du mit diesem Skill nicht tun solltest

Bitte systematic-debugging nicht darum,

• sofort viele mögliche Fixes zu brainstormen
• große Codebereiche umzuschreiben, bevor der Bug reproduziert ist
• „einfach nur den Test grün zu machen“ ohne Erklärung
• mehrere vermutete Ursachen gleichzeitig zu patchen

Diese Abkürzungen widersprechen direkt dem Design des Skills und verschlechtern die Ergebnisqualität.

FAQ zum systematic-debugging-Skill

Ist systematic-debugging nur für komplexe Bugs gedacht?

Nein. Die Grundhaltung des Repos ist: Auch einfache Bugs haben Ursachen. Besonders wertvoll ist der Skill gerade dann, wenn ein Problem simpel genug aussieht, um zu einem schnellen Patch zu verleiten.

Worin unterscheidet sich das von einem normalen Debugging-Prompt?

Ein normaler Prompt belohnt oft Geschwindigkeit und spekulative Fixes. systematic-debugging zwingt das Modell dazu, Untersuchung, Hypothesenbildung und Umsetzung sauber zu trennen. Das führt meist zu weniger falschen Patches und zu besseren Erklärungen.

Ist systematic-debugging einsteigerfreundlich?

Ja, solange du konkrete Belege liefern kannst. Der Prozess ist streng, aber die Schritte sind nachvollziehbar: reproduzieren, prüfen, zurückverfolgen, eine Idee testen, dann fixen. Gerade Einsteiger profitieren oft besonders, weil der Skill zufälliges Trial-and-Error verhindert.

Wann sollte ich systematic-debugging nicht verwenden?

Nutze es nicht als primäres Muster für:

• Feature-Ideation
• Architektur-Brainstorming
• Code-Generierung ohne Bezug zu einem Fehler
• rein visuelle Anpassungen ohne kaputtes Verhalten, das erklärt werden muss

Nutze es, wenn etwas nicht stimmt und du die Ursache brauchst, nicht nur einen Patch.

Hilft systematic-debugging bei Fehlern, die nur in CI auftreten?

Ja. Der Skill passt sehr gut zu CI-only- oder lastabhängigen Fehlern, weil er dich dazu zwingt, Umgebungen zu vergleichen, Bedingungen zu reproduzieren und Annahmen zu Timing und Zustand zu prüfen, statt ins Blaue hinein zu raten.

Kann der Skill bei flaky asynchronen Tests helfen?

Ja, und genau darin ist dieses Repo stärker als viele vergleichbare Ansätze. condition-based-waiting.md und die beispielhafte TypeScript-Datei zeigen sehr konkret, wie du von beliebigen Waits zu zustandsbasierter Synchronisation kommst.

Enthält der Skill auch Tools oder nur Hinweise?

Vor allem Prozessführung, ergänzt um einige konkrete Begleitdateien. Das praktischste Hilfsmittel ist find-polluter.sh, und das Beispiel für condition-based waiting lässt sich in manchen TypeScript-Testsetups direkt wiederverwenden.

Kann ich systematic-debugging mit jedem Stack verwenden?

Im Großen und Ganzen ja. Die Methode selbst ist stack-agnostisch. Die Beispiele orientieren sich eher an TypeScript, Shell und Test-Workflows, aber der Untersuchungsprozess funktioniert über Sprachen und Frameworks hinweg.

So verbesserst du den systematic-debugging-Skill

Gib bessere Belege, bevor du nach einem Fix fragst

Der größte Hebel ist die Qualität der Eingaben. Für bessere systematic-debugging-Ergebnisse solltest du Folgendes mitgeben:

• genau einen exakten Reproduktionsbefehl
• genau einen exakten Fehlerblock
• genau einen minimalen fehlschlagenden Test oder eine Datei
• was sich zuletzt geändert hat
• ob sich das Problem immer reproduzieren lässt

So arbeitet der Skill auf Basis von Belegen statt auf Basis von Vermutungen.

Verlange Untersuchungsergebnisse vor der Implementierung

Ein leistungsstarker Prompt blockiert frühes Fixen ausdrücklich. Zum Beispiel:

Use systematic-debugging. First produce root-cause investigation findings and the top 2 hypotheses with evidence for each. Do not suggest code changes yet.

Das verbessert die Antwortqualität, weil zwischen Symptomanalyse und Code-Änderung ein klarer Kontrollpunkt entsteht.

Erzwinge immer nur eine Hypothese gleichzeitig

Ein häufiger Fehler ist, mehrere mögliche Ursachen in einem Patch zu vermischen. Frage gezielt nach:

• der führenden Hypothese
• dem kleinsten Test, der sie widerlegen würde
• dem Ergebnis, das sie bestätigen würde

So bleibt der Workflow sauber an der eigentlichen Intention des Skills ausgerichtet.

Prompts für flaky-Test-Szenarien gezielt verbessern

Wenn du systematic-debugging for Debugging bei flaky Tests einsetzt, gib zusätzlich an:

• wie oft der Test besteht oder fehlschlägt
• ob die Fehler mit Parallelisierung oder CI zusammenhängen
• ob sleep, Waits, Retries oder Polling verwendet werden
• welches exakte Event oder welcher Zustand vom Test beobachtet werden soll

Damit erkennt das Modell deutlich leichter, wann condition-based-waiting.md das passende Begleitmuster ist.

Nutze quellnahe Dateien, nicht nur SKILL.md

Wenn die erste Antwort zu generisch wirkt, lenke das Modell gezielt auf die unterstützenden Dokumente:

• root-cause-tracing.md für downstream auftauchende Symptome
• condition-based-waiting.md für Timing- oder Race-Probleme
• defense-in-depth.md für Validierungsstrategien
• find-polluter.sh für Test-Pollution

Der Skill wird deutlich besser, wenn der Agent das spezialisierte Begleitmaterial nutzt und nicht nur den Haupt-Workflow aus SKILL.md.

Nach dem ersten Durchlauf den Scope enger ziehen

Wenn das erste Ergebnis zu breit bleibt, konkretisiere mit:

• dem exakten Subsystem, das geprüft werden soll
• der vermuteten Grenze, an der falsche Daten eintreten
• dem ersten Commit, in dem das Problem aufgetreten ist
• der kleinsten fehlschlagenden Reproduktion

Breite Debugging-Prompts erzeugen oft breite Debugging-Pläne. Ein enger Scope führt meist zu besserer Root-Cause-Arbeit.

Verbessere den finalen Fix, nicht nur die Diagnose

Sobald die Ursache gefunden ist, frage zusätzlich nach:

• dem minimalen Fix
• genau einem Regression Test
• genau einer Validierungsschicht, die ein erneutes Auftreten verhindert

Hier wird defense-in-depth.md besonders nützlich. Wenn der Bug aus ungültigen Inputs oder leicht umgehbaren Annahmen entstanden ist, reicht ein einzelner Patch unter Umständen nicht aus.

Achte auf diese typischen Fehlermuster

Schwache systematic-debugging usage entsteht meist durch:

• unvollständigen Fehlertext
• keine verlässliche Reproduktion
• zu frühe Bitte um Fixes
• mehrere Änderungen zwischen Testläufen
• die erste plausible Erklärung als bewiesen zu behandeln

Wenn du diese Punkte vermeidest, ist der Skill deutlich wertvoller als ein generischer „debug this“-Prompt.