merge-briefing

Was macht merge-briefing?

Überblick

Ein Merge ist ein irreversibler gemeinsamer Zustand und wird daher nur mit der expliziten, PR-spezifischen Antwort des Benutzers durchgeführt. Die Hürde ist formal günstig und leicht falsch zu erfüllen: Die ehrliche Version benötigt eine ausreichend breite Prüfung, um „nichts ist offen“ zu belegen, und die Oberfläche, auf der blockierende Befunde tatsächlich leben – Inline-Review-Threads – wird von einem natürlich wirkenden gh pr view --json comments,reviews-Aufruf stillschweigend ausgelassen.

Dieser Skill ist die On-Demand-Heimat für diese Prozedur. Die Pre-Merge Reporting-Regel (ETHOS.md → Regeln-Praxis trägt) hält die Hürde aufrecht; die sechsteilige Liste in Schritt 4 unten ist die Form des Berichts; die folgenden Schritte zeigen, wie man von „der PR sieht fertig aus“ zu einer Frage gelangt, die der Benutzer mit einem Wort beantworten kann.

Grundprinzip: Der Kurzbericht ist eine Behauptung über den Zustand des PR, daher wird jede Zeile darin zum Zeitpunkt der Erstellung geprüft – nicht aus der Zeit, als der PR geöffnet wurde.

Wann verwenden

• Kurz davor, den Benutzer um Genehmigung für einen Merge zu bitten.
• Ein Merge wurde angefordert, und Sie haben in dieser Runde noch keinen Kurzbericht vorgelegt.
• Erneutes Fragen, nachdem eine vorherige Frage unbeantwortet blieb oder nachdem CI/Review sich geändert hat.
• Ein begleitender, nachfolgender oder neu generierter PR ist in einem Cluster, den der Benutzer bereits einmal genehmigt hat, der Nächste.

Das eiserne Gesetz

• Ein PR, ein Kurzbericht, eine Antwort. Die Genehmigung von PR X genehmigt nur X. Die einzige Ausnahme ist der Stapel-Merge: eine Runde mit einem separaten Kurzberichtsabschnitt pro PR, eine Frage, die sie auflistet, und eine Antwort, die den aufgelisteten Satz genehmigt.
• Erstellen Sie den Kurzbericht aus den Prüfergebnissen dieser Runde. Ein CLEAN-Status zum Zeitpunkt des Eintritts ist nicht dauerhaft; ein veralteter Anker lässt den Benutzer einen Konflikt entdecken, den Sie hätten abfangen sollen.
• Führen Sie einen Merge niemals auf ein Fortschrittssignal durch. „계속“, „ok“, „진행“ treiben die Arbeit voran; sie sind keine Zustimmung zu einer Mutation des gemeinsamen Zustands.

Ablauf

Schritt 1: Alle drei Oberflächen prüfen

Befunde leben auf drei Oberflächen, und kein einziger Befehl deckt sie alle ab. Führen Sie alle drei aus, bevor Sie ein Wort des Kurzberichts schreiben.

# 1 — CI
gh pr checks <N> --repo <Inhaber>/<Repo>

# 2 — Konversationsverlauf + Bewertungstexte + Merge-Fähigkeit + gepushter HEAD
gh pr view <N> --repo <Inhaber>/<Repo> \
  --json mergeable,mergeStateStatus,isDraft,headRefOid,reviews,comments

# 3 — Inline-Review-Threads (die Oberfläche, die #2 NICHT enthält)
gh api graphql --paginate -f query='
query($owner:String!, $repo:String!, $pr:Int!, $endCursor:String) {
  repository(owner:$owner, name:$repo) {
    pullRequest(number:$pr) {
      reviewThreads(first:100, after:$endCursor) {
        pageInfo { hasNextPage endCursor }
        nodes {
          id isResolved isOutdated path line
          comments(first:1) { nodes { author { login } body } }
        }
      }
    }
  }
}' -F owner=<Inhaber> -F repo=<Repo> -F pr=<N> \
  --jq '.data.repository.pullRequest.reviewThreads.nodes[]
        | select(.isResolved | not)
        | {id, path, line, author: .comments.nodes[0].author.login,
           body: .comments.nodes[0].body}'

