softwareone-platform/issue-to-pr

PR öffnen

Öffne einen Pull Request für den aktuellen Branch auf der erkannten PR-Plattform (Azure DevOps oder GitHub). Titel und Beschreibung werden so verfasst, dass sie den Konventionen des aufrufenden Benutzers aus seinen eigenen früheren PRs entsprechen – nicht einem festen Team-Stil – und dann zur Bestätigung angezeigt. Der PR wird niemals ohne explizite Zustimmung erstellt – das Öffnen eines PRs ist eine nach außen gerichtete Aktion.

Diese Skill ist backend-agnostisch: Die plattformspezifischen Mechanismen (PR erstellen, Duplikatsprüfung, Label, Backport-Link) befinden sich in Backend-Adapter-Referenzdokumenten unter resources/backends/, und die Ticket-Link-Mechanismen in Tracker-Adapter-Referenzdokumenten unter resources/trackers/. Der Skill-Body erkennt Plattform und Tracker, lädt die passenden Adapter und folgt deren Rezepten – er enthält keine eigene az/gh-spezifische Feldparsung und keine tracker-spezifische ID-/URL-Parsung. Er leiht sich die Sicherheitsmechanismen eines PR-Erstellungsflusses, ist aber bewusst enger gefasst: Er öffnet einen PR für den Branch so wie er ist – veröffentlicht ihn zuerst auf dem Remote, falls er dort noch nicht vorhanden ist, da der PR ihn benötigt. Er führt keinen Merge des Basis-Branches durch, löscht keine Branches und bearbeitet keine Review-Kommentare (das ist Aufgabe von resolve-pr-comments).

Schritt 0 – Plattform + Tracker erkennen, Adapter laden, bekannt geben

Bevor irgendetwas anderes geschieht, ermittle, welches Backend und welcher Tracker für diesen Durchlauf verwendet werden:

• PR-Plattform – aus git remote get-url origin:
  • dev.azure.com oder *.visualstudio.com → Azure DevOps (resources/backends/azure-devops.md).
  • github.com → GitHub (resources/backends/github.md).
  • Uneindeutig oder anderer Host → die Einschränkung nennen und den Benutzer fragen, welche Plattform verwendet werden soll, anstatt zu raten.
