asanabrial/issue-flow

Issue Flow — Analyst / Entwickler über ein gemeinsames Issue-Tracking-System

Aktivierungsvertrag

Verwenden für issue-flow analyst [bedingungen], issue-flow dev [domänenregeln] [issue-nummer], Analysten- oder Entwicklerarbeit, Beanspruchungen und Workflow-Zustandsübergänge. Analystenbedingungen und Entwicklerdomänen sind optional: Ein begrenztes Ziel bildet den Umfang; andernfalls prüft der Analyst das Repository und der Entwickler implementiert das ausgewählte Issue. Lesen Sie zuerst die Repository-Anweisungen und laden Sie nur die von der Bedienerkonfiguration ausgewählte Tracker-Bindung, bevor Sie mit der Tracker-Arbeit beginnen. Laden Sie Domänenzusammensetzung für Übergabe-, Prioritäts- oder Routing-Regeln; Laufzeithinweise für Aufruf, Delegation oder Team-Mechaniken; und Sicherheitsvorfälle für Renn-, Rückforderungs-, Übergabe- oder Fehlerbegründung.

Harte Regeln

• Issue Flow besitzt Rollen, Zustände, Beanspruchungen und Übergänge; geroutete Domänen besitzen Wert, Priorität, Evidenz und Fertigstellungskriterien. Keine Seite erfindet die Richtlinie der anderen.
• Ein Analyst, einschließlich eines gegnerischen Prüfers, ist schreibgeschützt für das Repository und jedes externe System außer den unten erforderlichen konfigurierten Tracker-Operationen: Er erstellt keinen Branch/Worktree/Commit/PR und führt keine Migration, Synchronisation, Datenbankschreiboperation oder Lieferaktion durch. Er erstellt höchstens ein evidenzbasiertes Issue. Die Überprüfung MUSS einen Kontext verwenden, der die Änderung nicht geschrieben hat.
• Prägen Sie eine <laufzeit>-<sitzungspräfix>-Laufzeit-ID und verwenden Sie sie für jeden Schreibvorgang wieder. Halten Sie eine begrenzte Laufzeitzuordnung in analyst:<laufzeit>/dev:<laufzeit>-Labels und eine unbegrenzte Laufzeit-ID-Zuordnung im Text bei; Analysten-Labels bleiben bestehen, während Entwickler-Labels bei Freigabe entfernt, aber bei Lieferung beibehalten werden.
• Nehmen Sie das gehaltene Issue dieser Laufzeit wieder auf, bevor Sie Warteschlangen konsultieren. Verwenden Sie den zeitlich bereinigten Anspruch der ausgewählten Bindung; der früheste aktive Anspruch gewinnt. Führen Sie verify_claim vor dem ersten Repository-Schreibvorgang, jedem Heartbeat und jeder teuren oder irreversiblen Grenze aus; eine nicht lesbare Kontrolloberfläche erlaubt keinen Schreibvorgang.
• Halten Sie genau einen der Zustände analysis, ready, in-progress, review, blocked oder done. Der Workflow-Zustand der Bindung ist maßgeblich; jede konfigurierte Projektion wird aktualisiert und zurückgelesen, und done wird vor dem Schließen des Trackers explizit gesetzt.
• Die ausgewählte Bindung MUSS ensure_states, create, list_state, claim, reclaim, verify_claim, heartbeat, transition, comment, last_activity, label, unassign, publish_version und close abbilden. Führen Sie ausführbare reversible Operationen aus, anstatt sie zu rekonstruieren; Bindungen MÜSSEN nicht unterstützte Fähigkeiten deklarieren und bei Fehlern schließen.
• Die Abnahmekriterien des Issues, die gerouteten Domänenregeln und die Repository-Regeln definieren die Fertigstellung. Erfinden Sie niemals fehlende Tore oder interpretieren Sie das Issue stillschweigend neu.

Entscheidungsgatter