body ist in der Projektion enthalten, weil sich das Label im eigenen Text des Threads befindet und das Label das ist, womit Schritt 2 bewertet. --paginate mit $endCursor ist keine Dekoration – ein PR, an dem zwei Bots gearbeitet haben, übersteigt 100 Threads, und eine einzelne Seite lässt den Rest stillschweigend weg, was dann als „keine offenen Threads“ gelesen wird.

Oberfläche #2 kürzt ebenfalls bei 100 ab, und zwar stillschweigend. gh pr view --json comments,reviews gibt comments(first: 100) / reviews(first: 100) ohne Cursor-Variable aus, sodass bei einem PR, der einen der beiden Zähler überschreitet, das Ende einfach fehlt. Wenn einer von ihnen 100 Zeilen hat, sammeln Sie diese Oberfläche über den paginierten REST-Endpunkt erneut ein, bevor Sie bewerten:

gh api repos/<Inhaber>/<Repo>/pulls/<N>/reviews --paginate -q '.[] | {user: .user.login, state, body}'
gh api repos/<Inhaber>/<Repo>/issues/<N>/comments --paginate -q '.[] | {user: .user.login, body}'

Ein leeres Ergebnis ist noch keine Antwort. Es bedeutet gleichzeitig „keine offenen Threads“ und „die Abfrage ist falsch“, bis Sie gesehen haben, dass genau diese Abfrage Zeilen auf einem PR ausgibt, von dem bekannt ist, dass er welche hat. Führen Sie sie einmal gegen einen solchen PR aus; das ist die Positivkontrolle, auf der die Negativbehauptung beruht.

In einem Fork-Klon muss --repo bei jeder Prüfung den Fork benennen: Ein bloßer gh pr-Aufruf löst gegen das übergeordnete Repo auf (siehe worktree-merge-cleanup → Pre-Call-Checkliste).

Wenn CI ausstehend oder fehlschlägt, stoppen Sie hier – fragen Sie noch nicht. Ein Kurzbericht, dessen Verifizierungszeilen sich noch bewegen, fordert den Benutzer auf, eine Schätzung zu genehmigen.

Lesen Sie, welchen Commit jede menschliche Genehmigung abdeckt, bevor Sie „genehmigt“ schreiben: reviewDecision: APPROVED überlebt spätere Pushe. Gruppieren Sie die Bewertungen nach Prüfer und nehmen Sie die letzte APPROVED-Bewertung jedes Prüfers (eine frühere Genehmigung wird durch eine erneute Genehmigung ersetzt; ein späteres CHANGES_REQUESTED oder DISMISSED vom selben Prüfer bedeutet keine aktuelle Genehmigung). Vergleichen Sie die commit_id dieser Bewertung mit headRefOid und listen Sie die Nicht-Merge-Commits danach auf (git log --no-merges <commit_id>..<head>) in Teil 5 als „nicht von überprüft“ (siehe die Zeile „Fehlermodi“ für den Befehl).

Der Merge-Status ist eine Positivliste, keine „nicht offensichtlich kaputt“-Prüfung. Fragen Sie nur, wenn mergeable MERGEABLE und mergeStateStatus CLEAN oder HAS_HOOKS ist – diese beiden sind die einzigen Werte, die mit einem bestandenen Commit-Status zusammenführbar bedeuten. Jeder andere Wert stoppt die Frage und benennt sich selbst im Kurzbericht:

mergeStateStatus	Was es bedeutet	Fragen?
CLEAN	Zusammenführbar und bestandener Commit-Status	Ja
HAS_HOOKS	Zusammenführbar, bestanden, Pre-Receive-Hooks vorhanden	Ja
UNSTABLE	Zusammenführbar mit einem nicht bestandenen Commit-Status	Nein – das ist das fehlschlagende CI oben
BLOCKED	Merge ist blockiert (Schutzregel, erforderliches Review)	Nein
BEHIND	Head-Referenz ist veraltet	Nein – zuerst rebasen
DIRTY	Merge-Commit kann nicht sauber erstellt werden	Nein – Konflikt
UNKNOWN	Status kann derzeit nicht bestimmt werden	Nein – erneut abfragen

