steve-swanson/review-work

Review Work

Dieser Skill reviewed Code, zeigt die Ergebnisse auf einer lokalen Webseite an und korrigiert nur das, was der Benutzer genehmigt. Alle genehmigten Korrekturen landen in einem Branch und werden in einem einzigen Pull-Request (PR) ausgeliefert.

Der Hauptagent (der Chat, der diesen Skill ausführt) ist verantwortlich. Er legt den Umfang fest, wählt das Modell für jeden Helfer-Agenten aus, speichert alle Aufzeichnungen und überprüft alle Ergebnisse. Helfer-Agenten erledigen die ihnen zugewiesene Aufgabe und berichten zurück.

Dieser Skill arbeitet neben plan-work und execute-work. Er ruft sie nicht auf oder ändert sie.

Hier verwendete Begriffe

• Reviewter-Branch: der Branch, der reviewed wird. Der PR geht zurück in diesen Branch. Es ist nicht immer develop.
• Reviewter-Commit: der genaue Commit-SHA, der reviewed wurde. Jeder Befund zeigt darauf.
• Befund: ein Problem oder eine Frage aus dem Review, mit einer ID wie R001.
• Seite: die lokale Webseite, auf der der Benutzer für jeden Befund Fix, Don't fix oder Clarify auswählt.
• Batch: die Auswahlen, die mit einem Klick auf Submit gesendet werden.
• Worktree: ein zusätzlicher Checkout desselben Repositorys in einem eigenen Ordner.
• Koordinator-Branch: der eine Branch (mit eigenem Worktree), der alle Korrekturen sammelt. Er wird zum PR. Benennen Sie ihn im Conventional-Branch-Stil, <type>/<short-description>, in Kleinbuchstaben mit Bindestrichen. Korrekturen aus Reviews sind normalerweise fix/, z. B. fix/session-recovery; verwenden Sie refactor/, perf/, docs/, test/ oder chore/, wenn dies besser zu allen Korrekturen passt. Wenn der Benutzer oder das Repository eine andere Konvention nennt (z. B. in AGENTS.md), folgen Sie dieser. Setzen Sie niemals integration in den Namen.
• Aufgaben-Branch: ein kurzlebiger Branch und Worktree, in dem ein Helfer eine Korrektur vornimmt.
• Fast-Forward-Merge: ein Merge, der den Branch nur vorwärts bewegt und keinen Merge-Commit hinzufügt (git merge --ff-only).
• Run-eigen: von diesem Review-Durchlauf erstellt. Die Bereinigung berührt nur Run-eigene Branches und Worktrees. Ein passender Name ist kein Eigentumsnachweis.

Was der Benutzer erlaubt hat

• Das Starten dieses Skills erlaubt Review-Aufzeichnungen und den lokalen Seitendienst.
• Die Wahl, die Seite auf einem anderen verknüpften Rechner anzuzeigen, erlaubt einen Seiten-Host-Thread auf diesem Rechner in einem T3-Projekt namens Review-work pages (erstellt, falls nicht vorhanden). Es führt nur die review-work-CLI aus. Es berührt niemals Code dort. Wenn das Review abgeschlossen ist, sind das Beenden dieses Threads und das Löschen des Review-work pages-Projekts (das seine Chats löscht) erlaubt, wie in remote-page.md. Löschen Sie niemals ein anderes Projekt. Dieser Review-Chat befindet sich nie in diesem Projekt: Er bleibt bestehen und erhält den endgültigen Bericht.
• Das Einreichen von Fix (auf der Seite oder ein klares "fix it" im Chat) erlaubt Aufgaben-Worktrees, Commits, Merges in den Koordinator-Branch, sichere Bereinigung, Push und einen bereiten PR zur Überprüfung. Es erlaubt auch, diesen PR auf seinen Merge zu überwachen und dann den unveränderten, gemergten Koordinator-Worktree und lokalen Branch dieses Durchlaufs auf dem Review-Rechner zu entfernen.
• Wenn der Benutzer "local only" oder "no PR" sagt, folgen Sie dem.
• Mergen Sie niemals den PR, aktivieren Sie Auto-Merge oder führen Sie ein Deployment durch.

