adamstallard/bug-hunter

Bug Hunter

Eine Behauptung ohne fehlschlagenden Test ist eine Vermutung. Alles, was dieser Skill berichtet, wird durch einen Test belegt, der vor der Korrektur rot und danach grün beobachtet wurde; alles, was er nicht belegen kann, wird verworfen. Das ist die ganze Idee und der Grund, warum seine Ausgabe lesenswert ist.

Er editiert das Arbeitsverzeichnis, fügt Testdateien hinzu und committet standardmäßig.

• So führst du jeden Schritt aus – reference.md. Lies es vor den Schritten 4–7, bevor du einen Report schreibst und vor dem Commit.
• Mutationstests, Schritt 3 bis Schritt 9 – mutation.md. Lies es, bevor du mit einem Mutanten beginnst.

Der Vertrag

1. Jeder behobene Bug hat einen Regressionstest, der rot beobachtet wurde am unkorrigierten Code und nach der Korrektur grün.
2. Jeder Kandidat, der nicht rot gemacht werden kann oder den eine zweite Meinung widerlegt, wird verworfen – und sein Test gelöscht, niemals fehlschlagend zurückgelassen.
3. Alles Reale, aber außerhalb des Rahmens oder nicht testbar, wird berichtet, nicht behoben.
4. Die vollständige Testsammlung endet nicht schlechter als zu Beginn.

Workflow-Checkliste

- [ ] Schritt 0: Änderungsumfang eingrenzen – nur gestagter Diff
- [ ] Schritt 1: Triage – lohnt sich die Überprüfung dieses Commits überhaupt?
- [ ] Schritt 2: Basis – führe die Testsuite aus, bevor du etwas anfasst
- [ ] Schritt 3: Kandidaten finden (starkes Modell, Erreichbarkeit erforderlich); Mutations-Subagenten parallel, wo die geänderten Funktionen Tests haben
- [ ] Schritt 4: Beweisen – schreibe den Test, führe ihn aus, fordere ein passendes Rot ein
- [ ] Schritt 5: Widerlegen – eine zweite Meinung versucht, jeden bewiesenen Bug zu töten, und prüft jeden überlebenden Test und Dead-Code-Anspruch
- [ ] Schritt 6: Beheben (Präventionsfrage, rahmenbegrenzt)
- [ ] Schritt 7: Verifizieren – neue Tests grün; die vollständige Suite einmal, vor Schritt 9
- [ ] Schritt 8: Iterieren – direkt nacheinander, bis zu 3 Mal, ohne nachzufragen; niemals ein 4. Mal
- [ ] Schritt 9: Einmal am Ende berichten; frage den Nutzer jede offene Entscheidung (Picker – geschrieben ist nicht gefragt); dann committen (mit Trailer von prose, wenn prose installiert ist) oder zur Überprüfung belassen – oder, unter "caller commits", mit dem Block von `scripts/caller-result.sh` enden

Führe dies niemals innerhalb eines git pre-commit-Hooks aus. Es schreibt Dateien, fügt Tests hinzu und committet – all dies kämpft mit der Index-Sperre von git. Es wird vor dem Erstellen des Commits ausgeführt, und der Commit erfolgt in Schritt 9.

Ein Begleit-Hook überwacht Commits, die nie hier durchgekommen sind: Nach jedem Befehl fragt er git, ob sich HEAD bewegt hat und ob der neue Commit einen Bug-hunter:-Trailer trägt. Der Trailer ist also der einzige Marker, der zählt – keine Umgebungsvariable, nichts zu merken, und der Aufzeichnung lebt im Commit selbst, wo git log sie prüfen kann.

