TrackerJo/pr-description

PR-Beschreibungen in verständlichem Deutsch

Schreibe für einen Maintainer, der die Änderung schnell verstehen muss. Eine gute Beschreibung beantwortet auf dem ersten Bildschirm drei Fragen:

1. Was war falsch oder fehlte?
2. Warum musste es geändert werden?
3. Was ist jetzt der Fall?

Lies den tatsächlichen Diff, den aktuellen PR-Text, die Commits, Tests und den PR-Status, bevor du schreibst. Der alte Text und die Commit-Titel beschreiben die Absicht, keinen Beweis. Behaupte kein manuelles Testen, Deployment oder Produktionsverhalten, es sei denn, der Autor hat es bestätigt.

Erforderlicher Einstieg: Was sich geändert hat und warum

Jede PR-Beschreibung muss mit einem vom Beitragenden verfassten Abschnitt ## What Changed and Why beginnen, direkt nach dem vom Monitor verwalteten Abschnitt ## Status, falls dieser vorhanden ist. Dies ist erforderlich, keine optionale Formatierung.

Verwende drei kurze beschriftete Absätze in dieser Reihenfolge:

• Problem: der tatsächliche Benutzer- oder Betreiberfehler oder das fehlende Verhalten.
• Warum diese Änderung notwendig war: warum dieser Fehler wichtig war und warum die gewählte Abgrenzung notwendig ist.
• Neuer Status quo: das konkrete Verhalten nach diesem PR.

Halte jeden beschrifteten Absatz auf ein bis zwei Sätze. Ein Maintainer muss die Frage „Was ist in diesem PR passiert?“ allein aus diesem Abschnitt beantworten können. Beginne nicht mit Implementierungsmechanismen, einem verworfenen Design oder einer Nacherzählung der Historie.

Wenn ein unzureichender Einstieg überprüft wird, gib einen konkreten Ersatz oder eine prägnante Dreipunktgliederung, die auf den tatsächlichen Diff zugeschnitten ist. Sage nicht nur, dass er zu ausführlich, unklar ist oder eine bessere Erklärung benötigt.

Verwende diese Struktur für die meisten PRs:

## What Changed and Why

**Problem:** [Der tatsächliche Benutzer- oder Betreiberfehler oder das fehlende Verhalten.]

**Warum diese Änderung notwendig war:** [Warum es wichtig war und warum diese Abgrenzung
notwendig ist.]

**Neuer Status quo:** [Das konkrete Verhalten nach diesem PR.]

## Nach dem Merge

[Nur die tatsächlichen Betreiber- oder Prüferaktionen, die noch ausstehen. Diesen Abschnitt
weglassen, wenn es keine gibt.]

## Verifizierung

[Nur bestätigte manuelle Prüfungen und wirklich nach dem Merge erforderliche Prüfungen
angeben.]

Beginne mit der Substanz. Wiederhole nicht den PR-Titel, füge keine Einleitung hinzu oder schreibe eine Zusammenfassung, die den nächsten Absatz wiederholt.

Was beibehalten werden sollte

• Ein klarer Endzustand pro wesentlicher Änderung. Ein Leser, der den ersten Satz jedes Absatzes oder Aufzählungspunkts scannt, sollte verstehen, was sich nach dem Merge ändert.
• Echte Entscheidungen. Nenne eine abgelehnte Alternative nur, wenn sie das Produktverhalten, Risiko oder einen bedeutenden Kostenpunkt betrifft. Sage in einem Satz, was gewählt wurde und warum. Erfinde kein „Wichtige Entscheidung“-Label.
• Betriebliche Fakten. Erwähne Migrationen, Backfills, geplante Jobs, Integrationen, Secrets, die Bereitstellungsreihenfolge und Fehlerverhalten, wenn ein Prüfer oder Betreiber darauf reagieren muss.
• Ehrliche Verifizierung. Trenne, was jemand tatsächlich manuell überprüft hat, von Arbeiten, die wirklich bis nach dem Merge warten müssen. Liste keine Lint-, Build-, CI- oder Testbefehle auf. Tests können in normalem Deutsch erwähnt werden, wenn sie ein aussagekräftiges Verhalten abdecken.
• Offene Punkte. Füge nur ungelöste Entscheidungen ein, die der Prüfer treffen muss. Stelle die Frage an den Anfang, dann eine Empfehlung und deren Kosten. Lasse den Abschnitt weg, wenn es nichts zu entscheiden gibt.