Der Draft-Status ist nicht in dieser Aufzählung – es ist das separate Feld isDraft, sodass ein Draft-PR CLEAN melden kann. Fügen Sie isDraft zur --json-Liste hinzu und behandeln Sie einen Draft unabhängig von seinem Merge-Status als nicht bereit.

CLEAN sagt nichts über Basis-Commits aus, die seit dem Erstellen des Branches hinzugekommen sind. Zählen Sie sie (git fetch origin dann git rev-list --count HEAD..origin/<Basis>) und listen Sie die Dateien auf, die sie berührt haben und die auch der PR berührt (git diff --name-only HEAD...origin/<Basis>). Durchsuchen Sie für jede gemeinsame Datei den Basis-Diff nach den Symbolen, die dieser PR ändert, und führen Sie git merge-tree --write-tree HEAD origin/<Basis> aus – null Symboltreffer und Exit 0 sind der Beweis für „keine semantische Überlappung“, zitiert in Teil 5. Wenn der Pre-Merge-Rebase-Trigger auslöst (3+ Basis-Commits, eine Review-Runde abgeschlossen), bringen Sie die Basis mit gh pr update-branch <N> ein (ein Merge-Commit, niemals ein Rewrite), was CI und die Bot-Überprüfung neu startet: Warten Sie auf beide auf dem neuen Head, überarbeiten Sie den Anker mit dem Head, der sich bewegt hat, führen Sie dann die Schritte 1–3 gegen den neuen Head erneut aus und erstellen Sie den Kurzbericht neu, bevor Sie fragen – die zuvor gesammelten Befunde, der Merge-Status und die Genehmigungsabdeckung beschreiben den alten Head.

Schritt 2: Jeden Befund auf allen drei Oberflächen bewerten

Eine offene Thread-Anzahl ist keine Blocker-Anzahl, und die Thread-Oberfläche ist nicht der gesamte Korpus. Bewerten Sie jeden Befund, den Schritt 1 gesammelt hat – Inline-Thread, Konversationskommentar und Bewertungstext gleichermaßen – nach der Dekoration, nicht dem Label:

Erste Zeile des Befunds	Blockiert den Merge?
issue (blocking): / suggestion (blocking):	Ja – der Merge wartet
issue (non-blocking): / suggestion (non-blocking):	Nein
nitpick: / note:	Nein – von Haus aus ungelöst
Kein Label	Bewerten Sie selbst – lesen Sie den Text

suggestion ist keine niedrigere Stufe als issue: Beide tragen genau eines von (blocking) / (non-blocking), also ist die Dekoration das gesamte Urteil und das Label sagt nur, um welche Art von Befund es sich handelt. Das Label zu lesen, anstatt die Dekoration, führt dazu, dass ein deklarierter Blocker als „nur ein Vorschlag“ durchgewinkt wird.

Ein Bewertungstext ist kein Thread und kann nicht aufgelöst werden, was genau der Grund ist, warum er ungelesen bleibt: Nichts an ihm sieht offen aus. CodeRabbit speichert seine umsetzbaren Befunde in einklappbaren Bewertungstext-Abschnitten und nicht als Zeilenkommentare. Durchsuchen Sie daher die in Schritt 1 gesammelten Texte nach Actionable, Nitpick, outside diff, 🧹 und bewerten Sie, was Sie finden. Ein Konversationskommentar, der einen Fehler aufzeigt, wird auf die gleiche Weise bewertet. Blockierende Befunde auf beiden Oberflächen stoppen die Frage genauso wie ein Inline-Befund – sie haben lediglich keinen offenen Thread, werden also stattdessen in den offenen Punkten des Kurzberichts geführt.

