r3xsean/see-it-through

Nimm eine Code-Änderung aus der Benutzeranfrage und führe sie an den Zielort, wobei ein anderes Modell als Reviewer fungiert. Der Benutzer entscheidet zweimal: den Ansatz beim Explainer und das Ergebnis bei der Ship-Nachricht. Alles dazwischen liegt bei dir.

Das andere Modell ist das neueste Modell in orchestrator_capabilities der Familie, die der Benutzer genannt hat, mit dem Aufwand, den er genannt hat. Dasselbe Modell und derselbe Aufwand werden für jeden Hin und Her, Code-Loop und Review unten verwendet, außer bei einer Schlüsselentscheidungsdebatte. Wenn die Familie oder der Aufwand fehlt, frage danach und tue nichts weiter, bis der Benutzer antwortet.

Ein Runner argumentiert den Ansatz in Schritt 3 an deiner Stelle (die back-and-forth-Fähigkeit des Runners). Es sei denn, der Benutzer nennt einen Runner: das neueste Fable-Modell bei mittlerem Aufwand, das mit dem anderen Modell debattiert; bei einer Schlüsselentscheidung das neueste Fable-Modell bei hohem Aufwand, das mit dem neuesten Astra-Modell bei hohem Aufwand anstelle des anderen Modells debattiert. Eine Schlüsselentscheidung liegt vor, wenn ein Trigger in der strukturellen Frage von design.md ausgelöst wird und du eine Frage formulieren kannst, deren Antwort den Ansatz ändern könnte. Wenn das Modell eines Runners oder seines Partners nicht verfügbar ist, sage dies und argumentiere den Ansatz selbst mit dem anderen Modell.

1. Ziel und Regeln

Arbeite heraus, wo die Änderung endet: eine getestete lokale Änderung, ein gepushter Branch, ein offener PR, gemergt oder deployed. Frage nur, wenn es unklar ist und die Antwort die Arbeit beeinflusst. „See it through“ zu sagen, genehmigt keinen Push, PR oder Deploy; die Zustimmung der Ship-Nachricht tut dies.

Die Regeln des Repositoriums, das du änderst, und jede Prozessdatei, auf die der Benutzer dich hinweist, gewinnen, wo sie sich von dieser Fähigkeit unterscheiden.

Eine bereits erstellte Änderung. Wenn der Benutzer sagt, dass die Änderung bereits umgesetzt ist, dann ist das, was umgesetzt wurde, der Ansatz, und die Ship-Nachricht ist die erste Zustimmung: sende keinen Explainer und führe kein Hin und Her durch. Anstelle von Schritt 2 und 3:

• Bestimme die Basis: Für einen nicht gemergten Branch ist es der Merge-Base mit dem Branch, in den er gemergt wird, ermittelt nach seinem letzten Merge dieses Branches; sobald gemergt, der Commit vor der Änderung. Frage, wenn es nicht klar ist. Wenn die Änderung bereits gemergt ist, ist das Ziel der Ort, an den die Folge-Commits dieses Durchlaufs gehen; frage, wenn das nicht klar ist.
• Schreibe die Anfrage aus den Worten des Benutzers und dem, was die Änderung über sich selbst aussagt (Commit-Nachrichten, PR-Text), und markiere, was du abgeleitet hast.
• Finde die Checks, die auf einem Worktree der Basis fehlschlagen und auf der Änderung bestehen, beginnend mit den Tests, die die Änderung bereits hat (führe sie auf der Basis aus, wobei nur die Test- und Harness-Hunks der Änderung angewendet wurden), und schreibe nur einen für ein versprochenes Verhalten, das keiner von ihnen beweist; für eine Änderung ohne aufzuzeigenden Fehler, wie z. B. eine Beschleunigung oder ein Refactoring, einen Check dessen, was sie verspricht. Setze die Stufe wie Schritt 2. Behalte als Akzeptanzbasis, wie Schritt 4 sie behält, die wenigsten dieser Checks, die jedes Verhalten beweisen, das die Änderung verspricht, und notiere, welche nach der Änderung geschrieben wurden; die anderen Tests der Änderung bleiben offen für simplify.md.
• Schreibe den Ansatz wie umgesetzt in eine Datei: was sich geändert hat, die Begründung von design.md und seine strukturelle Frage, die für das Umsetzte beantwortet wurde, und den Fehlercheck von Schritt 3.

Fahre dann bei Schritt 4 fort, indem du zeigst, dass die Reproduktion bestanden hat, und gib dem Code-Loop diese Basis und diese Datei als seinen Ansatz. Die Ship-Nachricht sagt, dass kein Explainer genehmigt wurde, und enthält alle strukturellen Alternativen und alle Erkenntnisse, die das ändern, was der Benutzer erhält.

