GitHub Deep Review
Review wie Peter: hohe Sicherheit, evidenzbasiert, code-bewusst, und bereit, „nicht belegt“ zu sagen, wenn die Spur schwach ist. Das Ziel ist keine allgemeine Zusammenfassung. Das Ziel ist es, die Bug-Klasse zu verstehen, die wirkliche Ursache zu finden, wenn möglich die beste Lösung nach ausreichendem Lesen des Codes zu bestimmen und darauf hinzuweisen, ob eine größere Refaktorisierung das Design verbessern würde.
Start
Verwenden Sie gh, nicht die Web-Browsing, für GitHub-Referenzen:
gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch
Für PRs sammeln Sie standardmäßig den Autorenkontext, es sei denn, der Autor ist Peter (steipete oder ein offensichtliches Peter-Konto). Verwenden Sie den lokalen Workflow in ~/Projects/agent-scripts/skills/github-author-context/SKILL.md und fügen Sie einen kurzen Author context:-Block nahe dem Anfang des Reviews ein, wenn der Autor nicht Peter ist.
Nach Merge/Ablehnung/Schließen/Review verwenden Sie denselben Autorenkontext-Workflow, um einen Beitragshinweis anzuhängen, jedoch nur, wenn die Interaktion ein dauerhaftes Signal für zukünftige Reviews erzeugt.
Für repo-lokale Reviews überprüfen Sie auch:
git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<key symbol/error/config/endpoint>"
Wenn das Repository lokale Anweisungen, Issue/PR-Skills, Dokumentationslisten, Testanleitungen oder Maintainer-Runbooks enthält, lesen Sie diese vor einer Entscheidung.
Review-Vertrag
Beantworten Sie immer diese Fragen explizit:
- URL/Ref: Issue- oder PR-Nummer und betroffene Oberfläche.
- Was ist der Bug oder das Verhalten, das behoben wird?
- Können wir die Grundursache identifizieren? Wenn ja, wo im Code und warum. Wenn nein, welche Beweise fehlen.
- Für Regressionen: Wer/was hat sie eingeführt und wann? Fügen Sie Commit/PR-Herkunft bei, wenn diese durch eine begrenzte Historie nachvollziehbar ist; sagen Sie „unbekannt“ anstatt zu raten.
- Ist die aktuelle/vorgeschlagene Lösung die beste mögliche Lösung nach dem Lesen des angrenzenden Codes?
- Würde eine größere Refaktorisierung Korrektheit, Klarheit oder zukünftige Wartbarkeit verbessern?
- Welche Beweise existieren: Tests, Live-Reproduktion, CI-Prüfungen, Dokumentation, Abhängigkeitsdokumentation/-quellen, ausgeliefertes/aktuelles Verhalten.
- Was bleibt riskant oder unverifiziert.
Code-Lesetiefe
Lesen Sie über die erste geänderte Datei hinaus. Verfolgen Sie den tatsächlichen Aufrufpfad:
- Einstiegspunkt -> Validierung/Parsing -> Routing/Dispatch -> Besitzer-Modul -> gemeinsamer Helfer -> Persistenz/Netzwerk/Laufzeit-Grenze
- Konfiguration/Schema/Dokumentation -> Laufzeitnutzung -> Doctor/Migrations-/Fehlerbehebungspfad
- Provider/Kanal/Plugin-Besitzer-Code -> generischer Kern-Seam, nur wenn mehrere Besitzer ihn benötigen
- Tests rund um die betroffene Oberfläche plus angrenzende Regressionstests
Wenn das Verhalten von einer Abhängigkeit abhängt, lesen Sie die Upstream-Dokumentation/Quellen/Typen oder den aktuellen Paketvertrag, bevor Sie Annahmen treffen.
Bevorzugen Sie aktuelle Quellen und ausführbare Beweise gegenüber Issue-Kommentaren. Behandeln Sie veraltete Kommentare, alte CI- und alte Release-Verhalten als Hinweise, bis sie erneut überprüft werden.
Herkunft
Für Bug-/Regressions-Reviews fügen Sie, wenn möglich, eine kompakte Provenance:-Antwort ein:
- Verwenden Sie
git log -S/-G,git blame, verlinkte PRs/Issues und Tests. - Trennen Sie Autor, Committer/Merger und aktuellen PR-Autor, wenn diese unterschiedlich sind.
- Formulieren Sie als
introduced by,made visible byodercarried forward by. - Fügen Sie Vertrauensniveau ein:
clear,likelyoderunknown. - Für Features, Dokumentationen, Refaktorisierungen oder nicht nachvollziehbare Bugs schreiben Sie
N/Aoder sagen Sie, welche Beweise fehlen.
Qualitätsbar für Lösungen
Gute Lösungen:
- liegen an der Besitzergrenze, zu der der Bug gehört
- bewahren das öffentliche/abwärtskompatible Verhalten, es sei denn, das Issue betrifft dessen Außerdienststellung
- fügen einen Regressionstest an der kleinsten sinnvollen Nahtstelle hinzu
- vermeiden breite Sonderfälle, versteckte Migrationen, semantische Sentinelwerte und Provider-/Kanal-IDs im generischen Kern
- aktualisieren die Dokumentation/Changelog, wenn sich das benutzersichtbare Verhalten ändert
- scheitern klar in Laufzeitpfaden und reparieren durch Doctor-/Migrationspfade, wenn dies der etablierte Vertrag ist
Weisen Sie darauf hin, wenn eine Lösung nur Symptomebene ist. Wenn eine etwas größere Refaktorisierung die Invariante offensichtlich macht und zukünftige Fehler reduziert, empfehlen Sie sie. Wenn die Refaktorisierung das Risiko erhöht, ohne die Bug-Klasse zu verbessern, sagen Sie das.
PR-Review-Format
Führen Sie bei der Überprüfung eines PRs mit Ergebnissen an. Ergebnisse benötigen Datei/Zeilen/Symbol-Referenzen und eine konkrete Fehlerbeschreibung. Vermeiden Sie vage „überlegenswert“-Kommentare.
Wenn keine blockierenden Probleme vorliegen:
- sagen Sie, dass keine blockierenden Korrektheitsprobleme gefunden wurden
- listen Sie die stärksten überprüften Beweise auf
- nennen Sie verbleibende Risiken/Testlücken
- beantworten Sie, ob das Design die beste verfügbare Form ist
Genehmigen, kommentieren, schließen, mergen, pushen oder landen Sie nicht, es sei denn, der Benutzer hat diese Aktion angefordert.
Issue-Review-Format
Für Bugs/Issues:
- Rekonstruieren Sie das Szenario des Reporters und die betroffene Version/Oberfläche.
- Prüfen Sie, ob der aktuelle
maindas Problem bereits behebt. - Reproduzieren Sie das Problem oder erstellen Sie einen minimalen lokalen/Live-Beweis, wenn möglich.
- Wenn klar, identifizieren Sie die Grundursache und eine vorgeschlagene Fix.
- Wenn auf
maingelöst, kommentieren/schließen Sie nur, wenn der Benutzer danach fragt; fügen Sie Beweise und den kanonischen Commit/PR bei, falls bekannt.
Wenn eine Reproduktion nicht möglich ist, sagen Sie genau, was sie blockiert und welche Beweise die Entscheidung zuverlässig machen würden.
Ausgabevorlage
Verwenden Sie diese Form, wenn der Benutzer fragt „worum geht es hier“, „ist das der beste Fix“ oder „was haben wir repariert“:
Ref: #123 / PR #456
Surface: <runtime/CLI/provider/channel/docs>
Bug: <ein oder zwei Sätze>
Cause: <Codepfad + Vertrauensniveau>
Provenance: <introduced/made visible/carried forward by commit/PR/date, or N/A/unknown>
Best fix: <was sich ändern sollte und warum>
Refactor: <ja/nein, spezifische Form>
Proof: <tests/live/CI/source/dependency docs>
Risk: <verbleibende Unsicherheit>
Halten Sie es prägnant, aber überspringen Sie nicht die Entscheidung über Ursache/Lösung/Refaktorisierung/Beweis.