Der Hook stellt auch eine zweite Frage zu jedem Trailer, der selbst kein Skip-Vermerk ist – "0 bugs gefunden" und "abgebrochen ..." eingeschlossen, nicht nur solche, die eine Korrektur melden: Stimmt ein Bug-hunter-Tree-Trailer mit dem tatsächlich gelandeten Baum überein? Diese Bindung erzeugt scripts/mint-trailer.sh, wenn es gegen den echten gestagten Baum ausgeführt wird, direkt vor dem Commit – siehe Schritt 9 für das Wie. Ein Bug-hunter:-Trailer kann ein echter git-Trailer mit genau der richtigen Formulierung sein und trotzdem ein Satz sein, der aus dem Lesen dieser Datei erinnert wird, anstatt durch Ausführen eines Teils davon produziert zu werden – das ist die eine Form, die die Zeichenfolgenprüfung nicht fangen kann, und wofür diese Bindung gedacht ist.

Ein Commit, der ohne Bug-hunter:-Trailer landet, oder mit einem, dessen Bug-hunter-Tree-Bindung nicht übereinstimmt, wird in einem Report genannt, mit dem Repository, in dem er sich befindet. Der Report schickt dich zum Abschnitt unten und gibt keinen Befehl, den Commit zu korrigieren: Der Hook kann nicht sehen, wo du stehst, und der benannte Commit ist oft nicht dein HEAD.

---

Wenn du ein Agent bist, der gleich commiten wird

Wenn ein anderer Skill deine Commits erstellt und diesen Skill vor jedem von ihnen ausführt, lass diesen Skill von "commit this" starten; führe ihn trotzdem für "bug check this" aus. Wenn dieser Durchgang bereits einen Commit-Betreff angegeben hat, verwende diesen Betreff unverändert. Füge nur Trailer hinzu.

Jeder Commit, den du erstellst, geht durch diesen Skill und trägt einen Bug-hunter:-Trailer. Nicht nur, wenn explizit danach gefragt – jedes Mal. Ein Commit mit Code bekommt die Jagd. Ein Commit mit nur Docs, Spezifikationen, Tests oder Formatierung überspringt die Jagd, nicht den Skill. "Commit this", "commit my changes", "wrap up and commit" oder deine eigene Entscheidung zu commiten nach Abschluss einer Aufgabe bedeuten alle: stage die Änderung, führe diesen Skill aus, dann committe. Die Triage (Schritt 1) entscheidet, ob ein bestimmter Commit die Überprüfung wert ist, daher ist es immer günstig, ihn auszuführen, wenn er nicht zutrifft.

Führe ihn selbst aus, in deiner eigenen Sitzung. Der Agent, der die Änderung geschrieben hat, führt diesen Skill aus. Gib den gesamten Durchlauf nicht an einen Subagenten weiter, der dann eigene Finder, Widerleger und Mutationsagenten startet: Der Durchlauf benötigt einen Orchestrator, der am Leben bleibt, um Überlebende zu sammeln und Agenten fortzusetzen, und ein verschachtelter Delegierter beendet ständig seinen Zug, während seine Kinder laufen. Das Delegieren der einzelnen Durchläufe, wie die Schritte sagen, ist die Art, wie es laufen soll.

Diesen Skill nicht umgehen

Eine Überschrift, nicht fünf Regeln, weil ein Agent, der nach einem Ausweg aus einer Prüfung sucht, zuverlässig die Naht zwischen separat formulierten Regeln findet. Jede Zeile hier wurde hinzugefügt, nachdem ein Agent die Regel umgangen hatte, die sie schließt.

1. Sage jedes Mal laut, welches du tust. Eine Zeile in der Antwort, die der Benutzer sehen kann: "bug-hunter wird auf N Dateien ausgeführt", oder "bug-hunter wird übersprungen – ". Nicht in deiner Überlegung – in der Antwort. Überspringen, während du nichts sagst, sieht genauso aus wie Ausführen und Nichts finden. Ein angegebenes Überspringen kann in vier Worten überstimmt werden; ein nicht angegebenes ist eine Entscheidung, die du für sie getroffen hast. Wenn du überspringst, trägt der Commit auch den Trailer – commit-with-trailer.sh -F msg.txt "übersprungen – <Grund>", wie in Schritt 9. Beides, nicht entweder. Unter caller commits geht das Überspringen stattdessen zum Ergebnisskript (Wenn der Aufrufer committet).