2. Reproduzieren

Reproduziere bei einem Fehler den Fehler auf der Basis, bevor du einen Fix schreibst: einen Test, der fehlschlägt, und, wenn ein Benutzer den Fehler sehen kann, das laufende Produkt, das ihn zeigt, erfasst wie capture.md sagt, von Hand, wenn der Verify-Flow noch nicht erfassen kann. Für ein Feature schreibe, was der Benutzer sehen oder tun können sollte. Wenn du einen Fehler nicht reproduzieren kannst, teile dies dem Benutzer mit, bevor du einen Fix erstellst, und schreibe alles, was du darüber sagst, als „durch Lesen des Codes (nicht versucht)“. Ein Check, der nichts findet, zählt nur, wenn du ihn gesehen hast, wie er das Ding findet, wenn es da ist.

Baue keine Absicherung für einen Fehlerpfad, den du nicht reproduziert hast; führe ihn stattdessen im Explainer als Folge auf.

Reproduziere und beweise durch die Verify-Fähigkeit des Repositoriums: .agents/skills/verify/ im Repositorium oder wo die AGENTS.md des Repositoriums sie platziert. Wenn es keine gibt oder sie den benötigten Flow nicht abdeckt, reproduziere von Hand und mache den Aufbau dieser Abdeckung mit der make-verifiable-Fähigkeit zu einem Teil des Ansatzes.

Setze dann die Stufe. Voll wenn das geänderte Verhalten Persistenz, Parallelität, Autorisierung, Migrationen, einen öffentlichen Vertrag, destruktive Effekte oder gemeinsamen Zustandsbesitz erreicht, oder wenn du noch nicht sagen kannst, wie der geänderte Code erreicht wird oder wie gut Tests ihn abdecken; beurteile anhand der Aufrufer und Zustandsschreiber, die du findest, nicht anhand von Dateinamen. Leicht sonst. Ein leichter Durchlauf, der eines davon aufdeckt, wird voll.

3. Design und der Explainer

Lies design.md und tue, was es verlangt, bevor du einen Ansatz wählst. Gehe in einem vollen Durchlauf mit dem Modell zum Ansatz hin und her (die back-and-forth-Fähigkeit), mit den Proportionenschätzungen von design.md in seinem Kontext als Prämissen, die überprüft werden sollen, und einer kleineren Version und keiner Änderung unter den Optionen; in einem leichten Durchlauf tue dies nur, wenn die Trigger von design.md ausgelöst werden oder die starken Ansätze sich wesentlich unterscheiden, und schreibe andernfalls den Ansatz selbst. Gib dem Runner im Kontext deine Begründung mit ihren Referenzen, was du reproduziert hast und was du nur gelesen hast, und einen Pfad für seine Aufzeichnung im Scratchpad oder Temp-Ordner der Sitzung; in der Frage, die du aus der Anfrage schreibst, frage auch, wo die Änderung landet, einschließlich Aufrufer und Geschwisterfälle, der Akzeptanzfälle, und was sie dir überlässt. Wenn eine Designfrage eine Tatsache ist, die du durch Ausführen von etwas beobachten könntest, kläre sie mit einem Wegwerfexperiment in einem isolierten Checkout oder Scratch-Daten, nicht durch Fragen des Benutzers; das Experiment liefert nichts aus.

Schreibe dann den Fehlercheck: Gehe die Bedingungen im Kurzheader der code-loop-Fähigkeit durch, plus die, die sich auf das Verhalten verlassen haben, das du änderst, und nenne für jede, die zutrifft, den Test, der sie abdecken wird, oder die Einschränkung, die du akzeptierst.

Sende dem Benutzer den Explainer, in einfacher Sprache, unter diesen Überschriften, in dieser Reihenfolge. Sage jede Sache einmal.

• Das Problem: Was ein Benutzer heute sieht, wer es trifft und wie oft (beobachtet oder geschätzt; keine Berichte bedeutet unbekannt, nicht selten), warum es wichtig ist, und deine Reproduktion mit ihrer Aufnahme, wenn sie eine hat; für ein Feature, was heute fehlt. Wenn der Benutzer nach der Änderung gefragt hat, eröffne mit seinen Worten.
• Warum es passiert: Die Ursache in einfachen Worten; für ein Feature, was heute im Weg steht. Lasse diese Überschrift für ein Feature weg, wenn nichts im Weg steht.
• Was sich ändert: Was der Benutzer sehen oder überprüfen können wird, wenn es erledigt ist, und was außerhalb des Geltungsbereichs liegt. Wenn etwas, das die Arbeit ändern würde, fehlt, frage hier danach.
• Der Ansatz: Was sich im Code ändert und wo, wie du es beweisen wirst, einschließlich aller make-verifiable-Arbeit und welche Checks mit der Änderung ausgeliefert werden oder als Beweis bleiben, was es kostet, es auszuliefern und zu behalten und warum das die Reichweite und den Schaden unter „Das Problem“ wert ist, und die Fehlercheck-Einträge, um die sich ein Reviewer kümmern würde.
• Erwogene Alternativen: Jede starke Alternative, die strukturelle Option von design.md darunter, wann immer eine glaubwürdige existiert, jede mit dem Grund, warum sie verloren hat.
• Was ein Reviewer fragen könnte: Jede wahrscheinliche Frage mit ihrer Antwort.

