pedro-oscar/shorts-ai

Frag Matt

Du erinnerst dich nicht an jeden Skill – also frag.

Bevor du beschreibst, was ein Skill tut, oder empfiehlst, einen Schritt zu überspringen, lies die SKILL.md dieses Skills: Die Zusammenfassungen hier dienen nur der Orientierung.

Ein Flow ist ein Pfad durch die Skills. Die meisten Pfade verlaufen entlang eines Hauptflusses, und zwei Auffahrrampen münden in ihn ein. Alles andere ist eigenständig oder eine darunterliegende Vokabularschicht.

Der Hauptfluss: Idee → Auslieferung

Der Weg, den die meiste Arbeit nimmt. Du hast eine Idee und möchtest sie umgesetzt haben.

1. /grill-with-docs schärft die Idee durch ein Interview. Starte hier, wenn du in einem Arbeitsverzeichnis arbeitest: Es ist zustandsbehaftet und behält das Gelernte in GLOSSARY.md und ADRs. (Kein Arbeitsverzeichnis? Verwende stattdessen /grill-me, das unter Eigenständig aufgeführt ist. Beide nutzen dieselbe /grilling-Primitive; grill-with-docs hinterlässt eine Papierspur und ist daher die bessere Wahl, wenn ein Repository vorhanden ist.)

2. Verzweigung: Kannst du jede Frage im Gespräch klären? Wenn eine Frage eine ausführbare Antwort benötigt (Zustand, Geschäftslogik, eine UI, die man sehen muss), mache einen Umweg über einen Prototypen, überbrückt durch /handoff in beide Richtungen (ein Prototyp lebt in einem eigenen Verzeichnis, genau wofür /handoff gedacht ist; siehe Phasengrenzen):

   • /handoff raus, dann öffne eine neue Session für diese Datei,
   • /prototype beantwortet die Frage mit Wegwerfcode,
   • /handoff zurück, was du gelernt hast, und referenziere es aus dem ursprünglichen Ideen-Thread.

3. Verzweigung: Ist dies ein Multi-Session-Build?

   • Ja → /to-spec (wandle den Thread in ein Lastenheft um), dann /to-tickets, um es in Tracer-Bullet-Tickets aufzuteilen, die jeweils ihre Blockierungskanten deklarieren. Arbeite die Tickets dann auf eine von zwei Arten ab:
     • /implement pro Ticket, mit /clear des Kontexts zwischen den Tickets. Auf einem lokalen Tracker ist das eine Datei pro Ticket unter .scratch/<feature>/issues/, manuell zuerst die blockierenden bearbeitet; auf einem echten Tracker werden die Kanten zu nativen Blockierungslinks, sodass jedes Ticket, dessen Blockierer erledigt sind, bearbeitet werden kann. Jedes Ticket ist in sich geschlossen, daher ist der Kontext des letzten Tickets wegwerfbar.
     • /implement-spec für das gesamte Lastenheft in einem Durchlauf. Es liest die Tickets als Aufgabengraph und führt Implementierer-Subagenten parallel über die bereite Frontier aus, um alles auf einem Integrationszweig zu landen. Greife darauf zurück, wenn du den Build lieber orchestrieren möchtest, anstatt jedes Ticket selbst zu treiben.
   • Nein → /implement direkt hier, im selben Kontextfenster.

   In beiden Fällen wird der Code durch die Verwendung von /tdd (eine Rot-Grün-Scheibe nach der anderen) erstellt und mit /code-review abgeschlossen, einer zweiachsigen Überprüfung (Standards + Spezifikation) des Diffs. /implement führt beide pro Ticket aus; die Implementierer von /implement-spec treiben jeweils /tdd und führen eine /code-review über den Integrationszweig durch. Greife auf /tdd allein zurück, wenn du nur ein konkretes Verhalten test-first ohne vollständiges Lastenheft umsetzen möchtest, und auf /code-review allein, wenn du einen Zweig oder PR gegen einen Fixpunkt überprüfen möchtest.

   Wenn die Arbeit als Pull-Request eingereicht wird, formt /pr den Body: die kleinste visuelle Darstellung der Änderung, Vorher-Nachher-Belege, dass es funktioniert, und eine Einweg- oder Zweiweg-Entscheidung. Es wird modellgesteuert aufgerufen, also greift der Agent darauf zu, wenn er einen PR schreibt.

