Branch-Review-Tracker

Was macht Branch-Review-Tracker?

Eine Überprüfung eines Branches, die über mehrere Runden hinweg korrigiert wird. Jede Runde überprüft den Branch erneut und aktualisiert eine Seite: eine nummerierte Liste von Problemen, jedes mit einem Status und einem Detail-Popup, das den Nachweis, den verantwortlichen Commit und die Stellen zum Nachschlagen enthält.

Die Seite ist ein claude.ai-Artefakt und dient als Aufzeichnung der Überprüfung. Sie ist für Betrachter schreibgeschützt: Nur Claude ändert einen Status, während die Überprüfung und die Korrekturen fortschreiten. Eine neue Sitzung wird aus der kleinen context.json-Datei der Seite fortgesetzt, nicht aus der Konversation oder lokalen Dateien.

Der Tracker enthält drei Dateien:

• index.html: die Seite, eine Kopie von assets/tracker.html;
• issues.json: alle Probleme und das Sitzungsprotokoll;
• context.json: die Wiederaufnahme-Notizen und ein Index der Probleme für die nächste Sitzung, der Prompt, der sie startet, und die kurze Liste dessen, was auf den Benutzer wartet, was der einzige Teil ist, den die Seite anzeigt.

1. Fragen, was überprüft werden soll

Sammle zuerst Kandidaten und frage dann alles in einem AskUserQuestion-Aufruf. Überspringe eine Frage, deren Antwort bereits mit dem Aufruf gekommen ist, z. B. eine PR-Nummer oder URL.

git for-each-ref --sort=-committerdate --count=6 --format='%(refname:short)' refs/heads
git symbolic-ref --short refs/remotes/origin/HEAD      # der Standard-Basis-Branch
git log --format=%s <base>..<target> | grep -oE '[A-Z]+-[0-9]+' | sort -u
gh pr list --head <target> --json number,url,title     # oder: glab mr list --source-branch <target>

Frage	Optionen
Ziel-Branch	der PR-Head-Branch, wenn ein PR angegeben wurde; andernfalls die drei zuletzt aktualisierten lokalen Branches außer dem Basis-Branch
Basis-Branch	der Standard-Branch des Remotes (empfohlen), dann andere langlebige Branches, falls vorhanden
Ticket	IDs, die im Branchnamen und seinen Commit-Betreffen gefunden wurden; Kein Ticket

Der Benutzer kann immer einen anderen Wert eingeben. Stelle die Ticket-Frage, nachdem der Branch bekannt ist, oder leite ihre Optionen vom wahrscheinlichsten Ziel ab.

2. Überprüfe die Umgebung

Führe das Preflight-Skript aus und zeige dem Benutzer seine Tabelle:

<dieses skill>/scripts/preflight --target <branch> [--base <base>] [--ticket <id>]

Es überprüft das Repository, beide Referenzen, den Checkout des Benutzers, ob der lokale Branch mit dem PR-Head übereinstimmt, den PR auf dem Host, Checkout-Filter, die git worktree blockieren können, und die CLIs, die die Überprüfung verwendet. Exit-Code 2 bedeutet einen Blocker; 1 bedeutet nur Warnungen. Es überprüft nicht die Build-Tools des Projekts: Diese gehören zu den Hilfs-Skills des Projekts.

Das Skript holt beide Branches. Es nimmt den Basis-Branch von origin, wo er aktuell ist, und den Ziel-Branch vom Klon, wo der Autor ihn möglicherweise gepusht hat. Überprüfe gegen die Referenzen, die es ausgibt. Wenn es warnt, dass der lokale Branch vom PR-Head abweicht, überprüfe den PR-Head: Lese ihn mit git show <sha>:<path>, ohne ihn auszuchecken.

Überprüfe dann die Werkzeuge dieser Sitzung, die ein Skript nicht sehen kann, und füge sie zur Tabelle hinzu:

Benötigt für	Werkzeug	Ohne es
die Überprüfung	code-review-Skill oder das Agent-Werkzeug	Blocker
die Seite	Artifact-Werkzeug	Behalte die Dateien im Notizblock und gib dem Benutzer nach jeder Runde ihre Pfade an; sage dies
den Kontext des Tickets und das Erstellen von Tickets	Atlassian-Werkzeuge (getJiraIssue, createJiraIssue)	Überprüfung ohne; sage dies
die Kommentare und Checks des PR	gh oder glab, authentifiziert	Überprüfe nur den Branch; sage dies

Suche dann nach den Hilfs-Skills des Projekts, wie unten unter „Hilfs-Skills“ beschrieben, und füge eine Zeile pro Helfer zur Tabelle hinzu: gefunden, mit seinem Namen, oder fehlend, mit dem, was der Überprüfung fehlen wird.