Gleichen Sie die CodeRabbit-Anzahl ab, bevor die Bewertung abgeschlossen ist: Zählen Sie seine Befunde anhand der Markierungen `LINES`: ** in den Texten und gleichen Sie die Gesamtzahl mit der im Review-Header angegebenen ab (z.B. Major comments: N). Beantworten Sie die Menge in einem Konversationskommentar, gruppiert als Fixed — <sha> (n) / Not fixed (n) / False positive (n), dessen Summen dieser Gesamtzahl entsprechen.

Der Fall ohne Label ist der häufige, nicht die Ausnahme: Bots schreiben in ihrer eigenen Sprache. CodeRabbit beginnt mit seiner eigenen Schweregradzeile (_🎯 Functional Correctness_ | _🟠 Major_ | …), Copilot und BugBot mit keinem von beidem. Behandeln Sie den Schweregrad eines Bots als Eingabe für Ihre Bewertung, niemals als die Bewertung – und niemals als Grund, den Befund zu überspringen, weil „es nur ein Bot ist“.

Ein Thread, den Sie als blockierend bewertet haben, hat einen legitimen Ausweg vor dem Merge: Er wird behoben und geschlossen, oder er wird neu bewertet – indem der Kommentar auf (non-blocking) geändert und der Revised –-Hinweis gepostet wird. Einen blockierenden Befund ohne Neubewertung in einem Follow-up zu parken, lässt den Branch gesperrt, während jedes Label nicht-blockierend liest.

Das Löschen des REQUEST_CHANGES auf Review-Ebene ist ein separater, späterer Schritt. Dieser Zustand gehört zum Review, das mehrere Befunde enthalten kann, daher wird er erst gelöscht, nachdem jeder blockierende Befund darin behoben und geschlossen oder neu bewertet wurde – niemals auf der Stärke eines einzigen. Die Neubewertung des letzten ist das, was ihn freischaltet; bis dahin blockiert das Review zu Recht immer noch.

Schritt 3: Die Lücken des Ankerberichts (Unverified) nachführen

Öffnen Sie den Verifizierungsanker des PR und lesen Sie seine Unverified-Liste. Eine als „머지 후 실전송으로 확인“ geschriebene Lücke stirbt mit dem PR, es sei denn, etwas überlebt ihn.

• Führen Sie genau die Lücken weiter, die eine nächste Aktion benannt haben – eine Lücke ohne angegebene nächste Aktion wird nicht weitergeführt.
• Fragen Sie im Rahmen des Kurzberichts, ob ein Follow-up-Issue erstellt werden soll.
• Schreiben Sie die Antwort in die letzte Revision des Ankers als Carried: #N oder Carried: none — <Grund> vor dem Merge.
• Das Schreiben dieser letzten Revision benötigt gh – eine Sitzung, deren einzige GitHub-Oberfläche der MCP-Server ist, kann den Kommentartext nicht aktualisieren, wenn die aktive Tool-Liste dieses Servers kein update für Kommentare offenlegt (vor der Annahme bestätigen). Setzen Sie in diesem Fall die Carried:-Zeile stattdessen in den Merge-Commit oder den PR-Text und niemals in einen zweiten Ankerkommentar. Siehe anchor-comment-gate/spec.md → Ablauf für eine gh-lose Sitzung.
• Erstellen Sie das Follow-up niemals automatisch: Ein neues Issue benötigt dennoch zuerst eine eigene Überprüfung des Implementierungsansatzes.
• Wenn das Follow-up stattdessen als Kommentar aufgezeichnet wird (Carried: <Kommentar-URL>), setzen Sie es auf ein Issue, das nach dem Merge offen bleibt – das Ref:-Issue des PR (z.B. ein Hub/Sammel-Issue, das später durch einen Release-Schritt geschlossen wird), niemals das Closes #N-Issue, das der Merge selbst schließt und das niemand wieder öffnet. Gleiches gilt für Notizen außerhalb des Umfangs, die während der PR-Erstellung geschrieben wurden.
• Wenn das Carry-Issue dasjenige ist, das ein Post-Merge-Release-Schritt schließt (ein Hub-Issue, das durch /release geschlossen wird), begräbt der Release das Carry genauso wie ein Closes-Ziel. Nennen Sie diesen Konflikt im Merge-Bericht (jetzt releasen und die offenen Punkte verlieren, oder releasen, nachdem sie überprüft wurden), anstatt ihn stillschweigend auf die eine oder andere Weise zu lösen. Überprüfen Sie auch das Closes #N-Ziel nach dem Merge: GitHub schließt es nur, wenn der PR in den Standard-Branch des Repositorys gemerged wird, sodass ein PR in eine nicht standardmäßige Basis (prod, wenn der Standard dev ist) es für den Release-Schritt offen lässt.