Situation	Aktion
Analyst hat Bedingungen oder einen begrenzten Diff/PR/Issue	Analysieren Sie nur diesen Umfang unter den geltenden Repository- und Domänenregeln.
Analyst hat keine Bedingungen oder Domäne	Verwenden Sie den autonomen general-Vertrag in Domänenzusammensetzung; erstellen Sie nur den stärksten deduplizierten Befund oder nichts.
Eine Domänenroute ist aufgezeichnet	Der Analyst lädt das linke Regelbuch; der Entwickler lädt das rechte. Geben Sie explizit an, wenn die Implementierungsroute fehlt.
Laufzeitmechaniken oder die Erfassung unabhängiger Kontexte variieren	Befolgen Sie Laufzeithinweise; Laufzeitbeschränkungen ändern den Mechanismus, niemals die Invariante.
Sicherheit von Beanspruchung, Rückforderung oder Übergabe benötigt Begründung	Befolgen Sie die aktive Bindung und Sicherheitsvorfälle, ohne die Vorfallbeschreibung hier zu kopieren.
Zustand muss gewählt werden	Ungültige Spezifikation -> analysis; implementierbar und nicht zugewiesen -> ready; beanspruchter Build -> in-progress; gebaut/veröffentlicht -> review; nicht gebaute externe Wartezeit -> blocked mit Bedingung und Auslöser; zusammengeführt und verifiziert -> done.

Ausführungsschritte

Führen Sie vor dem ersten Tracker-Schreibvorgang einer Rolle in einem unbekannten Projekt ensure_states der ausgewählten Bindung aus; verwenden Sie dann deren ausführbare Operationen und Rücklesevorgänge, anstatt sie zu rekonstruieren. Laden Sie Domänenzusammensetzung für Routing, Skalierungsvalidierung, Warteschlangenpartitionierung oder autonomen Fallback; Laufzeithinweise für Aufruf, Schreibschutzdurchsetzung, Erfassung unabhängiger Kontexte oder Laufzeitbeschränkungen; Sicherheitsvorfälle nur, wenn eine Begründung für Beanspruchung, Rückforderung, Übergabe oder Fehler benötigt wird; und Repository-Auslieferung nur, wenn Repository-Regeln Isolation oder Integration nicht vollständig definieren.

Analyst

1. Halten Sie das Repository und nicht zum Tracker gehörende externe Systeme schreibgeschützt. Bearbeiten Sie analysis zuerst, älteste zuerst, dann prüfen Sie blocked: Verschieben Sie erfüllte Bedingungen mit Evidenz zu ready, datieren Sie Bedingungen, die noch gelten, und geben Sie an, wie lange eine Person eine ausstehende Entscheidung schuldet.
2. Analysieren Sie nur den begrenzten Umfang unter dem linken Domänenregelbuch. Ohne Bedingungen oder Domäne verwenden Sie den autonomen general-Vertrag; überprüfen Sie Evidenz und Duplikate, dann behalten Sie höchstens den stärksten vertretbaren Befund oder melden Sie, dass keiner überlebt hat.
3. Validieren Sie die Felder, Route, Skalierung und den Textkörpervertrag für in der Warteschlange befindliche und neue Befunde. Fügen Sie bei in der Warteschlange befindlicher Arbeit fehlendes Übergabematerial mit comment hinzu und überführen Sie nur dasselbe vollständige Element; erstellen Sie niemals einen Ersatz. Füllen Sie für einen neuen Befund die Analysten-Issue-Vorlage aus und create Sie sie mit jedem Marker plus analyst:<laufzeit> und Laufzeit-ID-Zuordnung. Verwenden Sie ready oder blocked mit der genauen fehlenden Bedingung und dem Auslöser; dann STOPPEN Sie, ohne es zu implementieren oder zuzuweisen.

Was der Analyst produziert

Ein Issue, das ein Entwickler ohne Wiederholung der Analyse aufnehmen kann. Wenn der Entwickler Ihre Argumentation neu ableiten muss, hat die Analyse nichts gebracht.

## Beschreibung für dumme Menschen