4. /retro schließt den Kreis. Nach einem Build, insbesondere wenn er schiefgelaufen ist, blickt es auf die Session zurück und schlägt Änderungen an der Umgebung des Agenten vor, nicht am Code: Navigationshinweise, automatisierte Prüfungen, die von /code-review durchgesetzten Codierungsstandards, Steuerdateien, Tooling. Mechanische Fehler werden zu deterministischen Prüfungen; Ermessensentscheidungen werden zu Codierungsstandards. Der nächste Build beginnt dann in einer besseren Umgebung.

Kontexthygiene

Halte die Schritte 1–3 in einem ununterbrochenen Kontextfenster (nicht komprimieren oder löschen bis nach /to-tickets), damit das Grilling, das Lastenheft und die Tickets auf derselben Denkarbeit aufbauen. Jedes /implement beginnt dann frisch, ausgehend vom Ticket. Führe /retro in der Session aus, auf die es zurückblickt, bevor du löschst; nach dem Löschen richte es stattdessen auf das Log dieser Session.

Die Grenze hierfür ist die Smart Zone: das Fenster (~150k Tokens bei modernen Modellen), in dem das Modell noch scharf denkt. Wenn eine Session diese Grenze vor /to-tickets erreicht, nicht in degradiertem Zustand weitermachen; mit /compact an der nächsten Phasengrenze komprimieren und fortfahren (siehe Phasengrenzen).

Auffahrrampen

Eine Startsituation, die Arbeit erzeugt und dann in den Hauptfluss mündet.

• Bugs und Anfragen häufen sich → /triage. Es bewegt Issues durch Triage-Rollen und erzeugt agentenreife Issues, die /implement später aufgreift.

  Triage ist nur für Issues, die du nicht erstellt hast: Fehlerberichte, eingehende Feature-Anfragen, alles, was roh ankommt. Tickets, die /to-tickets erzeugt hat, sind bereits agentenreif, also triage sie nicht.

• Etwas ist kaputt → /diagnosing-bugs. Für die harten Fälle: der Bug, der dem ersten Blick widersteht, der intermittierende Flake, die Regression, die zwischen zwei bekannten guten Zuständen eingeschlichen ist. Es weigert sich zu theorisieren, bis es eine enge Rückkopplungsschleife hat (ein Befehl, der bei diesem Bug bereits rot wird), und behebt dann mit einem Regressionstest. Nach der Behebung führe in derselben Session /retro aus, um zu fragen, was den Bug verhindert hätte; wenn die eigentliche Erkenntnis ist, dass es keine gute Naht gibt, um ihn zu fixieren, ist das ein Job für /improve-codebase-architecture.

• Ein riesiges, nebelhaftes Vorhaben: ein Greenfield-Projekt oder ein riesiger Feature-Build, zu groß für eine Session → /wayfinder, der kognitiv anspruchsvollste Flow hier. Wenn der Weg von hier zum Ziel noch nicht sichtbar ist, erstellt es eine gemeinsame Karte von Entscheidungs-Tickets im Issue-Tracker und löst sie nacheinander auf, wobei es Entscheidungen, keine Liefergegenstände produziert, bis der Nebel sich gelichtet hat und der Weg klar ist. Wo /grill-with-docs eine Idee schärft, die du in einer Session halten kannst, ist Wayfinder für die Idee, die du nicht halten kannst, und es ist langsamer und dichter, also hebe es dir genau dafür auf, niemals für ein gut abgrenzbares Feature.

  Wenn die Karte klar ist, übergibt es, es baut nicht: Münde in den Hauptfluss bei /to-spec ein, das die verknüpften Entscheidungen der Karte in einen baubaren Plan zusammenführt, dann wie gewohnt zu /to-tickets und /implement. Die Karte direkt in /implement zu schleifen, überspringt diese Zusammenführung und wirft die verknüpften Details weg, also gehe nur dann direkt zu /implement, wenn das Vorhaben sich als wirklich klein herausstellt.

