diagnose
von mattpocockdiagnose ist ein strukturierter Debugging-Workflow für knifflige Bugs, flaky Tests und Performance-Regressions. Er hilft dir, das Problem zu reproduzieren, den fehlschlagenden Fall zu minimieren, immer nur eine Hypothese auf einmal aufzustellen, Instrumentierung einzubauen, die Ursache zu beheben und den Fix mit einem Regressionstest abzusichern. Nutze den diagnose-Leitfaden, wenn „debug this“ nicht ausreicht.
Dieses Skill erreicht 74/100 und ist damit für Nutzer mit Bedarf an einem disziplinierten Workflow zur Bug-Diagnose durchaus listenswert, aber noch keine besonders ausgereifte Installations-Entscheidungsseite. Das Repository liefert genug konkrete Prozessanleitung, damit Agents es mit weniger Rätselraten nutzen können als einen generischen Prompt, vor allem beim Aufbau einer deterministischen Feedback-Schleife und bei der Wahl von Reproduktionsmethoden.
- Klares Triggering und sauberer Scope für knifflige Bugs, Throwers/Failures und Performance-Regressions in den Frontmatter-Daten.
- Starke operative Führung: Reproduce → minimise → hypothesise → instrument → fix → regression-test, inklusive konkreter Wege für eine Pass/Fail-Schleife.
- Enthält eine ausführbare Human-in-the-Loop-Shell-Vorlage, was die Agenten-Triggerbarkeit für interaktive Reproduktions-Workflows verbessert.
- Die sichtbaren Belege sind stark auf die Diagnose-Methodik fokussiert; der Ausschnitt zeigt nicht den kompletten End-to-End-Workflow, daher müssen Installationsnutzer einige Ausführungsdetails unter Umständen selbst ergänzen.
- Experimenteller/Test-Charakter und kein Installationsbefehl in SKILL.md können die Nutzung weniger schlüsselfertig wirken lassen als bei ausgereifteren Skills.
Überblick über diagnose skill
Wofür diagnose gedacht ist
Der diagnose skill ist ein strukturierter Debugging-Workflow für Fälle, in denen sich ein Fehler schwer eingrenzen lässt, ein Test instabil ist oder sich die Performance verschlechtert hat und Sie eine verlässliche Methode brauchen, um die Ursache zu isolieren. Er eignet sich besonders für Agents und Entwickler, die mehr wollen als einen generischen debug this-Prompt: Sie brauchen einen wiederholbaren Weg vom Symptom über die Reproduktion hin zu Hypothese, Instrumentierung, Fix und Regressionstest.
Wer ihn installieren sollte
Installieren Sie den diagnose skill, wenn Sie häufig an Codebases arbeiten, in denen Fehler sporadisch auftreten, von der Umgebung abhängen oder nur in der UI bzw. in produktionsnahen Abläufen sichtbar werden. Besonders nützlich ist er für Debugging in Projekten, in denen ein kurzer Blick in den Code nicht reicht und Sie vor Änderungen an der Implementierung erst ein belastbares Pass/Fail-Signal erzeugen müssen.
Was ihn unterscheidet
Der diagnose skill setzt zuerst auf den Aufbau einer schnellen Feedback-Schleife. Das ist sein wichtigstes Unterscheidungsmerkmal: Er priorisiert Reproduzierbarkeit und Beobachtbarkeit vor vorschnellen Codeänderungen. Außerdem ermutigt er dazu, das Glossar und die ADRs des Projekts zu nutzen, damit der Agent sich an der Fachsprache orientiert statt die Modulabsicht zu raten.
So verwenden Sie diagnose skill
diagnose skill installieren
Verwenden Sie den Installationspfad des Skills aus dem Repository und prüfen Sie anschließend, ob die Skill-Dateien in Ihrem lokalen Skills-Verzeichnis verfügbar sind. Für dieses Repo lautet der dokumentierte Installationsbefehl:
npx skills add mattpocock/skills --skill diagnose
Starten Sie nach der Installation mit SKILL.md und sehen Sie sich dann die unterstützenden Dateien an, die den Workflow prägen. Die relevantesten Repository-Pfade sind scripts/hitl-loop.template.sh sowie jede projektspezifische Dokumentation, die Begriffe, Architektur oder Testgrenzen erklärt.
Einen vagen Bug in einen guten diagnose-Prompt verwandeln
Der diagnose skill funktioniert am besten, wenn Ihr Input ein konkretes Symptom, den Auftretensort und das gewünschte Erfolgskriterium enthält. Ein schwacher Prompt lautet: „diagnose this.“ Ein stärkerer Prompt wäre:
„Diagnose, warum die Export-Schaltfläche in Staging manchmal fehlschlägt. Reproduziere das im Browser, minimiere die Schritte, ermittle, ob das Problem serverseitig oder clientseitig ist, und füge wenn möglich einen Regressionstest hinzu.“
Für die Verwendung von diagnose sollten Sie angeben:
- die beobachtete Fehlermeldung bzw. das Fehlerbild
- die Umgebung, in der es auftritt
- bekannte gute oder bekannte schlechte Beispiele
- ob Sie Tests, einen Dev-Server oder einen Browser-Harness ausführen können
Empfohlener Workflow und Dateien, die Sie zuerst lesen sollten
Beginnen Sie mit SKILL.md, um die Schleife zu verstehen, und lesen Sie danach scripts/hitl-loop.template.sh, wenn der Bug eine Reproduktion mit Human-in-the-Loop erfordert. Dieses Skript ist besonders hilfreich, wenn der Agent den Nutzer auffordern muss, Schritte durchzuklicken, einen Fehler zu erfassen oder Verhalten zu bestätigen, während der Agent das Ergebnis auswertet.
Ein praktikabler Workflow ist:
- das engste fehlgeschlagene Szenario identifizieren
- ein deterministisches Signal aufbauen
- jeweils nur eine Hypothese testen
- nur dort instrumentieren, wo das Signal unklar ist
- den Fix mit einem Regressionstest oder einem wiederholbaren Harness absichern
Tipps, die die Ergebnisse spürbar verbessern
Wenn Sie bessere Ergebnisse mit diagnose für Debugging wollen, sagen Sie dem Agenten, welche Werkzeuge erlaubt sind: Unit-Tests, CLI-Befehle, HTTP-Requests, Browser-Automation oder das Abspielen aufgezeichneter Traces. Erwähnen Sie auch, ob der Bug deterministisch, instabil oder performancebezogen ist, weil sich dadurch der Aufbau der Schleife ändert. Je präziser das beobachtbare Signal ist, desto weniger Zeit verbringt der Agent mit Raten.
FAQ zu diagnose skill
Ist diagnose besser als ein normaler Debug-Prompt?
Meistens ja, wenn das Problem schwer reproduzierbar ist oder mehrere Ebenen umfasst. Ein normaler Prompt springt oft direkt zu Codeänderungen; diagnose ist darauf ausgelegt, zuerst Belege zu schaffen, was bei flaky Bugs und Regressionen sicherer ist.
Wann sollte ich diagnose nicht verwenden?
Verwenden Sie diagnose nicht für offensichtliche Syntaxfehler, klare Null-Checks oder winzige Ein-Datei-Fixes, bei denen der Fehler bereits vollständig erklärt ist. In solchen Fällen kann der Aufwand für einen vollständigen diagnose-Leitfaden mehr sein, als Sie brauchen.
Ist der diagnose skill anfängerfreundlich?
Ja, wenn Sie das Symptom klar beschreiben und die vorgeschlagenen Checks ausführen können. Er ist besonders hilfreich, wenn Sie nicht wissen, wo der Bug sitzt, weil er der Untersuchung Struktur gibt, statt tiefes Vorwissen vorauszusetzen.
Passt diagnose zu jedem Stack?
Er passt zu den meisten Stacks, die einen Test, ein Skript, eine Browser-Prüfung oder einen wiederholbaren Input bereitstellen können. Weniger nützlich ist er, wenn das System keine deterministische Möglichkeit bietet, Erfolg oder Misserfolg zu beobachten, da der Skill auf einer verlässlichen Feedback-Schleife beruht.
So verbessern Sie diagnose skill
Geben Sie dem Skill ein stärkeres Startsignal
Die größte Verbesserung entsteht durch bessere Reproduktionsdetails. Statt „die App ist kaputt“ sollten Sie die exakte Aktion, die Datenform und das erwartete gegenüber dem tatsächlichen Ergebnis angeben. Wenn Sie Logs, eine fehlschlagende URL, ein Payload-Beispiel oder ein minimales Fixture haben, fügen Sie es direkt am Anfang hinzu.
Entfernen Sie Mehrdeutigkeiten, bevor Sie nach der Ursache fragen
Wenn es mehrere mögliche Fehler gibt, nennen Sie denjenigen, den Sie zuerst diagnostiziert haben möchten. Trennen Sie zum Beispiel „der Button tut nichts“ von „die Anfrage liefert 500“ und von „die Seite ist langsam“. Diagnose funktioniert am besten, wenn das anfängliche Problemstatement genau zu einem beobachtbaren Fehlerbild passt.
Nutzen Sie den ersten Durchlauf, um das nächste Experiment zu wählen
Verbessern Sie die Ergebnisse von diagnose nach dem ersten Output, indem Sie eine von drei Fragen beantworten: Ist die Reproduktion jetzt deterministisch, hat die Hypothese die Suche eingegrenzt, oder brauchen Sie ein anderes Signal? Wenn die Ausgabe weiterhin vage ist, bitten Sie lieber um einen kleineren Harness, eine andere Testnaht oder einen Browser-/CLI-Playback-Pfad, statt erneut nach einer breiten Erklärung zu fragen.