> [!NOTE]
> Ein oder zwei Sätze, einfache Sprache, kein Jargon, keine Dateipfade, keine Metriken – worum es bei diesem Issue geht, für jemanden, der niemals über diese Zeile hinauslesen wird. Geschrieben in der Sprache, die die Bedienerkonfiguration für diese Installation angibt (siehe Tabelle am Ende dieser Datei). Die Kopfzeile selbst ist der feste, wörtliche Titel oben – immer auf Englisch, immer genau dieser Ausdruck, niemals pro Issue umformuliert. `> [!NOTE]` ist die native Alarm-Syntax von GitHub – sie rendert als umrandeter, farbiger Hinweis, was der Punkt ist: Dies muss visuell unmöglich zu übersehen sein, wenn ein Issue ansonsten voller technischer Prosa ist.

Dies ist das Erste im Issue, vor `## Problem`.

## Problem
Was ist falsch oder fehlt, und woher Sie es wissen. Evidenz, keine Behauptung: Datei:Zeilen-Verweise, gemessene Zahlen, Logs, Reproduktionsschritte.

## Warum es wichtig ist
Auswirkungen, wenn es ignoriert wird. Wenn Sie keine nennen können, sagen Sie es klar – eine dokumentierte "geringe Auswirkung, der Vollständigkeit halber eingereicht" ist ehrlich und ermöglicht dem Entwickler eine Herabstufung.

## Vorgeschlagener Ansatz
Das Design. Alternativen, die Sie in Betracht gezogen haben, und warum Sie sie verworfen haben. Wenn Sie NICHT sicher sind, geben Sie an, welcher Teil unsicher ist und was ihn klären würde.

## Abnahmekriterien
Überprüfbare Aussagen. "Schneller" ist kein Kriterium; "p95 unter 200 ms, gemessen durch X" ist es. Schließen Sie ein, was sich NICHT ändern darf (Invarianten, byteidentische Ausgaben).

## Nicht im Umfang
Was ein Entwickler hier explizit nicht tun sollte. Dies verhindert Umfangsausweitung zuverlässiger als jede Menge Prosa in den obigen Abschnitten.

## Evidenz
Ausgeführte Befehle, gelesene Dateien, gemessene Zahlen. Genug, dass ein Prüfer die Analyse überprüfen kann, ohne sie zu wiederholen.

Entwickler

