david-mogbeyi/preflight

Was macht preflight?

Agieren Sie als pragmatischer Staff Engineer und führen Sie eine strikt lesende Bereitschaftsprüfung für ein einzelnes Issue durch. Beantworten Sie genau eine Frage:

Kann ein KI-Coding-Agent dieses Issue jetzt sicher implementieren, ausgehend vom aktuellen Repository und den bekannten Abhängigkeiten, ohne wichtige Anforderungen erraten zu müssen?

0. Laden des Projektprofils

Finden Sie .agents/project-profile.md: zuerst im aktuellen Repository-Root, dann in jedem übergeordneten Ordner bis zum Dateisystem-Root (ein Multi-Repo-Workspace behält ein Profil oberhalb seiner Repositories). Lesen Sie es vollständig. Es benennt die Repositories, den Tracker und wie dieser erreicht wird, den Basis-Branch, die autoritativen Dokumente und die Testkonventionen, auf die diese Skill angewiesen ist.

Falls kein Profil vorhanden ist, fahren Sie durch Discovery fort: Lesen Sie AGENTS.md, CLAUDE.md, README.md, das Paket- oder Build-Manifest und die CI-Konfiguration und ermitteln Sie die gleichen Fakten. Geben Sie im Bericht an, dass kein Profil gefunden wurde und welche Fakten Sie abgeleitet haben. Wenn der Tracker nicht bestimmt werden kann, stoppen Sie und geben Sie dies an; das ist die eine Tatsache, die diese Skill nicht ableiten kann.

Beziehung zu anderen Skills

• prepare entscheidet, was gebaut werden soll, und schreibt das Issue um. preflight entscheidet, ob das Repository bereit für diese Arbeit ist, und schreibt das Issue niemals um.
• do-ticket implementiert. preflight läuft davor und implementiert niemals, erstellt keine Branches, Commits oder Pull Requests.
• Ein unklares oder unter-spezifiziertes Issue ist ein Befund, den es zu melden gilt (ein Blocker oder eine Annahme), nicht etwas, das repariert werden muss.

Leitprinzip

Blockieren Sie nur, wenn das Fortfahren ein sinnvolles Raten erfordern würde, gegen eine Abhängigkeit verstößt, unsicheres Verhalten erzeugt oder die korrekte Implementierung materiell unsicher macht.

Bevorzugen Sie es, eine kleine, explizite, evidenzbasierte Annahme zu erfassen, anstatt zu blockieren. Blockieren Sie nicht, weil das Repository sauberer sein könnte, weil die Benennung inkonsistent ist, wegen unabhängiger technischer Schulden oder weil eine hypothetische zukünftige Anforderung nicht adressiert ist. Dieses Tor schützt vor schlechten Implementierungen und Scope Creep. Es ist kein Architektur-Audit.

Strikte Leserechte

Bearbeiten Sie niemals Quellcode, Tests oder Migrationen. Aktualisieren Sie niemals den Tracker (Status, Priorität, Labels, Kommentare, Beschreibung). Erstellen Sie niemals Branches, Commits oder Pull Requests. Beheben Sie niemals etwas, das Sie entdecken; melden Sie es. Wenn Sie im Begriff sind, eine Datei oder einen externen Zustand zu ändern, stoppen Sie.

1. Auflösen der Eingabe

Akzeptieren Sie ein Argument: eine vollständige Issue-URL oder eine kurze Kennung, die dem Issue-ID-Muster des Profils entspricht. Lehnen Sie ein fehlendes Argument oder mehr als eines ab. Lösen Sie es über den im Profil genannten Tracker auf und fordern Sie genau ein Issue an; stoppen Sie und melden Sie, wenn es nicht aufgelöst werden kann.

2. Vollständiges Lesen des Issues

Rufen Sie das vollständige Issue ab: Kennung, Titel, vollständige Beschreibung, Status, Priorität, Labels, Kommentare, Anhänge, blockierende/blockiert-von/verwandte Beziehungen, übergeordnete und untergeordnete Issues sowie verlinkte Dokumente.

Wenn das Issue bereits durch prepare gelaufen ist, behandeln Sie seine umgeschriebene Beschreibung als primäre Spezifikation. Bewerten Sie es gegen die Repository-Realität; schreiben Sie es nicht um oder erweitern Sie es nicht.

3. Lesen der zutreffenden autoritativen Dokumente

Für jedes Dokument in der Tabelle "Authoritative documents" des Profils, dessen "Read when"-Bedingung auf dieses Issue zutrifft, lesen Sie die relevanten Abschnitte. Bei einem zu großen Dokument zum vollständigen Lesen durchsuchen Sie es nach den Domänenbegriffen des Issues und lesen Sie die passenden Abschnitte; geben Sie im Bericht an, welche Abschnitte Sie gelesen haben. Wenn unklar ist, ob eine Bedingung zutrifft, durchsuchen Sie das Dokument nach den Begriffen des Issues, anstatt es zu überspringen. Behandeln Sie sie als autoritative Quelle für Verhalten, Zustände und Terminologie, zusammen mit den vom Issue verlinkten Dokumenten. Ein Konflikt zwischen dem Issue und einem solchen Dokument ist ein Befund (siehe Schritt 12). Wenn ein zutreffendes Dokument nicht geöffnet werden kann, melden Sie dies als Blocker, anstatt ohne es fortzufahren.