Erforderliche Nachweise bei geänderten Systemen

Eine Beschreibung ist unvollständig, wenn sie ein benutzerorientiertes System, einen wesentlichen Betreiberworkflow oder dessen Konfiguration ändert und dem Prüfer nicht zeigt, wie es überprüft werden kann.

• Screenshots oder kurze Videos: Füge visuelle Belege in einen eigenen Abschnitt ## Visueller Nachweis ein. Füge Screenshots für einen geänderten Bildschirm oder kurze Videos für eine geänderte Interaktion oder einen mehrstufigen Ablauf bei. Bette die Medien ein oder verlinke auf einen stabilen PR-Anhang. Bildunterschriften müssen sagen, was sich geändert hat und worauf der Prüfer schaut. Ersetze keinen Screenshot des Quellcodes, eines Testberichts oder eines unveränderten Bildschirms. Lege erforderliche Telefon-Nachweise vor Laptop- Nachweisen für öffentliche und Event-Oberflächen und identifiziere jeden Viewport und getesteten Zustand. Folge dem Skill visual-proof für Aufnahme, Upload und Überprüfung des letzten Commits. Lasse diesen Abschnitt nur weg, wenn der PR keine visuelle oder interaktive Oberfläche hat.
• Konfiguration, Umgebung und Migrationen: Füge nur tatsächlich hinzugefügte, entfernte, umbenannte oder verhaltensändernde Umgebungsvariablen, Secrets, Dashboard-Einstellungen und Datenbankmigrationen in ## Konfiguration ein. Beginne mit der einen Aktion, die ein Betreiber ausführen muss; halte die gewöhnliche externe Einrichtung auf einen kurzen Satz, z. B.: „Richte einen Monitor unter ein und richte ihn auf https://buildpurdue.org/api/health. Keine internen Änderungen.“ Fülle den Abschnitt nicht mit Polling-Details, bereits an anderer Stelle erläuterten Begründungen oder Links zu duplizierten Runbooks. Nenne für jede tatsächliche Migration den zugehörigen supabase/migrations/-Pfad, fasse die Schema-/Daten-/Richtlinienänderung zusammen, gib Kompatibilitäts- oder Backfill-Anforderungen an und nenne das bestätigte npm run db:verify-Wiederholungsergebnis. Gib niemals geheime Werte preis. Lasse den Abschnitt weg, wenn es keine Konfigurations- oder Migrationsänderungen gibt.
• Geänderte Abläufe: Verwende Mermaid-Flussdiagramme für wesentliche Änderungen von Abläufen. Ein Ablauf ist wesentlich, wenn er mehrere Schritte, Verzweigungen, Wiederholungen, eine Übergabe zwischen Systemen oder einen Fehlerpfad umfasst. Zeige den geänderten Pfad und sein wichtiges Fehlerverhalten, mit verständlichen Beschriftungen, die ein Prüfer lesen kann. Füge ein Diagramm pro geändertem Ablauf hinzu. Verwende kein Diagramm für eine einstufige Umbenennung oder eine triviale lokale Berechnung.

Diese sind getrennt von der Haupterklärung. Die Erklärung sagt, warum die Änderung existiert; Nachweise, Konfiguration und Diagramme ermöglichen es einem Prüfer, sie zu überprüfen.

Bleibe lesbar