1. Nehmen Sie das gehaltene Issue dieser Laufzeit an seinem aufgezeichneten Zustand wieder auf, bevor Sie Warteschlangen konsultieren. Andernfalls bearbeiten Sie nicht zugewiesene review vor ready, wobei Sie den Lieferblocker erneut prüfen, bevor Sie veröffentlichte Arbeit beanspruchen.
2. Partitionieren Sie für ready gültige Kandidaten nach stabiler Domäne und deklariertem Maßstab, bewerten Sie nur innerhalb jeder Partition und wählen Sie den ältesten Partitionskopf; eine ausgewählte Domäne schränkt die Auswahl auf ihr höchstbewertetes ältestes Element ein. Verwenden Sie älteste zuerst nur, wenn kein Kandidat einen gültigen Maßstabsvertrag hat.
3. claim mit der Laufzeit-ID und dem Horizont, dann entscheiden Sie über den Server-Zeitstempel-Zeitstrahl; der früheste aktive Anspruch gewinnt, und ein Verlierer kommentiert, gibt frei und wählt erneut aus. Behalten Sie beanspruchte Überprüfungsarbeit in review, es sei denn, eine Codeänderung erfordert in-progress und einen neuen Veröffentlichungs-/Überprüfungs-/CI-Zyklus; für bereite Arbeit übergehen Sie einmal zu in-progress mit dev:<laufzeit> und keinem zweiten Beanspruchungsereignis.
4. Laden Sie das rechte Implementierungsregelbuch der Route, bevor Sie planen; wenn es fehlt, geben Sie an, dass keines gilt und bauen Sie gemäß den schriftlichen Abnahmekriterien. Befolgen Sie die Repository-Regeln, verwenden Sie den Repository-Auslieferungs-Fallback für fehlende Isolations-/Integrationsrichtlinie, verifizieren Sie den Anspruch unmittelbar vor dem ersten Branch-/Worktree-/Datei-Schreibvorgang und implementieren Sie im isolierten Checkout.
5. Verlängern Sie vor der Veröffentlichung, veröffentlichen Sie das gemeinsame Überprüfungsziel oder verwenden Sie es wieder, dann übergehen Sie zu review. Erfassen Sie einen unabhängigen Kontext nur, wenn Überprüfungsdelegierung diese Laufzeit autorisiert; fordern Sie andernfalls eine separat gestartete Überprüfung an. Erfordern Sie sein Urteil und grünes CI auf demselben genauen Head/Base; jeder Push macht beide ungültig. Hinterlassen Sie blockierte Lieferung in review, stellen Sie den lokalen Zustand wieder her, der durch den fehlgeschlagenen Versuch geändert wurde, zeichnen Sie den genauen Blocker auf und heben Sie die Zuweisung auf, anstatt ihn zu umgehen; widersprüchliche Repository-Regeln erhalten ein separates Issue.
6. Verlängern Sie an jeder irreversiblen Grenze; führen Sie nur zusammen, wenn überprüft, grün und aktuelle Head/Base-Identitäten übereinstimmen. Erfordern Sie für eine Merge-Commit-Route, dass die genauen Eltern der gelieferten SHA die überprüfte Base und Head sind; andere konfigurierte Strategien erfordern ihre bindungsdeklarierte äquivalente Topologie und jedes gelieferte SHA-Tor. Veröffentlichen und verifizieren Sie für jede geänderte Version das unveränderliche annotierte Tag und die erforderliche Freigabe; verlängern Sie erneut, übergehen Sie zu done, zeichnen Sie Überprüfung/CI/Tests/Messungen/PR/liefernde SHA/Veröffentlichungen mit der Laufzeit-ID auf und schließen Sie. Bewahren Sie bei Übergabe alle Evidenz: falsche Spezifikation geht zu analysis, nicht gebaute externe Wartezeit zu blocked, gebaute, aber nicht lieferbare Arbeit zu review und eine nützliche Teildiagnose zu ready.

Detailliertes Überprüfungsgatter, das bis zum endgültigen Zurückziehungs-Slice beibehalten wird

6. Lassen Sie die veröffentlichte Änderung von einem Kontext überprüfen, der sie nicht geschrieben hat, und erfordern Sie dann grünes CI auf dem neuesten PR-Head. Erfassen Sie die Head- und Base-SHAs vor der Überprüfung und verlangen Sie, dass das Urteilsartefakt beide explizit nennt; ein fließendes "genehmigt" ist keine Evidenz für eine bestimmte Revision oder einen bestimmten Diff. Wo die Konfiguration es autorisiert, beschaffen Sie sich diesen Kontext selbst – einen Unteragenten oder Teamkollegen; wo nicht, übergeben Sie den PR einem separat gestarteten Analystenlauf und sagen Sie im Issue, dass Sie darauf warten. Was die Konfiguration entscheidet, ist, wer die Überprüfung startet, niemals, ob sie läuft. Jeder Push macht das vorherige Urteil und CI-Ergebnis ungültig: Überprüfen Sie die geänderte Oberfläche erneut und warten Sie erneut auf die erforderlichen Prüfungen.

   Wenn Überprüfung, CI oder Lieferung blockiert ist, STOPPEN SIE DORT und lassen Sie es in review. Arbeit, die gebaut und veröffentlicht, aber nicht ausgeliefert werden kann – ein Prüfer fordert Änderungen, eine Prüfung schlägt fehl, erforderliche native Genehmigung kann nicht von einer eindeutigen Identität geliefert werden, eine Berechtigung fehlt, zwei Projektregeln widersprechen sich – ist abgeschlossene Arbeit, die auf Lieferung wartet, was genau review bedeutet. Verschieben Sie es nicht zu done: Dieser Zustand bedeutet ausgeliefert. Umgehen Sie den Blocker auch nicht; eine Regel, die Sie umgehen, um auszuliefern, ist eine Regel, die aufhört, etwas zu bedeuten.

   Kommentieren Sie den Blocker präzise – was ihn abgelehnt hat, was dieses Ding erwartet, was das Projekt stattdessen benötigt – dann heben Sie die Zuweisung auf, damit ein anderer Akteur die Lieferung abschließen kann. Stellen Sie jeden lokalen Zustand wieder her, den Sie beim Versuch geändert haben.

   Ein Blocker, der aus zwei einander widersprechenden Projektregeln resultiert, verdient ein eigenes Issue. Er wird die nächste Aufgabe treffen und die danach, und jeder Lauf wird ihn von Grund auf neu diagnostizieren. Ein eingereichter Befund verwandelt eine wiederkehrende Steuer in eine Entscheidung, die jemand einmal treffen kann.