2. Nie um Erlaubnis bitten, es auszuführen. Der Auslöser ist eine Eigenschaft des Codes, kein Zeitpunkt: Wenn Code seit dem letzten sauberen Durchlauf geschrieben wurde, ist ein Durchlauf geschuldet. Vor einem Commit, zwischen Iterationen, nach einer Korrektur, die der Nutzer angefragt hat, nach einem Refactoring, nach einem bereits gelandeten Commit – nicht getrennte Fälle, alle "Code wurde geschrieben". Eine Liste von Zeitpunkten lädt dazu ein, nach dem Zeitpunkt zu suchen, der nicht auf der Liste steht.

3. Ankündigen zählt nur, wenn du bereits begonnen hast. "Das läuft als nächstes, wenn du hier aufhören willst" · "Ich starte das, wenn du damit zufrieden bist" · "Die Korrekturen brauchen ihren eigenen Durchlauf – soll ich ihn ausführen?" Jedes beendet den Zug mit der nicht laufenden Prüfung, was die Entscheidung so klar zurückgibt wie Fragen. Wenn du einen Durchlauf in der Zukunftsform beschreibst, hast du ihn nicht gestartet, und das ist der Bug.

4. Iterationen laufen direkt nacheinander, und der Report ist geschuldet. Bis zu drei, kein Check-in dazwischen und kein Zwischenbericht – ein Bericht zwischen Iterationen lädt zum vorzeitigen Stoppen ein und lässt einen unvollständigen Durchlauf abgeschlossen aussehen. Siehe Schritte 8 und 9.

Drei ist das Budget, kein Eröffnungsangebot. Es gibt keine vierte Iteration. "Soll ich noch einen Durchlauf machen?" · "Die eigenen Korrekturen von Iteration 3 wurden nie überprüft – soll ich eine vierte machen?" Beide geben eine Entscheidung zurück, die das Budget bereits getroffen hat, in dem Moment, in dem der Nutzer am wahrscheinlichsten Nein sagt. Ein Durchlauf, der an die Grenze stößt, endet im Ursachenbericht (Schritt 9) und einer Wahl pro Ursache, wobei die erste Wahl ein neuer Durchlauf bei Iteration 1 ist, der auf diese Ursache beschränkt ist. Das ist nicht Regel 2 ausgesetzt: Ein Durchlauf über die Korrekturen von Iteration 3 ist wirklich geschuldet, und er ist immer noch geschuldet – was ausgegangen ist, ist das Budget, ihn innerhalb dieses Durchlaufs zu nehmen, weshalb es ein neuer Durchlauf wird und weshalb der Nutzer bestimmt, welche Ursache ihn bekommt. Noch ist es Regel 3 umgekehrt: Innerhalb des Budgets ist ein Durchlauf geschuldet, und du startest ihn ohne zu fragen; an der Grenze ist der Durchlauf vorbei, und was übrig bleibt, ist eine Entscheidung, die als Optionen angeboten wird, nicht als offene Frage.

5. Das sind keine Gründe. Jeder wurde von einem fähigen Modell verwendet, um diesen Skill bei einem Commit zu überspringen, der dann einen Bug ausgeliefert hat:

• die Änderung ist klein – Einzeilen-Änderungen sind ständig falsch
• Ich bin zuversichtlich in diesen Code – das war jeder Autor jedes Bugs, den dieser gefunden hat
• der Nutzer wartet / wir sind schnell unterwegs – das ist der Moment, in dem Qualität geopfert wird, wofür dies existiert
• die Sitzung ist lang und das ist teuer – ein Durchlauf, der nichts findet, ist billig, die Triage stoppt die meisten Commits vor dem teuren Teil, und die langen Durchläufe laufen ohnehin im Hintergrund (Schritt 3)
• Ich habe es bereits früher auf verwandtem Code ausgeführt – du hast es nicht auf diesem ausgeführt
• das ist die eigene Maschinerie des Skills, kein echter Code – es ist echter Code, und die schlimmsten Bugs in der eigenen Geschichte dieses Skills waren genau in dieser Maschinerie
• der Nutzer sieht offensichtlich zu und würde Einspruch erheben, wenn es ihn stört – sie sehen die Ausgabe, nicht die Abwesenheit davon

Bugs zu erzeugen und weiterzumachen, weil die Überprüfung unbequem war, ist das spezifische Verhalten, das dieser Skill stoppen soll. Es gegenüber diesem Skill zu tun, ist keine Ironie, es ist nur der Bug.

Wessen Entscheidung die Kosten sind. Ein vollständiger Durchlauf dauert Minuten; ein schlechter eine halbe Stunde. Wer auch immer dies installiert hat, hat bereits eine langsamere Commit-Geschwindigkeit gegen einen Bug, der Main erreicht, abgewogen. Ein Agent, der stillschweigend entscheidet, dass die Prüfung heute zu langsam ist, hat kein technisches Urteil gefällt – er hat diese Entscheidung im Namen von jemandem, der nicht im Raum ist, in die Richtung überschrieben, die zufällig weniger Arbeit ist. Wenn die Kosten jetzt wirklich wichtig sind, sag es in einem Satz und lass sie wählen.

Wessen Entscheidung es ist

Zwei kurze Listen, weil beide Fehler an der Grenze zwischen ihnen leben: Nach der ersten zu fragen, trainiert den Nutzer zu überfliegen, und die zweite für sie zu entscheiden, ist Wahl 3 stillschweigend genommen.

Deine, nie gefragt. Ob und wann ausgeführt wird; ob ein Kandidat bewiesen, widerlegt oder verworfen wird; wie ein bewiesener Bug innerhalb der Änderung behoben wird; ob iteriert wird, bis zur Grenze; die Suite ausführen; einen sauber beendeten Durchlauf ohne Offenes zu committen – außer unter caller commits, wo der Commit Sache des Aufrufers ist.

Die des Nutzers, immer gefragt. Worauf reagiert wird: jede Ursache und jede Empfehlung (jetzt beheben / aufschreiben / überspringen), jeder ungelöste Eintrag eines Abbruchs, ob ein Commit durchgeführt wird, wenn etwas Berichtetes-nicht-Behobenes seine Bedeutung ändert (Nur-Bericht-Modus), und der Stopp in Schritt 0 – welche der divergierenden gestagten und ungestagten Bearbeitungen einer Datei behalten werden soll.

Wenn du fragst, verwende den interaktiven Picker des Hosts (in Claude Code das AskUserQuestion-Tool): Jede Frage mit diskreten Optionen geht durch ihn, eine Frage pro Entscheidung, in der Reihenfolge des Schweregrads, nie in Prosa am Ende eines langen Berichts vergraben. Klartext ist der Fallback für Hosts ohne Picker, nicht der Standard. Der Picker ist auch das eine Ding hier, das strukturell und nicht beratend ist – ein Zug mit einem offenen Picker kann nicht enden, bis der Nutzer antwortet – weshalb die nächste Regel wichtig ist.

Gefragt bedeutet, der Nutzer hat es gesehen. Eine Frage ist gestellt, wenn sie in einer Antwort ist, die der Nutzer liest, oder einem Picker, den er beantwortet – nicht, wenn ein Agent sie aufgeschrieben hat. Wenn dieser Skill in einem Agenten läuft, der an einen anderen Agenten berichtet, erreichen sein Schritt-9-Bericht und seine Fragen diesen Agenten, und noch nichts ist gefragt: Der Hop verschiebt den Picker, er entlastet die Frage nicht. Also:

• Wenn ein von dir erzeugter Agent dies auf seine eigene Änderung ausgeführt hat, ist sein Bericht deine Schritt-9-Eingabe, nicht deine Schritt-9-Ausgabe. Jede offene Entscheidung in diesem Bericht kommt vor den Nutzer in deiner nächsten Antwort, vor allem anderen – durch deinen Picker, eine Frage pro Entscheidung, oder den nummerierten Block des Berichts wörtlich, wo es keinen gibt. "Der Durchlauf wurde abgebrochen" oder "es wurden drei Ursachen gefunden" ohne Optionen darunter ist über den Bericht zu berichten, anstatt ihn auszuliefern; wenn du diesen Satz schreibst, ist das der Bug. Die Entscheidung über einen Zug zu halten, während andere Arbeit abgeschlossen wird, ist Wahl 3, für sie getroffen – die andere Arbeit wartet, oder die Antwort trägt beides.
• Wenn du dies in einem Agenten ausführst, der an einen anderen Agenten berichtet, hast du keinen Picker, der den Nutzer erreicht. Gib den gesamten Bericht in seinem Format aus – keine Zusammenfassung davon – mit dem Übergabe-Fußzeile (reference.md), die demjenigen, der ihn hält, sagt, was noch zu fragen ist. Sage klar, welche Entscheidungen offen sind und dass du sie nicht fragen konntest. Unter caller commits ersetzt die Entscheidungsliste des Ergebnisblocks die Fußzeile (Wenn der Aufrufer committet).

Ein Durchlauf ist nicht beendet, bis seine Fragen vor dem Nutzer sind, egal welcher Agent sie dorthin bringt.

Schritt 0 – Eingrenzung

Die zu überprüfende Änderung ist der gestagte Diff:

git diff --cached --stat
git diff --cached

Lies die gesamte Datei für jede geänderte Datei, nicht nur die Hunks – ein Bug liegt normalerweise in der Interaktion zwischen neuem Code und dem Code darum herum.

Wenn eine Datei sowohl im gestagten als auch im ungestagten Diff erscheint, stoppe. Du würdest über den Index nachdenken, während du den Arbeitsbaum testest, und sie stimmen nicht überein. Sage dem Nutzer, welche Dateien abweichen, und frage sie, diese Bearbeitungen zu stagen oder rückgängig zu machen. Führe niemals git stash aus, um dies zu umgehen – der Nutzer hat uncommittete Arbeit, und dieser Skill wird gleich Dateien darauf schreiben.

Ungestagte Änderungen in anderen Dateien sind in Ordnung. Notiere sie im Bericht.

Jage nicht nach Bugs in Spezifikationen, Dokumentation oder bestehenden Tests. Änderungen an diesen Dateien sind trotzdem lesenswerter Kontext.

Schritt 1 – Triage

Triage entscheidet anhand des Diffs, nicht anhand der Commit-Nachricht. Bei einem Diff von bis zu etwa 300 geänderten Zeilen triage ihn selbst, in der Schleife, in der du bereits bist: Ein Sub-Agent kostet mehr zu starten, als einen Diff dieser Größe zu lesen. Delegiere einen größeren Diff an einen einzigen schnellen Durchlauf auf einem kleinen, billigen Modell. So oder so bekommt der Durchlauf die Dateiliste, den Diff und ob der Nutzer nach einem Checkpoint gefragt hat (unten). Frage nach einem von REVIEW oder SKIP plus einzeiliger Begründung. Frage nicht zuerst nach einer Commit-Nachricht und lies kein Betreff-Präfix als Signal – dieser Skill erlegt keine Commit-Konvention auf (reference.md).

SKIP, wenn der Diff zeigt:

• Nichts außerhalb von Docs, Spezifikationen, Tests, Lockfiles, gene...

[...truncated for translation...]