Code-Gesundheit

Keine Feature-Arbeit, nur Instandhaltung.

• /improve-codebase-architecture wird immer dann ausgeführt, wenn du einen freien Moment hast, um die Codebasis für den Betrieb durch Agenten gut zu halten. Es deckt Vertiefungsmöglichkeiten auf; eine auszuwählen erzeugt eine Idee, die du im Hauptfluss bei /grill-with-docs aufnehmen kannst. Es ist die Umfrage, die die Kandidaten findet; /codebase-design (unten) ist die Werkbank, auf der du den ausgewählten entwirfst.

Vokabular darunter

Zwei modellgesteuerte Referenzen, die unter den anderen Skills laufen, jede die alleinige Quelle der Wahrheit für ihr Vokabular. Greife direkt auf sie zu, wenn die Wörter, nicht der Prozess, das Problem sind; oder lass die obigen Skills sie einbinden.

• /domain-modeling: Schärfe die Domänen-Sprache des Projekts: hinterfrage einen unscharfen Begriff, löse ein überladenes Wort auf („Konto“ macht drei Jobs), halte eine schwer umkehrbare Entscheidung als ADR fest. Es ist die aktive Disziplin, die /grill-with-docs antreibt, um GLOSSARY.md als sauberes Glossar zu erhalten.
• /codebase-design ist das Tiefmodul-Vokabular (Modul, Schnittstelle, Tiefe, Naht, Adapter, Hebelwirkung, Lokalität) zum Entwerfen der Form eines Moduls: viel Verhalten hinter einer kleinen Schnittstelle an einer sauberen Naht. /tdd und /improve-codebase-architecture sprechen es beide.

Phasengrenzen

Eine Phase ist ein Arbeitsabschnitt innerhalb einer Session: das Grilling, die Implementierung, die Qualitätssicherung. An der Grenze zwischen zwei Phasen hast du fünf Optionen, und die Wahl zwischen ihnen ist die unscharfste Entscheidung in dieser gesamten Karte:

• Weitermachen: bleib, wo du bist. Kostet nichts, verliert nichts.
• /clear: leere das Fenster, wenn nichts hier für das Nächste relevant ist.
• /handoff schreibt eine portable Markdown-Datei. Eng gefasst: nur für eine neue Umgebung, ein neues Verzeichnis, einen Kollegen oder zum Abspalten einer Nebenaufgabe mitten in einer Phase. Was es kauft, ist Portabilität.
• Subagent: sende eine eng umrissene Aufgabe in ein eigenes Fenster und erhalte einen Bericht zurück.
• /compact komprimiert diesen Kontext und startet eine frische Session damit. Der Standard, ganz unten im Baum eher als der erste Griff.

Lies PHASE-BOUNDARIES.md für den geordneten Baum: die fünf Fragen, die Begründung hinter jedem Zweig und warum die Primärquellenkosten Weitermachen zu dem machen, das man zuerst ausschließen sollte. Triff die Entscheidung an einer Grenze; mitten in der Phase: weitermachen oder den Rest in Subagenten aufteilen.

Eigenständig

Völlig außerhalb des Hauptflusses.