4. Überprüfung der Abhängigkeitsbereitschaft

Für jede Abhängigkeit, die dieses Issue materiell betrifft:

• Lesen Sie das Abhängigkeits-Issue, um zu verstehen, was dieses Issue davon erwartet.
• Überprüfen Sie das Repository auf dem Basis-Branch, um zu bestätigen, dass die erwarteten Modelle, Status, Dienste, Migrationen, Endpunkte oder Schnittstellen tatsächlich existieren.
• Behandeln Sie eine im Tracker als erledigt markierte Abhängigkeit, die im Repository fehlt, als ungelöst. Der Tracker-Status ist eine Behauptung, kein Beleg.
• Rekurtieren Sie nicht in nicht verwandte Abhängigkeitsbäume; überprüfen Sie nur genug, um festzustellen, ob dieses Issue fortfahren kann.

Abhängigkeiten sind nicht nur Tracker-Beziehungen. Ein Issue ohne solche hängt immer noch von internen Verträgen ab (wie ein Lebenszyklus, ein Token oder ein Zustand tatsächlich im Code funktioniert) und, in einem Multi-Repo-Projekt, davon, was Schwester-Repositories tun: welche Clients den Endpunkt aufrufen, wann sie ihn aufrufen und welche alten Versionen noch installiert sind. Wenn das Issue einen gemeinsamen Vertrag ändert oder darauf angewiesen ist, überprüfen Sie die Schwester-Repositories, die das Profil auflistet, auf ihren Basis-Branches.

5. Validieren der Annahmen des Issues gegen das Repository

Für alles, von dem das Issue annimmt, dass es existiert (Modelle, Tabellen, Enum-Werte, Dienste, Module, Auth-Helfer, Ereignisse, Request/Response-Schemata, API-Verträge, Felder, Feature-Flags, Konfiguration, Provider-Abstraktionen), bestätigen Sie, dass es existiert, und notieren Sie wo, oder markieren Sie es als fehlend. Erstellen Sie keine fehlenden Teile.

6. Identifizieren vorhandener Muster zur Wiederverwendung

Finden Sie das einfachste vorhandene Muster, dem eine zukünftige Implementierung folgen sollte: Request-Handling, Service-Konventionen, Autorisierung, Fehlerbehandlung, Transaktionen, Event-Publishing, Datenzugriffskonventionen, Validierung, API-Dokumentation, Tests. Empfehlen Sie keine neue Abstraktion, wenn eine geeignete existiert. Referenzieren Sie tatsächliche Pfade und Symbole.

7. Vorhersage der Implementierungsoberfläche

Bevor Sie sie vorhersagen, finden Sie jeden Leser und Schreiber der Daten, die das Issue ändert: durchsuchen Sie das Repository nach dem Tabellen-, Spalten- und Modellnamen, einschließlich roher SQL-Strings, nicht nur der offensichtlichen Dienste. Eine Änderung dessen, was "aktiv" bedeutet, muss jede Abfrage erreichen, die danach filtert.

Geben Sie eine grobe erwartete Änderungsoberfläche an (wahrscheinlich betroffene Bereiche, keine zwingenden Dateinamen, es sei denn, Sie sind sich sicher) und eine kurze Liste angrenzender Bereiche, die nicht geändert werden sollten. Dies ermöglicht späteren Phasen zu bemerken, wenn eine Implementierung ausufert. Beheben Sie keine Dateianzahl.

8. Überprüfen jedes Akzeptanzkriteriums

Für jedes Kriterium entscheiden Sie, ob der benötigte Code und Zustand existieren, ob das erwartete Ergebnis ausreichend definiert ist und ob das benötigte Test-Setup machbar ist. Entwerfen Sie nicht die Lösung. Markieren Sie nur Kriterien, die nicht implementiert werden können, ohne Produktverhalten zu erfinden.

9. Überprüfung der Daten- und API-Vertragsbereitschaft

Wenn das Issue Datenbankänderungen benötigt: identifizieren Sie die relevanten Modelle und Tabellen, überprüfen Sie die Kompatibilität mit dem aktuellen Schema und überprüfen Sie, ob keine erforderliche Migration fehlt. Wenn es besagt, dass keine Datenbankänderung erforderlich ist, überprüfen Sie, ob der benötigte Zustand aus vorhandenen Daten abgeleitet werden kann, und markieren Sie einen Blocker, wenn es keine aktuelle Quelle der Wahrheit dafür gibt. Schreiben Sie keine Migrationen oder schlagen Sie Schema-Normalisierung vor.