• Issue-Tracker (Reihenfolge – erster Treffer gewinnt):
  1. Explizite Konfiguration gewinnt: Wenn .claude/pr-lifecycle.json (optional, gitignoriert) den Tracker-Typ festlegt, diesen verwenden (und die Jira-Basis-URL daraus übernehmen).
  2. sonst ableiten des Typs aus einem vorhandenen Ticket-Verweis: [A-Z][A-Z0-9]+-\d+ → Jira (beide Plattformen); ein bloßer numerischer Issue-Verweis → GitHub Issues – aber nur auf einem GitHub-Remote (auf Azure DevOps ist #<n> ein Work-Item-Link, kein GitHub-Issue, daher impliziert eine bloße Nummer dort kein GitHub Issues).
  3. sonst Standard nach Plattform: ein GitHub-Remote → GitHub Issues (Null-Konfiguration); ein Azure DevOps-Remote → Jira.
  4. Kein Ticket vorhanden → keine Tracker-Zeile erzeugen (wie bisher).
  • Jira → resources/trackers/jira.md; GitHub Issues → resources/trackers/github-issues.md.
• Bekannt geben der erkannten Plattform und des erkannten Trackers, sodass ein stiller Fehler unmöglich ist.

Die passenden Backend- und Tracker-Adapter laden und die plattform-/trackerspezifischen Teile der untenstehenden Schritte über sie ausführen. Die einzige Backend-Naht in diesem Body ist das Erkennen des Remote-Strings, um den Adapter auszuwählen – kein Feldzugriff darüber hinaus. (Adapter-Pfade sind relativ zum Plugin-Root – plugins/pr-lifecycle/resources/backends/ und resources/trackers/ – nicht zum Skill-Verzeichnis.)

Schritt 1 – Ziel-Branch ermitteln

• Den eigenen Standard-Branch des Repos lesen; niemals annehmen. git symbolic-ref --short refs/remotes/origin/HEAD ergibt origin/<branch> – das Präfix entfernen. Diese Referenz wird von git clone geschrieben, daher kann es einem Remote, der durch git init + git fetch erstellt wurde, fehlen; dann den Remote direkt mit git ls-remote --symref origin HEAD fragen, was schreibgeschützt ist und keinen lokalen Zustand ändert.
• Nur wenn keines der beiden funktioniert, auf den Branch zurückfallen, den der Remote tatsächlich als main/master hat – und wenn beide existieren, nachfragen. Ein Repo, das sich mitten in einer Umbenennung befindet, behält den alten als veralteten Branch, sodass eine stillschweigende Auswahl den PR auf das falsche Ziel basieren würde, was auch Schritts 2 Vorwärts-Zähler und den Verlauf ungültig macht, aus dem Schritt 3 die Konvention des Aufrufers lernt.
• Wenn der aktuelle Branch auf eine Release-Linie abzielt (z.B. release/2.5), als Backport behandeln (siehe Backport-Format unten).
• Wenn das korrekte Ziel wirklich uneindeutig ist, nachfragen, anstatt zu raten.

Schritt 2 – Vorbedingungen (stoppen und melden, wenn eine fehlschlägt)

Diese ausführen, bevor etwas entworfen wird, da jede ein häufiger Erstausführungs-Blockierer ist:

• Hat Commits für den PR. Der Branch muss dem Ziel voraus sein: git fetch, dann git rev-list --count origin/<target>..HEAD muss größer als 0 sein.
• Auf dem Remote – bei Bedarf veröffentlichen. Das Erstellen des PRs benötigt den Quell-Branch auf dem Remote. Ein noch nicht gepusher Branch ist kein Stopp: Nach Bestätigung veröffentlicht open-pr ihn (git push -u origin <branch>) als Teil des Erstellens in Schritt 4. (Bei nicht-interaktivem Laufen wird nicht gepusht und nicht erstellt – siehe Schritt 4.)
• Kein Duplikat. Prüfen, ob ein vorhandener offener PR für diese Quelle zu diesem Ziel existiert, über das Duplikatsprüfungs-Rezept des Backend-Adapters. Wenn einer existiert, stoppen und den Benutzer darauf hinweisen – keinen zweiten PR öffnen und den vorhandenen hier nicht ändern.

Schritt 3 – Konvention des Aufrufers lernen, dann entwerfen

Den Aufrufer aus git config user.email (bevorzugt) und user.name identifizieren, dann dessen letzte gemergte PRs in diesem Repo lesen: git log <target> --author="<email or name>" (beide Formen versuchen; nur als "kein Verlauf" behandeln, wenn beide nichts zurückgeben). Aus den letzten mehreren die Titel-Schreibweise und das Beschreibungs-Layout (Abschnitte vs. eine flache Aufzählungsliste) per Mehrheit ableiten – der neueste nach Commit-Datum bricht ein Unentschieden, ein einzelner vorheriger PR wird direkt verwendet. Das Ergebnis bekannt geben (von K Ihrer früheren PRs gelernt oder kein passender Verlauf -> Standard verwenden), sodass eine stille Fehlentscheidung unmöglich ist.

Das Lernen umfasst, wie dieses Repo und dieser Aufrufer Dinge schreiben, nicht nur Typografie: Titel-Schreibweise, Beschreibungs-Layout (Abschnitte vs. eine flache Aufzählungsliste) und die Form des Ticket-Präfixes im Titel – eingeklammert ([acme-123] …), nackt (acme-123 …), ein Conventional Commits-Typ (fix(scope): …) oder gar kein Präfix. Die Form aus demselben Verlauf lesen; wenn die beobachteten PRs kein Ticket-Präfix tragen, keines hinzufügen. Die folgenden Standardwerte sind das, was verwendet wird, wenn kein Verlauf zum Lernen vorhanden ist, niemals ein Format, das einem Repo aufzuzwingen ist, das sichtbar etwas anderes tut.

Das Lernen darf niemals die obligatorischen Inhalte unten fallen lassen oder umordnen – den Ticket-Link, die Zusammenfassung und die Aufzählungspunkte; das Diagramm in Punkt 4 ist optional, und die Herkunfts-Fußzeile in Punkt 5 ist standardmäßig deaktiviert, aber wenn die Herkunfts-Fußzeile aktiviert ist, muss das Lernen sie zuletzt lassen und niemals fallen lassen. Das Lernen nicht auf dieses Repository verzerren, wenn es ein Einzelautoren-Repo ist – die relevante Konvention ist die des Aufrufers, in welchem Repo die Skill auch läuft.

Standardformat (der Rückfall; die gelernte Konvention des Aufrufers überschreibt die Darstellung)

Titel: die Ticket-ID und ihre Schreibweise aus dem Tracker-Adapter ableiten:

• Jira-Tracker: [acme-xxxxx] <prägnante einzeilige Zusammenfassung> – der eingeklammerte, kleingeschriebene Schlüssel (der Adapter liefert auch die großgeschriebene Form für die URL).
• GitHub Issues-Tracker: #<n> <prägnante einzeilige Zusammenfassung> – der #<n>-Verweis anstelle der Klammerform.
• Kein Ticket gefunden: die Ticket-Zeile weglassen und den Titel so betiteln, wie dieses Repo ticketlose PRs betitelt. ad-hoc <Zusammenfassung> ist der Rückfall nur, wenn der Verlauf in Schritt 3 Ihnen nichts zum Kopieren gab – es ist eine Markierung eines Teams, keine Konvention, die in ein Repo einzuführen ist, das sie nie verwendet hat. Eine einfache <Zusammenfassung> ist der sicherere Standard.
• Zwei oder mehr verschiedene Ticket-IDs bedeuten nachfragen, welche, anstatt stillschweigend die erste zu nehmen.

Beschreibung (Standard-PR):

1. Ticket-Link – erstellt vom Tracker-Adapter: für Jira https://<jira_base_url>/browse/<KEY> (Großbuchstaben-Key); für GitHub Issues #<n> (GitHub verlinkt ein Issue im selben Repo automatisch). Dies ist die erste Zeile, damit die Plattform ihn automatisch verlinkt; die gesamte Zeile nur weglassen, wenn es kein Ticket gibt.
2. Zusammenfassung – ein oder zwei Sätze.
3. Beschreibung – eine Aufzählungsliste, ein Punkt pro diskreter Änderung als Aktion plus kurzes Warum/Auswirkung. Datei-/Klassen-/Methoden-/Pfad-Identifikatoren weglassen – die Absicht beschreiben, nicht den Diff einfügen.
4. Ein kurzes ASCII-Diagramm, umschlossen von einem Code-Block mit Backticks (optional) – nur eines einfügen, wenn ein Bild dem Reviewer die Änderung schneller erfassen lässt als Prosa; sonst weglassen. Wenn Sie eines einfügen: ein echtes Monospace-Strukturbild (Boxen/Pfeile oder ein kleiner Baum/eine Tabelle – niemals Prosa, die als Diagramm verkleidet ist), auf hohem Niveau gehalten, in einem dreifachen Backtick-Rahmen, gezeichnet mit einfachen ASCII-Zeichen (+ - | > v), nicht Mermaid; jedes breite oder komplexe Diagramm in kleinere aufteilen, anstatt einen unlesbaren Block zu erzwingen. Vollständige Zeichenanleitung, die Begründung für den Rahmen/die Kodierung und eine beispielhafte Form: resources/diagram-guidance.md.
5. KI-Herkunftsmarkierungen (optional – standardmäßig deaktiviert) – die Fußzeile (ein ----Trenner, dann 🤖 _Entworfen mit Claude Code._) und das ai-assisted-Label, das in Schritt 4 angewendet wird, werden nur hinzugefügt, wenn die aufrufende Anfrage explizit darum bittet, den PR als KI-assistiert zu markieren/kennzeichnen/flaggen (oder eine explizite Zustimmung übergibt). Ohne diese Formulierung – einschließlich jedes automatisierten resolve-issue-Pipeline-Aufrufs, der keine solche Formulierung trägt – keines von beiden hinzufügen. Die Entscheidung in derselben Zeile wie die Plattform-/Tracker-/Lernergebnis bekannt geben (Herkunft: aus (sagen Sie "als KI-assistiert markieren" zum Hinzufügen), oder Herkunft: an (Fußzeile + Best-Effort-Label)), sodass eine stillschweigend weggelassene Markierung unmöglich ist. Wenn aktiviert, ist die Fußzeile das letzte Element auf jedem Pfad – sie nach dem gelernten Konventions-Body anhängen und niemals zulassen, dass das Lernen sie fallen lässt oder umordnet – und sie wird auf Azure DevOps und GitHub identisch dargestellt, der portablen Markierung; das Label ist das plattformnative Abzeichen daneben (Best-Effort – siehe Schritt 4). Wenn ein Team jemals eine obligatorische KI-Offenlegung für die Prüfung benötigt, wird diese dann als Konfigurations-Flag wieder eingeführt – bewusst jetzt nicht gebaut.

Backport (Ziel ist release/*):

• Titel (Jira-Tracker): [acme-xxxxx] [release] <Zusammenfassung>; (GitHub Issues-Tracker): #<n> [release] <Zusammenfassung>.
• Beschreibung ist der Ticket-Link, dann cherry pick von <PR-Link>, wobei der Backend-Adapter die PR-Link-Syntax liefert (Azure DevOps !<pr_number>, GitHub #<pr_number> – beide werden als Link zu diesem PR dargestellt), dann – nur wenn die Herkunft aktiviert ist (Schritt 3, Punkt 5) – die KI-Herkunfts-Fußzeile (--- + 🤖 _Entworfen mit Claude Code._). Kein Zusammenfassungsblock, keine Aufzählungspunkte oder Diagramm – die eigentliche Überprüfung fand im ursprünglichen PR statt.
• Den Benutzer nach der (oder als Eingabe akzeptieren) Quell-PR-Nummer fragen, von der der Cherry-Pick stammt, und die einzeilige Zusammenfassung dieses PRs für <Zusammenfassung> wiederverwenden. Ein Backport lernt nur die Titel-Schreibweise, nicht das Beschreibungs-Layout.

Auf jedem Pfad (einschließlich des Backports): Titel und Beschreibung sind in Englisch. Keinen Co-Authored-By-Trailer von sich aus hinzufügen – es ist eine Commit-Angelegenheit, keine PR-Beschreibungs-Angelegenheit, und ob dieses Repo einen möchte, ist die Entscheidung des Repos, beobachtbar aus seiner eigenen Historie (git log -n 50 --format=%b | grep -c '^Co-Authored-By'), nicht etwas, das diese Skill entscheidet. Standardmäßig nicht hinzufügen; wenn die Commits des Repos ihn regelmäßig tragen, dem folgen, anstatt ihn zu überschreiben. Die KI-Herkunfts-Fußzeile und das ai-assisted-Label sind eine andere Sache und sind standardmäßig deaktiviert – werden nur auf die explizite Zustimmung hinzugefügt, die in Schritt 3 (Fußzeile) beschrieben ist, und in Schritt 4 (Label) angewendet – und sind niemals der verbotene Trailer.

Schritt 4 – Präsentieren, bestätigen, erstellen

Den entworfenen Titel und die Beschreibung anzeigen und dem Benutzer erlauben, sie zu bearbeiten. Dann:

• Eigenständig: nur erstellen, nachdem der Benutzer explizit bestätigt hat. Wenn der Quell-Branch noch nicht auf dem Remote ist, ihn zuerst veröffentlichen (git push -u origin <branch>), dann den PR über das Erstellungsrezept des Backend-Adapters erstellen – die vollständige Beschreibung in eine temporäre Datei schreiben und als Body-Datei-Flag des Adapters übergeben, niemals als Inline-String. Der Adapter dokumentiert die Dateikodierungs-Fallen der Plattform (z.B. Azure DevOpss az.cmd cp1252/UTF-8 @<Datei>-Eigenheiten) und – nur wenn die Herkunft aktiviert ist (Schritt 3) – wie das ai-assisted-Label angewendet wird (Azure DevOps erstellt das Tag inline über --labels; GitHub fügt es nach dem Erstellen mit gh pr edit --add-label hinzu, da gh pr create --label abbricht, wenn das Label nicht existiert). Wenn aktiviert, ist das Label in beiden Fällen Best-Effort (siehe Genannte Einschränkungen); standardmäßig wird kein Label angewendet. Die PR-URL zurückgeben.
• Kann keine Bestätigung einholen (läuft nicht-interaktiv oder innerhalb eines Subagenten, der keine Eingabeaufforderung geben kann): den Branch nicht pushen und den PR nicht erstellen. Den vorbereiteten Titel und die Beschreibung zur manuellen Erstellung für den Benutzer ausgeben und dies mitteilen. In einem nicht-interaktiven Kontext kein Im-Browser-öffnen-Flag verwenden (z.B. Azure DevOps --open). Wenn die Herkunft aktiviert war, trägt die ausgegebene Beschreibung bereits die Fußzeile; dem Benutzer sagen, das ai-assisted-Label hinzuzufügen, wenn er den PR erstellt. Standardmäßig (keine Zustimmung) wird keine Markierung ausgegeben oder erwähnt.

Die Invariante: niemals den Branch veröffentlichen oder einen PR ohne explizite menschliche Bestätigung öffnen – beides sind nach außen gerichtete Aktionen.

Sicherheitsmechanismen

• Niemals Merge-Konflikte automatisch auflösen – stoppen und melden.
• Niemals Branches löschen.
• Niemals ohne explizite Anfrage Force-Push durchführen.

Genannte Einschränkungen

• Wenn das PR-Tool der erkannten Plattform fehlt oder nicht authentifiziert ist (siehe Vorbedingung jedes Backend-Adapters – z.B. az + die azure-devops-Erweiterung für Azure DevOps, gh authentifiziert für GitHub), dies mitteilen und den vorbereiteten Titel und die Beschreibung zur manuellen Erstellung ausgeben – nicht stillschweigend fehlschlagen.
• Gelernte Konvention ist Best-Effort: Wenn ein Squash-Workflow keinen Beschreibungs-Body hinterlassen hat, stammt die Schreibweise dennoch aus dem Commit-Betreff, und das Layout fällt auf den Standard zurück – angekündigt, nicht stillschweigend.
• Herkunftsmarkierungen sind standardmäßig deaktiviert – keine Fußzeile und kein Label, es sei denn, die aufrufende Anfrage aktiviert sie explizit (Schritt 3, Punkt 5). Wenn aktiviert, ist das ai-assisted-Label Best-Effort: Wenn die Plattform es ablehnt (eine Organisation, die Ad-hoc-PR-Tags auf Azure DevOps verbietet, oder ein Label, das auf GitHub noch nicht existiert), das Label weglassen, den PR nur mit der Fußzeile (der aktivierten Markierung) erstellen und dies mitteilen – der Backend-Adapter dokumentiert das plattformspezifische Verhalten.