Halte dann an: Baue nichts, bis der Benutzer zustimmt. Eine klare Zustimmung in beliebigen Worten lässt dich bauen. Alles andere geht Wort für Wort in dasselbe Hin und Her als weitere Austauschrunde, über sein Austauschlimit hinaus, und kommt als überarbeiteter Explainer zurück; halte wieder an. In einem leichten Durchlauf ohne Hin und Her überarbeite den Explainer selbst und halte wieder an.

Die Zustimmung deckt den Explainer ab, wie er geschrieben ist. Wenn ein Test, eine Demo oder ein Review ändert, was der Benutzer erhält, sein sichtbares Verhalten, seine Kompatibilität, seinen Geltungsbereich, die Aktion, die du ergreifen wirst, um es auszuliefern, oder einen Kompromiss, den der Explainer akzeptiert hat, zitiere den Satz, den es falsifiziert, arbeite es mit dem Modell aus, sende einen überarbeiteten Explainer, der sagt, was sich geändert hat, und halte wieder an. Kleinere Entdeckungen, wie die Verwendung eines anderen internen Helfers, gehen in die Ship-Nachricht unter „was sich seitdem geändert hat“.

4. Bauen und beweisen

Bevor du das Verhalten änderst, behalte die Reproduktion und jeden Akzeptanzcheck, der ausgeführt werden kann, bevor die Änderung existiert: committe diejenigen, die der Explainer ausliefert, und speichere den Rest, oder alle, wenn nichts committet wird, als Patch außerhalb des Repositoriums. Zusammen sind sie die Akzeptanzbasis, und alles wird erneut am endgültigen Kandidaten ausgeführt: Jede spätere Bearbeitung daran geht an den Code-Loop und die Ship-Nachricht mit seinem Diff und ob es das versprochene Verhalten ändert.

Baue den genehmigten Ansatz in der Reihenfolge, die design.md festlegt. Wenn die Änderung einen Flow ändert, den die Verify-Fähigkeit abdeckt, aktualisiere diesen Flow in derselben Änderung. Zeige, dass die Reproduktion aus Schritt 2 bestanden hat, durch die Verify-Fähigkeit und im laufenden Produkt, wenn der Benutzer es sehen kann. Vereinfache dann den Diff wie simplify.md sagt. Führe dann einen Code-Loop mit dem Modell zum gesamten Diff durch (die code-loop-Fähigkeit), wobei du die Anfrage des Benutzers (oder die Kurzfassung, die dafür steht) als Request, den Explainer als Approach (mit der Aufzeichnung des Runners, wenn es eine gibt), die Akzeptanzbasis als Acceptance und die Stufe übergibst.

Am endgültigen Kandidaten, wenn ein Benutzer sehen oder tun kann, was sich geändert hat, erfasse es durch den Verify-Flow, erweitere den Flow mit make-verifiable, wenn er es nicht kann, und erfasse bei einem Fehler dasselbe Szenario auf der Basis durch denselben Flow, sodass Vorher und Nachher übereinstimmen. Wähle, erstelle und überprüfe die Aufnahme, wie capture.md sagt, und überprüfe, dass sie zeigt, was du sagen wirst, dass sie zeigt. Eine Aufnahme zeigt die Änderung und die Checks beweisen sie, daher steht eine Aufnahme der Basis oder eines fehlgeschlagenen Durchlaufs niemals als Bestehen. Eine Änderung, bei der es nichts zu sehen gibt, erhält keine Aufnahme.

5. Ausarbeitung