Schritt 1: Festlegen, was reviewed werden soll

1. Lesen Sie die Anweisungen, Anforderungen, den Status, die Branches und Worktrees des Repositorys. Lassen Sie uncommittete Änderungen und andere Durchläufe in Ruhe.
2. Zeichnen Sie den Repository-Pfad, den gemeinsamen Git-Ordner, den Branch, die Basis, den reviewed Commit-SHA, den Host (Rechnername) und die Chat-ID auf.
3. Reviewen Sie nur committed Code mit git show, Diffs oder einem sauberen verwalteten Checkout. Uncommittete Dateien sind nicht Teil des Reviews.
4. Wählen Sie den Umfang:
   • Feature-Branch: Reviewen Sie seinen Diff von seiner Basis. Ermitteln Sie die Basis vom Benutzer, aus Projektregeln oder PR-Metadaten. Wenn es noch unklar ist, fragen Sie.
   • develop: Reviewen Sie den gesamten aktuellen Code. Erfinden Sie kein Startdatum oder Start-Commit.
5. Fragen Sie "Inline or subagent fanout?" es sei denn, der Benutzer hat es bereits gesagt.
   • Inline: der Hauptagent reviewt selbst. Korrekturen verwenden immer noch Helfer.
   • Fanout: Helfer reviewen parallel. Fragen Sie nach den meisten Helfern auf einmal und schlagen Sie eine Anzahl basierend auf den nützlichen unabhängigen Bereichen vor. Bieten Sie Auto an: so viele nützliche Helfer, wie die Kapazität erlaubt. Wenn die Kapazität unbekannt ist, sagen Sie, dass das Limit 4 ist. Warten Sie auf die restlichen.
6. Bevor Sie einen Worktree erstellen, speichern Sie eine Momentaufnahme der aktuellen Worktrees, lokalen Branches und verwalteten Anhänge. Führen Sie eine Liste jedes Worktrees, den dieser Durchlauf erstellt: Reviewer, Fixer, Helfer, Wiederholungen und ihre Kinder, auch unveränderte oder aufgegebene. Siehe cleanup.md.

Schritt 2: Starten der Review-Aufzeichnungen

• Verwenden Sie Node 24+ und scripts/review.mjs aus diesem Skill. Befehle sind in runtime.md.
• Führen Sie init einmal aus, mit einer JSON-Eingabedatei, die außerhalb des Projekts aufbewahrt wird. Speichern Sie den zurückgegebenen Review-Ordnerpfad und verwenden Sie ihn wieder. Erstellen Sie bei der Wiederaufnahme niemals einen neuen Durchlauf.
• Aufzeichnungen leben in <home>/.agents/state/review-work/. Die Runtime erstellt ihre .gitignore, bevor andere Dateien dort sind, sodass Git sie nie aufnimmt.
• Die Identität eines Repositorys ist seine bereinigte Remote-URL plus sein tatsächlicher gemeinsamer Git-Ordner. Verknüpfte Worktrees eines Klons teilen eine Identität; separate Klone tun dies nicht. Jeder Durchlauf hat auch seine eigene ID, sodass gleichzeitig laufende Reviews nicht vermischt werden.
• Nur der Hauptagent und sein Seitendienst schreiben die Aufzeichnungen. Kopieren Sie niemals die Datenbank, den Dienst oder den Zustand in einen Worktree oder .worktreeinclude. Helfer geben Ergebnisse zurück, und der Hauptagent speichert sie. Helfer legen große Dateien in ihrem eigenen Temp-Ordner ab; der Hauptagent importiert sie.

Schritt 3: Modelle auswählen, dann reviewen

Lesen Sie zuerst routing.md.