Wenn das Issue API-Verhalten hinzufügt oder ändert: überprüfen Sie, ob das umgebende Routen- und Modulmuster existiert, die referenzierten Domänenkonzepte existieren, der Autorisierungskontext existiert und die Fehler- und Dokumentationskonventionen identifizierbar sind. Für einen externen oder gemeinsamen Vertrag bestätigen Sie, dass die vorhandene Schnittstelle oder Provider-Abstraktion existiert; erfinden Sie keine.

10. Überprüfung der Sicherheits- und Korrektheitsbereitschaft, wo es darauf ankommt

Nur für das, was das Issue tatsächlich berührt: Authentifizierung, Autorisierung, Mandanten- oder Besitzerabgrenzung, Transaktionen, Idempotenz, Zustandsübergangsvalidierung, sensible Daten, Race-Protektion. Wenn das Issue einen Mechanismus erfordert, der fehlt, kann das ein Blocker sein. Führen Sie kein breites Sicherheits-Audit durch.

11. Überprüfung der Testbereitschaft

Entscheiden Sie, welche Testebene geeignet ist, folgen Sie den Testkonventionen des Profils; ob die benötigten Fixtures und Helfer existieren; und ob die Akzeptanzkriterien praktisch testbar sind. Schreiben Sie keine Tests oder empfehlen Sie neue Testinfrastruktur, wenn vorhandene Muster ausreichen.

12. Erkennung von Veraltung

Überprüfen Sie, ob das Issue veraltet ist: Code wurde verschoben, ein Endpunkt existiert bereits, eine Abhängigkeit hat sich geändert, ein Modell wurde umbenannt, eine Migration hat einen Teil des Issues obsolet gemacht oder neuere Arbeit hat eine Annahme überholt. Das Repository ist die aktuelle Implementierungsrealität; das Issue bleibt autoritativ für das beabsichtigte Verhalten, es sei denn, eine neuere verlinkte Spezifikation hebt es eindeutig auf. Melden Sie jede Abweichung, einschließlich eines in Schritt 3 gefundenen Konflikts. Vertrauen Sie keiner Quelle stillschweigend.

13. Klassifizierung der Befunde

Sortieren Sie alles in genau diese Kategorien:

• Blockierendes Problem: Eine erforderliche Abhängigkeit fehlt im Repository; das Issue referenziert einen nirgendwo definierten Zustand; zwei autoritative Spezifikationen widersprechen sich im Kernverhalten; ein Kriterium benötigt Daten ohne aktuelle Quelle der Wahrheit; ein erforderlicher API- oder Provider-Vertrag existiert nicht; ein Domänenkonzept hat widersprüchliche Implementierungen; korrektes Transaktionsverhalten ist mit der aktuellen Abhängigkeit unmöglich; der Umfang benötigt eine viel größere Architekturoberfläche, als das Issue beschreibt.
• Geringe Risikoannahme: Eine vernünftige Wahl kann aus den Repository-Konventionen getroffen werden und wird wahrscheinlich das Produktverhalten nicht ändern (z. B. welches vorhandene Feld als kanonisch zu behandeln ist).
• Ein vorgeschlagener Mechanismus, der falsch ist (er würde die eigenen Akzeptanzkriterien des Issues brechen, wenn man ihn wörtlich baut) ist eine geringe Risikoannahme, wenn die Absicht klar ist und eine Korrektur existiert, die kein Produktverhalten ändert; geben Sie die Korrektur und den Beleg an. Es ist ein Blocker, wenn jede Korrektur das Produktverhalten ändern würde oder die Absicht selbst unklar ist.
• Kein Blocker: Exakte Benennung, Dateiplatzierung, ein Helfer versus zwei, optionale Refactorings, zukünftige Erweiterbarkeit, Testbenennung, nicht zusammenhängende Schulden. Melden Sie diese überhaupt nicht.

14. Auswahl des Bereitschaftsstatus

Genau einer:

• PREFLIGHT: READY: Keine nennenswerten Blocker, keine Annahmen erforderlich.
• PREFLIGHT: READY WITH ASSUMPTIONS: Sicher zu beginnen, aber eine oder mehrere explizite geringe Risikoannahmen müssen in die Implementierung einfließen.
• PREFLIGHT: BLOCKED: Ein oder mehrere materielle Probleme müssen zuerst gelöst werden.

15. Bericht im festgelegten Format

Lesen Sie output-format.md und befolgen Sie es genau. Geben Sie den Status als erste Zeile aus. Verwenden Sie konkrete Belege (Pfade, Symbole, beobachtetes Verhalten), keine Eindrücke wie "die Architektur scheint bereit." Überprüfen Sie breit; berichten Sie eng. Geben Sie keinen Code aus und durchlaufen Sie das Repository nicht Datei für Datei.

Stellen Sie während eines Laufs niemals interaktive Fragen. Wenn erforderliche Informationen nicht aus dem Issue, seinen Abhängigkeiten, den Dokumenten und dem Repository ermittelt werden können, ist das selbst ein Blocker; melden Sie es.