• /grill-me: dasselbe unermüdliche Interview wie /grill-with-docs, aber zustandslos: es speichert nichts lokal und erstellt kein GLOSSARY.md. Greife darauf zurück, wenn du nicht in einem Arbeitsverzeichnis arbeitest (einen Plan, ein Design, ein Schriftstück schärfst – alles ohne Repository darunter). Wenn du in einem Arbeitsverzeichnis bist, verwende stattdessen /grill-with-docs: Es führt dasselbe Interview durch und hinterlässt eine Papierspur, also ist es streng genommen das bessere.
• /grilling ist die Interview-Primitive selbst: Runden, die Frontier, Fakten sind die Aufgabe des Agenten und Entscheidungen sind deine. /grill-me und /grill-with-docs sind die zwei benannten Wege hinein, und /triage, /wayfinder und /improve-codebase-architecture führen es intern aus. Greife nur dann direkt darauf zu, wenn du das Interview ohne Hülle darum haben möchtest.
• /prototype ist ein kleines, wegwerfbares Programm, das eine einzige Designfrage beantwortet: fühlt sich dieses Zustandsmodell richtig an, oder wie sollte diese UI aussehen. Wegwerfbar ist eine Einschränkung, wie der Code geschrieben wird, kein Versprechen, ihn zu zerstören: Die Antwort fließt in den echten Code ein, und der Prototyp selbst wird als Primärquelle auf einem prototype/<name>-Zweig von main aus aufbewahrt, auf den vom Implementierungs-Issue verwiesen wird. Es ist der Umweg in Schritt 2 des Hauptflusses, aber greife jederzeit darauf zurück, wenn eine Designfrage auf dem Papier schwer zu klären ist.
• /research: delegiere Leseaufgaben an einen Hintergrundagenten: Er untersucht eine Frage anhand von Primärquellen und hinterlässt dann eine zitierte Markdown-Datei im Repository. Arbeite weiter, während er liest. Die Datei, die er produziert, ist etwas, das in den Hauptfluss bei /grill-with-docs aufgenommen wird, da Recherche das Denken füttert, nicht ersetzt.
• /to-questionnaire kommt zum Einsatz, wenn das, was dich blockiert, nicht in deinem Kopf oder der Codebasis liegt, sondern in jemand anderem, und es schreibt ihnen einen Fragebogen zum Ausfüllen. Es ist das Gegenteil von /grill-me: Anstatt dich über das Thema zu interviewen, interviewt es dich über den Versand (an wen es geht, was du zurückbrauchst) und richtet die Fragen auf die Lücke. Was zurückkommt, ist Material für /grill-with-docs oder /to-spec.
• /wizard ist für die Schritte, die nur ein Mensch unternehmen kann: Bereitstellung von Infrastruktur, Einrichten von Anmeldedaten oder CI-Secrets, Klicken durch ein unbekanntes Drittanbieter-Dashboard, Ausführen einer einmaligen Migration oder Umstellung. Es generiert ein interaktives Bash-Skript, das jede URL öffnet, jeden Wert erfasst und in .env und GitHub Secrets schreibt, sodass die Prozedur nicht mehr jedes Mal neu einem Agenten erklärt werden muss. Modellgesteuert, also greift der Agent darauf zu, sobald er auf eine Wand trifft, die nur du passieren kannst. Wenn der Agent es selbst tun könnte, sollte er es; dies ist für Fälle, in denen ein Mensch wirklich im Kreislauf ist.
• /wait-what ist die Korrektur für eine Nachricht, die nicht angekommen ist. Verwende es mitten im Gespräch, innerhalb jedes anderen Skills, und der Agent wiederholt das Gesagte mit dem fehlenden Kontext, in einfachem Deutsch, unter Verwendung des Vokabulars aus GLOSSARY.md. Es wirkt im Nachhinein; /grill-with-docs ist die vorbeugende Heilung, denn eine früh vereinbarte gemeinsame Sprache verhindert, dass der Fachjargon überhaupt auftaucht.
• /teach: Lerne ein Konzept über mehrere Sessions hinweg, wobei das aktuelle Verzeichnis als zustandsbehafteter Arbeitsbereich dient.
• /writing-for-agents ist die Referenz zum Schreiben von Dokumenten, die Agenten konsumieren: Skills, AGENTS.md, referenzierte Dokumente.

Vorbedingung

/setup-matt-pocock-skills: Führe es vor deinem ersten Engineering-Flow aus, um den Issue-Tracker, Triage-Labels und das Dokumentenlayout zu konfigurieren, das die anderen Skills voraussetzen. Benutzerdefinierte Issue-Tracker funktionieren ebenfalls.