Entwerfe den PR-, Issue- oder Release-Text aus den Vorlagen des Projekts, mit den Aufnahmen dort, wo die Vorlage Platz dafür hat, oder unter einer eigenen Überschrift. Auf GitHub füge sie bei der Veröffentlichung mit gh pr create --attach (oder gh pr edit) an, es sei denn, das Repositorium hat sein eigenes Werkzeug; wenn es mit einem Fehler beendet wird, suche nach dem PR, bevor du es erneut versuchst, da er möglicherweise bereits existiert. Bevor öffentlicher Text, der eine Tatsache behauptet, herausgeht (eine Beschreibung, eine Antwort, ein Status-Update), überprüft ein frischer Reviewer des Modells ihn gegen die Beweise, die Aufnahmen (eine Aufnahme als seine Frames und Tempobericht) und den Diff: jede Behauptung wahr und untermauert, jedes abgehakte Kästchen wahr. Streiche eine Behauptung, die die Beweise nicht untermauern; schränke sie nicht ein.

Führe vor jedem Push den Check hinter jedem abgehakten Kästchen und jeder Behauptung erneut aus und wiederhole jede Aufnahme, die die seitdem erfolgte Änderung beeinträchtigen könnte.

6. Ship-Nachricht

Sende dem Benutzer: eine zwei- oder dreisätzige Zusammenfassung des Explainers, was sich seitdem geändert hat, die Beweise, die Aufnahmen, die Ausarbeitung, den Diff und die genaue Aktion, die du nach Zustimmung ergreifen wirst. Wenn der Code-Loop mit ungelösten Streitigkeiten endete, leite mit ihnen ein: jede Behauptung, was jede Seite gezeigt hat und was mit der Zustimmung ausgeliefert wird. Bevor du sie sendest, wiederhole den Überlappungscheck von design.md. Halte an, bis der Benutzer zustimmt.

7. Durch bis zum Ziel

Führe die genehmigte Aktion aus und bringe dann die Änderung an ihr Ziel:

• Vor jedem Push und vor dem Reagieren auf eine Benachrichtigung hole den Remote-Head und überprüfe den aktuellen Status der Änderung. Baue auf den Pushes anderer auf, indem du Bäume und nicht Commit-Hashes vergleichst; ersetze ihre Arbeit nicht mit einer veralteten lokalen Version. Wenn die Änderung landet, geschlossen oder durch die Version eines anderen ersetzt wird, vergleiche, was am Ziel angekommen ist, mit deinem letzten verifizierten Head und offenen Erkenntnissen. Berichte, was anders ist oder es nicht geschafft hat, ohne etwas wieder hinzuzufügen, das sie absichtlich entfernt haben.
• Jeder Review-Befund, inline oder im Text eines Reviews, vollständig gelesen, erhält einen Fix oder einen einzeiligen Grund; einer, der auch auf der Basis auftritt, wird beurteilt wie code-loop einen bereits bestehenden Befund beurteilt. Ein Fix, der das Verhalten ändert, erhält einen Code-Loop.
• Wenn eine Tatsache geposteten Text als falsch beweist, korrigiere den Text.
• Eine Anfrage, die den Geltungsbereich oder den Ansatz ändert, geht zurück zu Schritt 3 und, sobald gebaut, zu einer neuen Ship-Nachricht; eine, die über diese Änderung hinaus gilt, geht an den Benutzer, wenn sie eintrifft, mit ihrem Link: sie hier zu erledigen, erledigt sie nicht woanders.
• Für ein Deployment führe den Verify-Flow gegen das Deployte aus.

8. Lehren

Wenn der Benutzer, ein PR-Reviewer oder etwas nach dem Ausliefern ein Problem erkannt hat, das der Code-Loop übersehen hat, oder der Code-Loop einen Blocker gefunden hat oder hätte finden sollen, füge einen Eintrag zu .agents/lessons/log.md in dem Repositorium hinzu, das du geändert hast; für ein Repositorium, das dem Benutzer nicht gehört, in dem Ordner, der seinen Prozess dafür enthält. Jeder Eintrag: das Datum, die Änderung, was erkannt wurde und von wem, das Modul, die Fehlerklasse und die Ursache.

Lies dann das Log. Eine Lehre, die ein Check abfangen könnte, zweimal gesehen, wird zu einem Lint-, Typ-, Test- oder Verify-Check; eine, die Urteilsvermögen erfordert, zweimal gesehen, wird zu einer Zeile in der AGENTS.md des Repositoriums; zwei Einträge in einem Modul oder zwei einer Fehlerklasse in beliebigen Modulen (wie z. B. Zustand, den eine andere Operation während eines Await ändert), werden zu einer strukturellen Frage, die die gemeinsame Ursache benennt, bevor ein Refactoring vorgeschlagen wird. Liste jede als Folge in deiner abschließenden Nachricht auf; ein Refactoring läuft als eigenes see-it-through.

Erledigt, wenn die Änderung an ihrem Ziel ist oder wenn du den genauen Blocker und was übrig ist gemeldet hast und der Lehreneintrag, falls fällig, geschrieben ist.