Stoppe bei einem Blocker und sage, was fehlt. Gib bei Warnungen an, was die Überprüfung nicht abdecken wird, und fahre fort.

Wenn das Ticket gelesen werden kann, rufe seine Zusammenfassung und seinen Status ab. Schreibe einen Status in Klammern hinter die ID: PROJ-123 (in Bearbeitung).

3. Erste Runde

1. Überprüfung. Rufe code-review für <target> gegen <base> oder für die PR-Nummer auf. Sage dem Prüfer, er solle andere Commits mit git show <rev>:<path> lesen und niemals etwas im Verzeichnis des Benutzers auschecken.

2. Überprüfe die Prosa, wie unten unter „Die Prosa-Überprüfung“ beschrieben. code-review sucht nach Defekten im Code und deckt diese nicht ab.

3. Verifiziere jeden Fund, wie unten unter „Verifizierung von Befunden“ beschrieben. Ein Problem kommt erst nach diesem Schritt auf die Seite. Ein Fund, der ihn nicht übersteht, wird entweder fallengelassen, bevor er aufgelistet wird, oder, sobald er gelistet ist, auf dismissed gesetzt, mit seinem Grund.

4. Klassifiziere jedes Problem.

   • Der verantwortliche Commit: git log -S'<symbol>' <base>..<target> oder git blame -s <target> -- <path>.
   • Ob der Basis-Branch es auch hat: git show <base>:<path>. Ein Problem, das der Basis-Branch bereits hat, erhält "commitRole": "Pre-existing on" und "commit": "<base>". Es ist keine Regression des Branches, kann aber dennoch den Merge blockieren, wenn der Branch es verschlimmert, z. B. indem er mehr Daten dadurch offenlegt.
   • file:line für jede Stelle, beim überprüften Commit.

5. Schreibe den Tracker in den Notizblock der Sitzung, in einen Ordner, der nach dem Branch benannt ist (/ ersetzt durch -):

   • index.html: eine Kopie von assets/tracker.html, mit __TITLE__ ersetzt durch den Seitennamen. Der Name ist das Thema des Branches in zwei bis vier Wörtern, gefolgt von „Überprüfung“, z. B. API-Schlüssel-Autorisierungs-Überprüfung.
   • issues.json und context.json, wie unten unter „Die Datendateien“ beschrieben.

6. Validiere beide Dateien. Der Validator überprüft das Schema, dass jede Stelle beim überprüften Commit existiert und dass der Index in context.json mit den Problemen übereinstimmt:

   python3 -I <dieses skill>/scripts/validate-issues.py <verz>/issues.json --repo <repo>
   

7. Veröffentliche mit der publish-Aktion des Artifact-Werkzeugs, file_path gesetzt auf <verz>/index.html, files gesetzt auf {"issues.json": "<verz>/issues.json", "context.json": "<verz>/context.json"}, icon: "checklist" und einer ein-Satz-description. Schreibe die zurückgegebene URL in beide Dateien ("artifact"), veröffentliche erneut und gib dem Benutzer den Link.

4. Nachfolgende Runden

Führe eine Runde aus, wenn der Benutzer sagt, dass der Branch aktualisiert wurde, oder um eine erneute Überprüfung bittet.

1. Bestätige, dass der Branch sich bewegt hat. Vergleiche den PR-Head oder die Ziel-Referenz mit reviewed und sieh dir git reflog -3 --date=iso <target> an. Ein Push kann spät eintreffen, und der lokale Branch des Benutzers kann hinter dem PR hinterherhinken. Wenn sich nichts bewegt hat, sage dies und stoppe.
2. Hole den Basis-Branch (git fetch origin <base>). Wenn sich der Basis-Branch bewegt hat, notiere es und vergleiche den Branch mit git range-diff <old-base>..<old-tip> <new-base>..<new-tip>.
3. Sieh, was sich geändert hat:
   • git range-diff <base>..<reviewed> <base>..<target> zeigt, welche Commits umgeschrieben, hinzugefügt oder entfernt wurden;
   • git diff <reviewed> <target> zeigt die Nettoänderung;
   • die neuen Kommentare, Bewertungen und Checks des PR (gh pr view <n> --json comments,reviews, gh api repos/<owner>/<repo>/pulls/<n>/comments, gh pr checks <n>).