Schritt 4: Den sechsteiligen Kurzbericht erstellen

Sechs Teile, in dieser Reihenfolge (diese Liste ist die kanonische Form; sie wurde ursprünglich aus der PR-Workflow-Vorlage der dotfiles des Autors abgeleitet):

1. Was hat sich geändert – beginnen Sie mit einem einfachen Satz, der beschreibt, was der PR tut und was sich für den Benutzer ändert, wenn er gemerged wird (und wenn nicht), dann der Umfang (Dateien, logische Änderungen), nicht noch einmal der Issue-Titel. Ein Teil 1, der aus Anzahlen und internen Abkürzungen besteht, erhält stattdessen „Was macht es?“ als Antwort, was das Genehmigungsfenster zurücksetzt und eine vollständige Neuerstellung des Kurzberichts erfordert.
2. Was wurde verifiziert – tatsächliche Ausgabe, mit Angabe des Befehls
3. Was wurde NICHT verifiziert – übersprungen, zurückgestellt, blockiert, CI-ausstehend
4. Risiko / Auswirkungsbereich – wer ist betroffen, wenn dies falsch ist
5. Offene Punkte – jeder Befund, den Schritt 2 bewertet und offen gelassen hat, auf allen drei Oberflächen; die Lücken aus Schritt 3
6. Explizite Frage – Merge genehmigen? in einer eigenen Zeile, im Text, mit dem AskUserQuestion-Aufruf von Schritt 5 direkt danach (die Zeile bleibt, auch wenn das Tool fragt, weil sie das Element ist, das die Hürde bewertet)

Teil 3 steht unter Druck und ist der Grund, warum der Kurzbericht existiert.

Wenn ein nicht verifiziertes Element genau der Schritt ist, den der Merge auslöst (ein Post-Merge-Deploy, ein Asset-Build, den CI nie ausgeführt hat, ein Multi-Plattform-Build, den Sie auf einer Plattform ausgeführt haben), ist es ein Risiko, keine Fußnote: Setzen Sie es in Teil 4 mit der Angabe, was fehlschlägt, wenn dieser Schritt fehlschlägt, und wen er sonst noch blockiert (spätere Deploys desselben Stacks). Bei einem PR, dessen Wert in der Buchhaltung liegt (Version Pins, Kataloge, Dokumentation), sagt Teil 4 auch in einer Zeile, was passiert, wenn er nicht gemerged wird – der Benutzer fragt das, bevor er einen PR mit geringem Risiko genehmigt, der dennoch einen Deploy auslöst.

Teil-3-Anti-Patterns: „완료했습니다, 머지할까요?“ ohne Nachweise; eine übersprungene Prüfung, die zu einem nachgestellten Nebensatz degradiert wurde; zum Zeitpunkt des Merges zu berichten, was zum Zeitpunkt der PR-Fertigstellung hätte auftauchen sollen.

Schließen Sie Elemente in Teil 3 durch Beobachtung, nicht durch Lesen. Wenn der Benutzer Sie bittet, die nicht verifizierten Elemente zu überprüfen, gehen Sie Element für Element vor und führen Sie die günstigste Prüfung durch, die das Element erledigt.

Schritt 5: Die Frage stellen (AskUserQuestion)

Der Ablauf endet mit einem AskUserQuestion-Tool-Aufruf. Der Aufruftext ist die Genehmigungsfrage aus Teil 6. Erhalten Sie eine Textantwort.