• Standardmäßig 250 Wörter oder weniger. Eine Beschreibung kann länger sein, wenn der Betreiber eine kurze Checkliste benötigt, aber jeder Satz muss seinen Platz verdienen.
• Verwende kurze Absätze. Verwende Aufzählungspunkte nur für eine echte Liste, z. B. verbleibende Einrichtungsschritte. Mache nicht jeden Satz zu einem beschrifteten Aufzählungspunkt.
• Setze Problem, Grund und neuen Status quo in normales Deutsch. Sage, wer was tut.
• Vermeide rohen Code, Abfragen, Konfigurationsfragmente, Statuscodes als Substantive, Jargon, Metaphern, Übertreibungen und Gedankenstriche.
• Erkläre nicht jeden Mechanismus. Behalte das Verhalten, das der Prüfer wissen muss.
• Wiederhole keine Tatsache in einem späteren Abschnitt. Wenn ein Satz verschwinden kann, ohne dass Informationen verloren gehen, entferne ihn.

Status wird vom Monitor verwaltet

Beitragende verwalten jeden Teil der PR-Beschreibung außer ## Status. Füge diesen Abschnitt nicht selbst hinzu, entferne ihn nicht und bearbeite ihn nicht. Der BuildPurdue-PR-Monitor verwaltet ihn und hält ihn mit dem aktuellen Überprüfungszustand abgestimmt.

Wenn der Monitor den Status ändert, veröffentlicht er auch einen passenden PR-Kommentar Status update:. Er verwendet einen Satz in verständlichem Deutsch: eine konkrete Vor-Merge-Nächstaktion, wenn noch Arbeiten ausstehen, oder Keine weiteren Arbeiten ausstehend., wenn nichts mehr aussteht. Status gehört niemals in einen beitragendenorientierten Beschreibungs-Überprüfungskommentar.

Verwende Status nicht für optionale Zukunfts-Ideen, historische Notizen, reine-Nach-Merge-Arbeiten oder separat verfolgte Arbeiten, die diesen PR nicht blockieren.

Wenn mehr Struktur gerechtfertigt ist

Füge einen gezielten Abschnitt nur hinzu, wenn er Informationen enthält, die nicht in die Haupterklärung passen:

• Datenbank / Migrationen: was ausgeführt werden muss, ob vorhandene Daten kompatibel bleiben und ob ein Backfill erforderlich ist.
• Betriebsverhalten: was läuft, wann es läuft, wie Fehler sichtbar sind und was ein Betreiber konfigurieren muss.
• Verifizierung: bestätigte manuelle Prüfungen und wirklich nach dem Merge erforderliche Prüfungen.
• Offene Punkte: ungelöste Produkt- oder Risikoentscheidungen.

Ein kleiner Bug-Fix kann einfach Folgendes verwenden:

## Grundursache

## Behebung

## Verifizierung

Vor der Veröffentlichung

1. Überprüfe, dass jede Behauptung auf den aktuellen Diff, die Tests, den PR-Status oder einen von dir ausgeführten Befehl zurückgeht.
2. Lies den ersten Bildschirm für sich allein. Er muss klar das Problem, den Grund für die Änderung und den neuen Status quo angeben.
3. Entferne historische Erzählungen, changelog-artige Implementierungsprotokolle, wiederholte Erklärungen und nicht zusammenhängende Arbeiten.
4. Bestätige, dass jede Migration, jedes Deployment, jedes Secret, jedes Dashboard oder jede Nach-Merge-Aktion explizit und umsetzbar ist.
5. Lies es laut vor. Es sollte sich anhören, wie eine Person einem Teamkollegen die Änderung erklärt, nicht wie ein Prüfbericht.
6. Vergleiche bei jedem Push den Text mit dem neuen Diff und aktualisiere ihn, wenn sich das Verhalten, die verbleibende Einrichtung oder der Verifizierungsstatus geändert hat.

Quelle

Bearbeite diese Kopie unter .agents/skills/. Der Pre-Commit-Hook spiegelt sie in .claude/skills/pr-description/; bearbeite das Spiegelbild nicht direkt.