• Der Hauptagent wählt das genaue Modell und den Aufwand für jede Review- und Fix-Aufgabe aus. Er überprüft, dass der Host sie anbietet, und zeichnet die Auswahl auf, bevor er die Aufgabe startet. Helfer rufen niemals Jev auf oder wählen Routen (Modell, Aufwand oder Optionen). Sie starten niemals ihre eigenen Helfer, es sei denn, der Hauptagent gibt ihnen eine genaue, feste Zuweisung.
• Bleiben Sie in der Modellfamilie des Chats: GPT-Modelle in einem GPT-Chat; Claude Opus, Sonnet oder Haiku in einem Claude-Chat.
• Immer die neueste Version. Modelle werden nach Stufennamen ausgewählt (Astra, Sol, Terra, Opus, Sonnet, Haiku). Für jede Stufe behält die Runtime nur die neueste Version in der Modellliste des Hosts und lehnt ältere ab. Wählen Sie niemals eine Version aus dem Gedächtnis. Vertrauen Sie der Modellliste des Hosts mehr als Schätzungen. Erfinden Sie niemals eine Modell-ID oder wechseln Sie stillschweigend den Anbieter. Wenn die Familie unbekannt ist oder ein benötigtes Modell fehlt, fragen Sie.
• Jev kann zuerst das Modell auswählen, dann einen Aufwand, den dieses Modell unterstützt. Es benötigt einen Schlüssel. Finden Sie ihn mit der Credential-Discovery der Runtime, niemals, indem Sie die Datei selbst öffnen. Die Discovery überprüft zuerst <home>/.config/jev/credentials.env (TYPESAFE_API_KEY ist der empfohlene Name). Wenn kein nutzbarer Home-Schlüssel existiert, überprüfen Sie die tatsächliche Env-Ladereihenfolge des Projekts und seine konfigurierten Adapter, und übergeben Sie dann diese Env-Dateipfade. Drucken, speichern oder sourcen Sie niemals Schlüsseldateien oder Schlüsselwerte. Die vollständige Lookup-Reihenfolge ist in routing.md.
• Ein konfigurierter Jev-MCP-Adapter kann dieselben beiden Auswahlen treffen. Lesen Sie zuerst sein tatsächliches Tool-Schema; nehmen Sie nicht an, dass ein jev_route-Tool existiert. Ohne einen Adapter verwenden Sie den integrierten direkten Transport der Runtime.
• Aufwandsgrenzen, für jedes Modell: Reviews und Planung gehen bis zu extra-high, niemals max oder ultra. Korrekturen gehen bis zu High. Die Runtime lehnt jede Route über der Grenze ab, von Jev oder von Main.
• Wenn Jev fehlt oder eine nicht verwendbare Antwort gibt, entscheidet der Hauptagent mit denselben Regeln. Es gibt keine feste Fallback-Tabelle.
  • Nur lesende Auflistungsarbeit: Low ist in Ordnung.
  • Algorithmen oder schwieriges Denken: High oder extra-high.
  • Nicht sicher: High.
  • Sicherheits-Review und Planung (Login, Berechtigungen, Geheimnisse, Krypto, Mandantentrennung, Vertrauensgrenzen): neuestes GPT Astra oder neuestes Claude Opus, auf extra-high. Wenn dieses Modell kein extra-high hat, verwenden Sie dasselbe Modell auf seiner höchsten Stufe unterhalb der Grenze (mindestens High). Wechseln Sie nicht zu einer älteren Version. Wenn ein Helfer einen neuen Sicherheitsbereich findet, stoppt er diesen Teil und meldet ihn an Main. Geplante Implementierung verwendet die Fix-Routen unten, einschließlich Sicherheits-Fixes.
  • Inline-Review, wenn ein Teil davon eine höhere Route benötigt: bitten Sie den Benutzer nicht, das Modell oder den Aufwand dieses Chats zu ändern. Dieser Chat kann seinen eigenen Aufwand nicht bestätigen oder setzen. Geben Sie diesen Teil (z. B. die Sicherheitsprüfungen) an einen Review-Helfer und setzen Sie das genaue Modell und den Aufwand des Helfers, wenn Sie ihn starten (in Claude Code, das Modell und den Aufwand des Agenten-Tools; in T3, die Optionen von delegate_task). Zeichnen Sie zuerst die Route auf. Der Helfer gibt Befunde zurück; der Hauptagent speichert sie. Fragen Sie den Benutzer nur, wenn der Host keinen Helfer mit dem erforderlichen Modell und Aufwand starten kann: Erklären Sie dann die Lücke und bieten Sie an, das Modell dieses Chats zu behalten. Zeichnen Sie diese Wahl einmal für dieses Review auf und fragen Sie nicht erneut. Dies senkt niemals die Regel für Fanout-Helfer.