4. Bewerte jede Korrektur. Lies für jedes Problem, das die Änderung adressiert, die Korrektur und zeichne in fix auf, was sie tut und wie sich der Code jetzt verhält. Setze fixed nur, wenn das Lesen es bestätigt, und sage in verified, wie weit es verifiziert wurde.
5. Suche nach Problemen, die die Korrekturen verursachen. Eine Korrektur verschiebt das Problem oft, anstatt es zu beseitigen. Überprüfe die Eingaben, die der alte Code zufällig verarbeitet hat:
   • einen fehlenden, leeren oder null-Wert, z. B. eine Eigenschaft, die ein Client nicht setzt, die früher ein harmloses Literal erzeugte und jetzt „keine Einschränkung“ bedeutet;
   • Standardwerte, auf die ein Wert zurückfällt;
   • Codepfade, die die Änderung erreicht, ohne sie zu berühren, wie Aufrufer, andere Endpunkte, ältere Clients und die Importseite eines Exports;
   • Verhalten, das die Änderung für Anfragen ändert, die sie nicht betraf. Füge jedes Problem als neues Problem hinzu und notiere die Korrektur, die es verursacht hat, bei beiden Problemen. Führe „Die Prosa-Überprüfung“ für die Nettoänderung durch.
6. Bewerte jedes Problem, das nicht behoben ist, neu gegen den neuen Code und sieh dir erneut die behobenen an, deren Code sich geändert hat.
7. Führe Tests nur so aus, wie unten unter „Reproduzieren mit Tests“ erlaubt.
8. Aktualisiere den Tracker, wie unten unter „Den Tracker aktuell halten“ beschrieben:
   • Setze reviewed auf die neue Spitze.
   • Schreibe commits auf die neuen Hashes um. Ein umgeschriebener Commit erhält seinen neuen Hash; ein entfernter verlässt die Map; ein neuer wird hinzugefügt.
   • Ändere status, commit, commitRole, note, fix und detail der Probleme, die sich geändert haben.
   • Finde die Zeile jeder Stelle an der neuen Spitze mit git grep -n neu. Verschiebe keine Zeilen durch Arithmetik.
   • Hänge neue Probleme mit der nächsten freien Nummer an. Renummeriere niemals.
9. Validiere, dann veröffentliche erneut an dieselbe URL.
10. Berichte dem Benutzer: was diese Runde behoben hat, was noch offen ist und was neu ist, mit Datei:Zeile und was ausgeführt wurde. Beende mit dem Seitenlink.

Verifizierung von Befunden

Lies den Code selbst beim überprüften Commit, bevor ein Problem auf die Seite kommt.

1. Verfolge das Szenario Ende-zu-Ende. Folge der Eingabe von dort, wo sie eintritt, bis dorthin, wo der Schaden auftritt, und benenne jeden Schritt mit Datei:Zeile. Ein Befund, der einen Schritt benötigt, den der Code nicht ausführt, wird verworfen, mit diesem Schritt als Grund.
2. Überprüfe die Vorbedingungen. Frage, wie der auslösende Zustand entstehen kann:
   • wer die Eingabe erstellen kann, z. B. über welche API, und ob ein Validator oder ein Standardwert sie stoppt;
   • ob ein konfigurierter Standardwert, wie eine unbegrenzte Lebensdauer oder eine Rolle, die zugewiesen wird, wenn keine angegeben ist, das Szenario unerreichbar macht oder es zum Normalfall macht;
   • ob vorhandene Daten es enthalten können. Wenn nur Daten außerhalb des Repositorys antworten können, verwende das Datenprüf-Hilfs-Skill des Projekts; ohne eines, frage den Benutzer, wie man es herausfindet. Zeichne die Antwort in verified und im Protokoll auf.
3. Trenne „beabsichtigt“ von „akzeptabel“. Ein Runbook, Test oder Codekommentar, der ein Verhalten als beabsichtigt zeigt, macht es nicht harmlos. Überprüfe die Rückwärtskompatibilität separat: vorhandene Clients und bereitgestellte Versionen, vorhandene Daten und Anbieter oder Benutzer, die die neue Funktion nie verwendet haben. Ein beabsichtigter Bruch eines vorhandenen Arbeitsablaufs ist ein Problem und ein Blocker, es sei denn, der Benutzer akzeptiert ihn.
4. Sage, wie es verifiziert wurde. Schreibe es in verified: „Durch einen Test auf Controllerebene reproduziert; die Dienstschicht wurde gestubbt“, „Aus dem Lesen des Codes; nicht ausgeführt“, „Datenprüfung: keine passenden Datensätze“. Berichte, was der Nachweis beweist, und nenne, was er nicht beweist. Behandle keinen kausalen oder vergleichenden Befund, den die Daten nicht zeigen.
5. Verwerfe mit einem Vermerk. Eine Verwerfung setzt status: "dismissed" und ein dismissal mit wem entschieden hat, wann und warum. Wenn Claude verwirft, sage dies und dass keine Person es abgezeichnet hat; die Seite zeigt es.
6. Öffne bei Anfechtung wieder. Wenn der Benutzer eine Verwerfung oder ein Urteil in Frage stellt, überprüfe es erneut anhand des Codes, anstatt es zu verteidigen. Wenn es falsch war, öffne das Problem wieder, entferne die Verwerfung und sage deutlich in note, was das frühere Urteil falsch gemacht hat.