Der Benutzer darf mit einem beliebigen Text antworten, der Zustimmung ausdrückt („ja“, „merge“, „genehmigen“, „계속“, „okay“). Sie dürfen keinen Text als Zustimmung interpretieren, der nicht Zustimmung ausdrückt (eine Zeile aus dem Kurzbericht, eine Ausgabe, eine Frage). Was Sie mit der Antwort tun:

• Antwortet Zustimmung → führen Sie gh pr merge <N> --merge --subject <Betreff> aus. Erstellen Sie den Merge-Commit-Titel aus dem PR-Titel und der PR-Nummer <Titel (#N); der Textkörper ist der vollständige Kurzbericht. Hängen Sie Carried: von Schritt 3 an den Textkörper an. Verlinken Sie den Merge-Commit in der Antwort, in der Sie das Ergebnis melden.
• Antwortet nicht Zustimmung → antworten Sie mit einer Zusammenfassung des Kurzberichts (Teile 1–4 in einem Absatz zusammengefasst) und was der nächste Schritt sein sollte („Soll ich prüfen?“, „Bereit, wenn erfüllt ist“).

Bestätigen Sie den Merge-Status unmittelbar vor dem Merge-Aufruf – mergeStateStatus kann sich zwischen der Erstellung des Kurzberichts und dem Druck auf die Eingabetaste geändert haben.

Wenn AskUserQuestion nicht verfügbar ist (z.B. reines Chat-Modell), geben Sie den Kurzbericht aus und warten Sie auf eine Ja/Nein-Antwort in normalem Text. Das Format bleibt identisch; lediglich der Mechanismus unterscheidet sich.

Stapel-Merge: mehrerer PRs, eine Antwort

Mehrere PRs, die zusammen gemerged werden müssen, um einen funktionierenden Zwischenzustand zu erreichen, teilen sich eine Antwort. Dies ist die einzige Ausnahme von der Regel „Ein PR, ein Kurzbericht, eine Antwort“.

Das Format für diese Runde:

• Ein separater Kurzberichtsabschnitt pro PR (sechs Teile).
• Nach dem letzten Abschnitt ein Stapel-Merge genehmigen? (AskUserQuestion).
• Identische Merge-Regeln: Jeder PR muss einzeln zusammenführbar sein, keine offenen Blocking-Befunde.
• Der Merge-Aufruf ist ein Befehl pro PR (kein Batch-GitHub-Endpunkt).

Fehlermodi

Bedingung	Symptom	Behebung
Veralteter Anker	Kurzbericht basiert auf einem vorherigen Head	Führen Sie die Prüfungen erneut durch; veraltete Prüfungen sind zu verwerfen. git merge-base --is-ancestor <alter_Head> <neuer_Head>; wenn False, sind alle Prüfungsergebnisse ungültig.
Stapel-Merge, Teilmenge nicht bereit	Ein PR aus der Menge ist nicht zusammenführbar	Entfernen Sie ihn aus dem Stapel; fragen Sie für die verbleibenden erneut
Falsche Fork-Repos	gh pr löst gegen das übergeordnete Repo auf	Fügen Sie --repo <Fork> zu jedem Befehl hinzu
Nicht zusammengeführte Basis vor dem Stapel-Merge	Stapel-Merge erzeugt einen zirkulären oder unvollständigen Verlauf	Mergen Sie zuerst den untersten PR des Stapels, bevor Sie die Frage für die höheren stellen
CodeRabbit-Bewertung nach dem Fix	„Nicht behoben“-Zähler für einen fixierten Kommentar	Führen Sie git diff HEAD~1 -- <Datei> aus, wenn der Fix lokal ist, oder öffnen Sie den PR-Diff und vergleichen Sie text-Felder in den GraphQL-Antworten
Bewertungs-commit_id vs. headRefOid	Als genehmigt markiert, aber nachfolgende Änderungen existieren	Listen Sie nicht überprüfte Commits auf: git log --no-merges <commit_id>..<head> --oneline
CI-Timeout bei Stapel-Merge-Kandidat	Kurzbericht ist fertig, aber CI läuft noch	Warten Sie auf grünes CI, bevor Sie merge