• Teilen Sie das Review nach Verhalten und nach Dateien auf. Folgen Sie Abläufen über Dateien hinweg. Suchen Sie nach Wegen, wie der Code kaputt geht: falsche Ergebnisse, gebrochene Regeln, verlorene Daten, fehlende Prüfungen und Kompatibilitätsbrüche. Überprüfen Sie jedes Anliegen gegen die Anforderungen und den Code, der tatsächlich läuft. Führen Sie Duplikate zusammen.
• Zeichnen Sie die Abdeckung auf: was Sie überprüft, übersprungen und nicht abschließen konnten, mit Pfaden, SHA, Grund und Beweis. "Keine Befunde" bedeutet nicht, dass jede Datei überprüft wurde. Nennen Sie das Review nicht abgeschlossen, während wichtige Abdeckung nicht berücksichtigt ist (nicht als überprüft, übersprungen oder nicht abgeschlossen aufgezeichnet).

Schritt 4: Befunde schreiben, die Leute verstehen können

Der Benutzer entscheidet allein aus dem Befundtext, daher muss der Text kurz, genau und klar sein. Lesen Sie writing-findings.md. Geben Sie seinen Pfad jedem Review-Helfer und sagen Sie ihm, er solle ihn befolgen.

Verwenden Sie Labels der Conventional Comments wie issue, question, suggestion und nitpick. Markieren Sie jeden Befund als blocking oder non-blocking. Jeder Befund hat vier Teile:

• Titel: Was schief läuft, als klarer Satz von 80 Zeichen oder weniger. "Retrying a payment can create two invoices", nicht "Non-idempotent invoice creation path".
• Warum es wichtig ist (discussion): wer oder was verletzt wird, wann und wie oft.
• Beweis (evidence, plus optional einen Code-excerpt): path:line, der Codepfad oder die Schritte und woher Sie es wissen.
• Fix-Idee (suggestion): beginnt mit Small fix, Medium fix oder Large fix, sagt dann, was geändert werden soll.

Wenn Sie sich nicht sicher sind, schreiben Sie eine question. Präsentieren Sie niemals eine Schätzung als bestätigtes issue. Geben Sie jedem Befund eine stabile ID, den Pfad und die Zeile sowie den reviewed SHA.

Bevor Sie Befunde laden, führen Sie die Klarheitsprüfung aus writing-findings.md an jedem durch. Schreiben Sie jeden, der durchfällt, neu und behalten Sie jede Tatsache.

Schritt 5: Seite anzeigen und Entscheidungen sammeln

1. Laden Sie die Befunde und die Abdeckung, dann starten Sie die Seite. Eine Seite dient dem gesamten Review, einschließlich späterer Runden.

2. Für jeden Befund wählt der Benutzer Fix, Don't fix oder Clarify aus und kann eine Notiz zu jedem hinzufügen. Auswahlen speichern als Entwürfe. Das Wechseln der Auswahl behält die Notiz.

3. Nur Submit sendet einen Batch. Teilweise Batches sind in Ordnung; unentschlossene Befunde bleiben offen. Eingereichte Auswahlen sind auf der Seite gesperrt. Änderungen finden im Chat statt.