Reproduzieren mit Tests

Führe Builds und Tests nur aus, wenn der Benutzer darum bittet oder wenn die Anweisungen des Repositorys und des Benutzers es ohne Fragen erlauben. Wie das Projekt gebaut und getestet wird, mit welcher Toolchain und welchen Einstellungen, kommt vom Build-und-Test-Hilfs-Skill des Projekts und seinen Anweisungen, nicht von diesem Skill.

1. Verwende niemals den Checkout des Benutzers. Lege den zu testenden Commit in einem separaten Verzeichnis ab:
   • git worktree add --detach <notizblock>/<name>-wt <sha>;
   • wenn etwas die Worktree blockiert, exportiere stattdessen den Commit, wobei die Pfade, die ihn blockieren, weggelassen werden: git archive <sha> -- . ':(exclude)<blockierter-pfad>' | tar -x -C <verz>. Beispielsweise schlägt ein git-crypt-Schmutzfilter bei verschlüsselten Pfaden fehl, wenn der Schlüssel nicht verfügbar ist. Das Preflight-Skript nennt die Pfade, die Checkout-Filter haben.
2. Baue und führe so aus, wie das Projekt es sagt. Ein Werkzeugfehler, wie eine Toolchain, die das Projekt nicht unterstützt, ist kein Testergebnis: Korrigiere die Umgebung, wie das Hilfs-Skill oder die Anweisungen des Projekts sagen, und führe dann erneut aus. Ohne ein Hilfs-Skill, frage den Benutzer, anstatt zu raten, und notiere, was für die Projektnotizen gelernt wurde.
3. Schreibe den Test so, dass er das korrekte Verhalten bestätigt. Ein Fehler reproduziert dann das Problem, und derselbe Test wird zum Regressionstest für die Korrektur. Steuere die echten Klassen entlang des Pfades und stubbe nur das, was das Szenario benötigt. Lasse jeden Stub widerspiegeln, was der echte Code tut, und nenne jede gestubbte oder nicht ausgeführte Schicht in verified, wie HTTP, die Sicherheitskette oder die Datenbank.
4. Führe die kleinste Menge aus: den neuen Test plus die Tests, die den geänderten Code abdecken.
5. Behalte die Testquelle im Tracker. Der Notizblock kann zwischen Sitzungen gelöscht werden. Veröffentliche den Test als tests/<Name>.<ext> in files, mit contentType: "text/plain", und nenne ihn im Problem.
6. Räume auf. Entferne die Worktree oder den Export und alle Build-Ausgaben, die ein Lauf im Checkout des Benutzers hinterlassen hat, wie kompilierte Testklassen, die ein späterer Build aufgreifen würde. Überprüfe dann, dass git status und git worktree list den Checkout des Benutzers unverändert zeigen.

Hilfs-Skills

Der Überprüfungsablauf ist für jedes Projekt gleich; was das Projekt weiß, lebt in seinen eigenen Skills. Verwende sie, wenn sie existieren; dieses Skill kodiert niemals Projektwerkzeuge fest.

Finde sie in dieser Sitzungsliste der verfügbaren Skills anhand ihrer Beschreibungen. Rate keine Namen. Lade eines mit dem Skill-Werkzeug, wenn der Schritt es benötigt.

Helfer	Verwendet für	Ohne es
Überprüfungs-Checkliste	die Risikobereiche des Projekts: Sicherheitsmodell, Kompatibilitätsversprechen, API-Verträge, Migrationen	die Überprüfung stützt sich auf Allgemeinwissen; sage, welche Bereiche sie möglicherweise übersieht
Build und Test	Bauen und Testen eines Commits isoliert: Befehle, Toolchain, Einstellungen, bekannte Blocker	Tests werden nur ausgeführt, nachdem der Benutzer gefragt wurde, wie; Befunde bleiben „aus dem Lesen des Codes“
Datenprüfungen	Beantwortung von Fragen aus Daten außerhalb des Repositorys, sicher	der Benutzer wird gefragt, wie man es herausfindet
Prosaregeln	Kommentare, Docstrings, Changelogs, Commit-Nachrichten und PR-Text, wie z. B. eine generische

…

[Gekürzt für die Übersetzung]