7. Führen Sie nur den überprüften PR-Head zusammen, nachdem sein erforderliches CI grün ist, veröffentlichen Sie alle Versionstags, dann close. Verlängern Sie den Anspruch unmittelbar vor dem Zusammenführen, erfordern Sie überprüfter Head/Base == CI Head/Base == aktueller Head/Base, binden Sie den Merge an den überprüften Head-SHA und lehnen Sie ab, wenn sich eine Seite bewegt hat. Verwenden Sie die konfigurierte Merge-Strategie; ein Merge-Commit bewahrt die Branch-Grenze und PR-Abstammung, während Squash und Rebase diese Informationen absichtlich verwerfen. Rufen Sie die gelieferte SHA nach dem Merge ab und verifizieren Sie, dass sie genau die überprüfte Base und den überprüften Head als Eltern hat; behaupten Sie keine Topologiebewahrung allein aus einem Befehlsflag. Eine Merge-Queue ist nur zulässig, wenn ihre konfigurierte Methode dieselbe Topologie garantiert. Wenn das Projekt CI auf der genauen gelieferten SHA erfordert, warten Sie auf dieses Post-Merge-Tor.

Arbeiten in einem Repository – der Standardablauf

Die Repository-Regeln gewinnen immer. Lesen Sie seine Agentenanweisungen (AGENTS.md, CLAUDE.md oder Äquivalent) vor allem anderen und befolgen Sie sie. Was folgt, ist der Fallback für ein Repository, das nichts vorschreibt, und eine Untergrenze für eines, das nur einen Teil vorschreibt – niemals ein konkurrierender Standard.

Der ältere Fallback – verwenden Sie die Commit-Historie als Konvention – reicht nicht so weit, und es lohnt sich zu sagen, warum. Ein Git-Log sagt Ihnen, wie Commit-Nachrichten geschrieben werden. Es kann Ihnen nicht sagen, ob zwei Agenten einen Checkout teilen dürfen oder ob ein Branch, der letzte Stunde verifiziert wurde, noch gültig ist, nachdem jemand anderes zusammengeführt hat. Diese Antworten entscheiden, ob parallele Arbeit sich selbst korrumpiert, also liefert diese Fähigkeit sie, anstatt sie einer Domäne zu überlassen, die keinen Grund hat, sie zu kennen.

1. Arbeiten Sie niemals im Basis-Baum. Für einen Entwickler ist der Standard-Branch schreibgeschützt: keine Bearbeitungen, keine Commits. Überprüfen Sie vor der ersten Änderung, anstatt anzunehmen:

git branch --show-current   # main / master -> stop, branch first

Wenn Sie feststellen, dass Sie bereits auf dem Basis-Branch committet haben und NICHT gepusht haben, verschieben Sie die Commits auf einen Branch und setzen Sie zurück. Wenn Sie bereits gepusht haben, führen Sie keinen Force-Push durch – machen Sie es rückgängig und wiederholen Sie es ordnungsgemäß.