4. Überprüfen Sie zuerst die Umgebung. Dieser Chat läuft in T3 Code, wenn seine Shell T3CODE_THREAD_ID oder T3CODE_CLI_PATH gesetzt hat oder wenn T3-Tools wie t3_environment_links verfügbar sind. Wenn nicht:

   • Zeigen Sie die Seite auf diesem Rechner an, mit deliveryMode: "terminal".
   • Überspringen Sie die Seiten-Host-Auswahl unten und bieten Sie keinen anderen Rechner an. Lesen Sie nicht remote-page.md.
   • Verwenden Sie die einfache Terminal-Formulierung in Punkt 5.

   In T3 wählen Sie, wo die Seite vom Ursprung des Chats aus angezeigt werden soll. Halten Sie dies getrennt von der Inline/Fanout-Wahl.

   • Beachten Sie eine bereits in diesem Chat getroffene explizite Seiten-Host-Wahl. Bei Wiederaufnahme verwenden Sie sie wieder; fragen Sie nur erneut, wenn der Benutzer sie ändert oder dieser Host nicht verfügbar ist.
   • Wenn der Chat lokal auf dem Review-Rechner gestartet wurde, zeigen Sie die Seite auf diesem Rechner ohne Nachfragen an. Stellen Sie dies aus der Aussage des Benutzers oder den vom Host bereitgestellten Client-Ursprungs-Metadaten fest, die das initiierende Gerät identifizieren. Der Hostname des Agenten, das Arbeitsverzeichnis, die Ausführungsumgebung oder creationSource (web, mobile oder mcp) allein beweist nicht, wo der Benutzer den Chat gestartet hat.
   • Wenn der Chat remote gestartet wurde oder sein Ursprung unsicher ist, fragen Sie einmal, wo die Seite angezeigt werden soll. Fragen Sie direkt nach dem Seiten-Host, ohne eine separate Frage, ob der Benutzer lokal ist. Rufen Sie t3_environment_links auf und bieten Sie diesen Rechner plus jeden erreichbaren verknüpften Rechner mit vollem Zugriff unter Verwendung ihrer tatsächlichen Bezeichnungen an. Lassen Sie keinen Rechner aufgrund seines Betriebssystems aus. Erklären Sie einen bekannten Fähigkeits-/Zugriffsblocker, anstatt einen Host stillschweigend zu verstecken. Wenn das Fragen-Tool nicht jede Auswahl aufnehmen kann, listen Sie alle berechtigten Hosts in der Frage auf und akzeptieren Sie einen Hostnamen.
   • Empfehlen Sie den Rechner des Benutzers, wenn er bekannt und berechtigt ist. Erklären Sie die Bildschirmsperre-Einschränkung nur, wenn sie die Auswahl beeinflusst: Der gestreamte Browser von T3 stoppt, wenn der Bildschirm des Review-Rechners gesperrt ist. Speichern Sie den ausgewählten Host und den Ursprungsbeweis (oder unknown) in den Review-Notizen.
   • Auf einem anderen Rechner: folgen Sie remote-page.md. Die Seite öffnet sich dort im eigenen Browser des Benutzers, und Submit sendet die Auswahlen zurück an diesen Chat. Es benötigt T3-Links mit vollem Zugriff. Es funktioniert, während dieser Rechner gesperrt ist.

5. Geben Sie immer den Host und den Seitenlink an.

   • In T3, auf diesem Rechner: der T3-Browser kann die Seite öffnen. Sagen Sie "Submit resumes this conversation automatically." Die Seite verwendet den lokalen Befehl t3 thread send. Es ist kein öffentlicher Webhook oder Tunnel erforderlich.
   • In T3, auf einem anderen Rechner: sagen Sie, welcher Rechner die Seite anzeigt, und "Submit sends your choices back to this chat."
   • In einem einfachen Terminal sagen Sie: ...

[truncated for translation]