AlemTuzlak/skills

docs

Schreibe Dokumentation, die ein echter Mensch lesen möchte. Kurz, klar, aufgebaut um jemanden, der etwas Reales tun möchte.

"Feature X dokumentieren" ist nicht die Aufgabe. "Jemandem helfen, Y mit X zu tun" ist die Aufgabe.

Arbeite in zwei Phasen. Zuerst plane die Geschichte: Wer liest das, was sie wollen und wie viele Seiten es braucht. Dann schreibe.

Der Plan ist nicht privat. Der Benutzer muss die Leser sehen und muss den Ton wählen, bevor eine Seite geschrieben wird.

docs finden
  → Nachbarseiten lesen
  → Phase 1: Leser + Seiten
  → PERSONA-GAT (die Leserliste in den Chat schreiben, dann anhalten)
  → TON-GAT (den Ton in den Chat schreiben, dann anhalten)   [beim Schreiben von Seiten]
  → simple-english + i-have-adhd laden   [beim Schreiben von Seiten]
  → Phase 2: schreiben

Ein Doc-Wirkungsliste in einem Feature-Plan durchläuft trotzdem das Persona-Gat. Sie durchläuft nicht das Ton-Gat und lädt die Schreibfähigkeiten erst, wenn tatsächlich Seiten geschrieben werden.

Wann ausführen

Dokumentation wird mit dem Code ausgeliefert. Führe diese Fähigkeit zu drei Zeitpunkten aus, nicht nur auf Anfrage.

• Jemand bittet um Dokumentation. Schreibe sie.
• Planung eines Features oder einer Änderung in einem Repository. Bevor der Plan fertig ist, liste auf, welche Dokumentation neu ist und welche aktualisiert werden muss. Diese Doc-Wirkungsliste ist Teil des Plans, genau wie die Code-Änderungen. Nenne den Leser für jede Seite.
• Abschluss einer Implementierung. Schreibe oder aktualisiere diese Dokumentation, bevor du die Arbeit als erledigt betrachtest. Eine Änderung des Verhaltens, die keine Änderung der Dokumentation mit sich bringt, ist nicht abgeschlossen.

Erforderliche Fähigkeiten für die endgültigen Seiten

simple-english und i-have-adhd sind Voraussetzungen. Sie gelten für die Dokumentationsseiten, nicht für diesen Planungschat.

Lade beide unmittelbar vor dem Schreiben des Seiteninhalts. Verwende das Skill-Tool, falls diese Umgebung eines hat. Falls nicht, lies die SKILL.md jeder Fähigkeit aus dem lokalen Skill-Verzeichnis. Schreibe keine Seiten aus dem Gedächtnis dieser Fähigkeiten.

Fehlt eine der beiden Fähigkeiten, halte inne und informiere den Benutzer. Schreibe die Seiten nicht ohne sie.

Wie sie zusammenwirken:

• Diese Fähigkeit bestimmt, für wen die Seite ist, die Seitenaufteilung, Problem-dann-Lösung, Zeigen-statt-Erzählen, kein Verlauf-Lecks, verbotene Schriftzeichen und die Nachbarstruktur.
• simple-english bestimmt die Sätze. Verwende den pragmatischen Modus. Führe die Selbstprüfung durch, bevor du eine Seite als fertig erklärst.
• i-have-adhd bestimmt die Form der Seite: nächste Aktion zuerst, nummerierte Schritte, Listen auf maximal 5 Einträge begrenzt (teile auf in „muss“ vs. „später“ oder teile die Seite), keine Einleitung, ein sichtbarer Erfolg am Ende.

Wenn i-have-adhd von dieser Fähigkeit geladen wird, wende es nur auf die Seiten an. Schalte den Rest der Sitzung nicht in den ADHS-Modus. Der Persistenzabschnitt von i-have-adhd gilt hier nicht.

Finde zuerst die Dokumentation

Bevor du etwas schreibst, finde heraus, wo die Dokumentation lebt.

1. Suche nach einem docs-Ordner. Prüfe zuerst docs/, dann documentation/, content/docs/, site/, website/docs/.
2. Nichts gefunden? Frage den Benutzer, wo die Dokumentation abgelegt werden soll. Rate nicht und erstelle keinen Ordner aufgrund einer Vermutung.
3. Öffne 2 oder 3 bestehende Seiten in der Nähe des Ortes, an den der neue Inhalt gehört. Lies sie, um Inhalt, Struktur, Frontmatter-Felder und Komponenten zu verstehen. Notiere den offensichtlichen Ton als Kandidaten für das Ton-Gat. Übernehme ihn noch nicht.
4. Notiere, welche Komponenten die Seite bereits verwendet (Schritte, Tabs, Callouts, Karten, Akkordeons, Code-Gruppen usw.). Unterschiedliche Seiten haben unterschiedliche.
5. Verwende diese Komponenten wieder, um die Geschichte zu erzählen. Wenn die Seite eine Schritt-Komponente hat, verwende sie für Anleitungen. Wenn sie Tabs hat, verwende sie für Framework-Varianten. Wenn die Seite keine hat, verwende einfaches Markdown. Erfinde niemals eine Komponente, die die Seite nicht hat.

Wenn es keine Seite gibt, die derjenigen ähnelt, die du schreiben wirst, lies die nächstgelegene, die du finden kannst, und passe dich ihr an.

Was „Nachbarn anpassen“ abdeckt, und was nicht

Nachbarn anzupassen bezieht sich auf Inhalt, Struktur, Frontmatter und Komponenten: ob Überschriften im Satzfall sind, wie viel Einleitung ein Abschnitt bekommt, welche Komponenten die Anleitung tragen, wie Codebeispiele eingeführt werden, welche Frontmatter-Felder es gibt.

Es ist kein Ersatz für das Ton-Gat. Nachbarn können einen Standard vorschlagen. Sie können nicht für den Benutzer antworten.

Es ist keine Erlaubnis, schlechte Angewohnheiten der Nachbarn zu kopieren. Alles in Verboten und jede Regel dieser Fähigkeit gilt weiterhin für den Inhalt, den du schreibst, unabhängig davon, was die umgebenden Seiten tun. Eine bestehende Seite voller Gedankenstriche berechtigt nicht zu einem weiteren.

Argumentiere also niemals: „Die anderen Seiten machen es so, also werde ich es auch tun“ in Bezug auf eine Regel, die diese Fähigkeit angibt. Wenn bestehende Seiten gegen eine Regel verstoßen und du denkst, dass der gesamte Satz in Einklang gebracht werden sollte, ist das eine separate Bereinigung, die mit dem Benutzer zu besprechen ist, und nicht etwas, das durch stilles Anpassen an den Verstoß gelöst werden kann.

Phase 1: Plane die Geschichte

Führe dies durch, bevor du ein Wort des Inhalts schreibst.

1. Liste auf, wer dies liest und was jeder möchte. Eine Person, die auf einer React SPA entwickelt, eine Person auf einer servergerenderten App, jemand, der nur eine schnelle Demo möchte, jemand, der die Interna erweitert. Höre nicht beim ersten Leser auf.
2. Schreibe eine Benutzergeschichte pro Leser: „Als X möchte ich Y, damit ich Z kann.“
3. Verwandle Geschichten in Seiten. Eine Reise ist eine Seite. Unterschiedliche Reisen sind unterschiedliche Seiten. Ein Feature mit drei echten Reisen besteht aus drei Seiten plus vielleicht einer kurzen Übersicht, nicht einer einzigen riesigen Seite.
4. Überprüfe, ob jeder Leser einen Pfad hat. Ein Leser ohne Seite ist ein Loch im Plan. Füge eine Seite oder einen Weg für sie hinzu.

Die Seitenaufteilung ergibt sich aus diesem Schritt. Überspringe ihn nicht.

Gate: Zeige die Personas

Frage-Tools (AskQuestion, ask_user_question und ähnliche Formen) zeigen ihre Nutzlast nicht im Chat an, den der Benutzer liest. Ein Zug, der nur eines dieser Tools aufruft, besteht dieses Gate nicht. Der Benutzer wird gebeten, eine Liste zu bestätigen, die er nicht sehen kann.

Nach Schritt 4 schreibe eine normale Chat-Nachricht. Der Nachrichtentext ist erforderlich, auch wenn gleichzeitig ein Frage-Tool aufgerufen wird. Die Nachricht enthält:

1. Jeden Leser als eigenen kurzen Block, den der Benutzer scannen kann:
   • Name des Lesers.
   • Eine Benutzergeschichte: „Als X möchte ich Y, damit ich Z kann.“
   • Die Seite, die du für sie schreiben wirst.
2. Eine Frage, geschrieben in derselben Nachricht: bestätigen, einen Leser streichen oder einen hinzufügen.

Ein Frage-Tool ist optional. Rufe es erst auf, nachdem diese Liste bereits in der Chat-Nachricht steht. Das Tool fragt nur die kurze Auswahl ab (bestätigen, streichen oder hinzufügen). Setze die Lesernamen, die Geschichten oder die Seiten nicht in das Tool. Wenn das Tool die einzige Ausgabe des Zuges wäre, rufe es nicht auf. Schreibe stattdessen die Nachricht.

Wähle dann einen Weg:

Standard: anhalten. Diese Nachricht ist der gesamte Zug. Beende den Zug. Schreibe keine Dateien. Beginne nicht mit Phase 2. Sage nicht, dass du fortfahren wirst, es sei denn, der Benutzer widerspricht.

Wartezeit überspringen: im selben Zug fortfahren. Verwende diesen Weg nur, wenn eine der folgenden Bedingungen zutrifft:

• Diese Unterhaltung hat bereits die Bestätigung des Benutzers für diese Persona-Liste.
• Der Benutzer sagte „verwende vernünftige Standardeinstellungen“, „schreibe es einfach“ oder „stelle keine Fragen“. Zeige die Liste dennoch in diesem Zug, dann fahre fort.
• Die Änderung ist eine winzige Kopie-Bearbeitung: Tippfehler, defekter Link, Code-Fence-Sprache oder eine sachliche Korrektur. Keine neue Seite, kein neuer Abschnitt, keine Neufassung einer Reise.

Auf diesem Weg beende den Zug nicht. Nachdem du die Liste gezeigt hast (oder nach einer winzigen Kopie-Bearbeitung, ohne Liste), fahre mit dem nächsten Schritt fort.

Dies sind keine Überspringungen:

• „Die Leser sind offensichtlich.“
• „Der Benutzer bat um Dokumentation, also möchte er keine Frage.“
• „Ich habe sie bereits im Plan benannt.“
• „Es gibt nur einen Leser.“
• „Dies ist Teil der Implementierung eines Features, mach weiter.“
• „Das Frage-Tool zeigt ihnen die Liste.“ Tut es nicht. Die Liste kommt in den Chat.

Dokumentation zu schreiben ist der Grund, warum dieses Gate existiert. Es ist kein Grund, es zu überspringen.

Weniger ist mehr: teilen, nicht stopfen

Zwinge nicht Tausende von Wörtern auf eine Seite. Lange Seiten verstecken die Antwort.

Wenn ein Thema mehrere Blickwinkel hat, gib jedem seine eigene kurze Seite und verlinke sie. Ein Leser landet auf der Übersicht und klickt dann in das genaue, was er braucht.

Beispiel. Ein Feature für Tool-Unterbrechungen:

Schlecht: eine Seite
  interrupts.md   (Übersicht + einfacher Fall + viele Unterbrechungen + benutzerdefiniert, alles hineingestopft)

Gut: eine kleine Gruppe verlinkter Seiten
  interrupts/index.md            Was es ist, wann man es verwendet, Verweise auf andere
  interrupts/basic.md            Eine Unterbrechung, von Anfang bis Ende
  interrupts/multiple.md         Mehrere Unterbrechungen in einem Ablauf
  interrupts/custom.md           Baue deine eigene

Jede Seite ist kurz und macht eine Sache. Die Übersicht verbindet sie zu einer Geschichte.

Gate: Frage nach dem Ton

Dieses Gate sitzt zwischen Phase 1 und Phase 2. Führe es aus, bevor du eine Seite schreibst. Verschachtele es nicht innerhalb von Phase 2.

Nachbarn können einen Standard vorschlagen. Sie können nicht für den Benutzer antworten.

Schreibe eine normale Chat-Nachricht. Der Nachrichtentext ist erforderlich, auch wenn gleichzeitig ein Frage-Tool aufgerufen wird. Die Nachricht enthält:

1. Den Ton, den du aus benachbarten Seiten abgeleitet hast, in einem Satz (wie formell, wie viel Einleitung, zweite Person oder nicht).
2. Eine Frage, geschrieben in derselben Nachricht: diesen Ton verwenden, informeller, formeller oder der Benutzer nennt einen anderen.

Ein Frage-Tool ist optional und kommt, nachdem diese Zeile im Chat ist. Das Tool fragt nur die kurze Auswahl ab. Setze den abgeleiteten Ton nicht nur innerhalb des Tools. Ein Zug, der nur das Tool aufruft, besteht dieses Gate nicht.

Wähle dann einen Weg:

Standard: anhalten. Diese Nachricht ist der gesamte Zug. Beende den Zug. Schreibe keine Seiteninhalte.

Wartezeit überspringen: im selben Zug fortfahren. Verwende diesen Weg nur, wenn eine der folgenden Bedingungen zutrifft:

• Diese Unterhaltung hat bereits die Tonauswahl des Benutzers, einschließlich eines expliziten „passe die bestehenden Seiten an“.
• Der Benutzer sagte „verwende vernünftige Standardeinstellungen“, „schreibe es einfach“ oder „stelle keine Fragen“. Gib dennoch den abgeleiteten Ton in einem Satz an, dann fahre fort.
• Winzige Kopie-Bearbeitung, gleiche Ausnahme wie beim Persona-Gate.

Auf diesem Weg beende den Zug nicht. Nachdem du den Ton angegeben hast (oder nach einer winzigen Kopie-Bearbeitung, ohne Frage), fahre mit Phase 2 fort.

Dies sind keine Überspringungen:

• „Ich kann es aus den Nachbarn erkennen.“
• „Die Seite hat bereits eine Stimme.“
• „Ton spielt für eine Referenzseite keine Rolle.“
• „Ich werde mich den Nachbarn anpassen und es später erwähnen.“

Phase 2: Schreibe wie ein Mensch

Schreibe erst dann Seiteninhalte, wenn das Persona-Gate bestanden wurde, das Ton-Gate bestanden wurde und simple-english sowie i-have-adhd geladen sind.

Das Ton-Gate ist die Überschrift über dieser. Führe zuerst dieses Gate aus. Lade dann die beiden Fähigkeiten. Schreibe dann.

Lesbarkeit ist das Ziel, vor allem anderen.

• Halte es verdaulich. Keine Textwüsten, keine riesigen Absätze. Zerlege Ideen in kleine Stücke. Gib die kleinste Menge an Informationen, die den Job erledigt.
• Sätze folgen simple-english (pragmatischer Modus). Baue keinen schwächeren Ersatz ein.
• Halte Markdown leicht. Aufzählungen sind in Ordnung. Fette Überschriften auf jeder Zeile sind es nicht. Lass die Wörter die Seite tragen.
• Bevorzuge einfaches ASCII und normale Tastaturzeichen gegenüber ausgefallenen Glyphen. Schreibe so, wie eine Person tippt.
• Zweite Person, Aktion zuerst. Beginne damit, was der Leser jetzt hat und was er am Ende haben wird. Keine „In diesem Leitfaden werden wir erkunden…“-Einführungen. Fange einfach an.
• Gestalte die Seite mit i-have-adhd: Die erste Zeile ist etwas, das der Leser tun kann, mehrstufige Arbeiten sind nummeriert, eine Liste länger als 5 wird geteilt, die Seite endet mit einem sichtbaren Erfolg.

Beginne mit dem Problem, dann löse es

Jede Seite beginnt mit dem Problem, das der Leser hat, in seinen eigenen Worten, vor jeder API. Nenne die Situation, in der er feststeckt. Dann sage in ein oder zwei Sätzen, wie das Feature es löst. Erst danach gehst du zu den technischen Teilen und dem Code über.

Ein Leser, der zuerst das Problem sieht, weiß in Sekunden, ob er auf der richtigen Seite ist. Ein Leser, der zuerst auf eine API-Signatur stößt, muss rückwärts erschließen, wofür sie überhaupt ist.

Die erste Zeile des „Wie“ ist die nächste Aktion (aus i-have-adhd). Das Problem kommt dennoch zuerst, damit sie wissen, dass sie auf der richtigen Seite sind.

Schlecht:
  Rufe useInterrupts() auf und übergib einen Resolver. Der Resolver läuft einmal pro
  ausstehendem Element innerhalb einer Transaktion...

Gut:
  Manche Tool-Aufrufe sollten ohne menschliche Bestätigung nicht ausgeführt werden: Geld bewegen,
  Daten löschen. Eine Unterbrechung pausiert den Durchlauf für diese Entscheidung und setzt dann
  dort fort, wo er aufgehört hat. So schützt du ein Tool hinter einer Genehmigung:

  [code]

Die Reihenfolge für eine Anleitung ist Problem, einzeilige Lösung, dann das „Wie“ (Schritte, Schnipsel, API). Halte das Problem auf ein paar Sätze, keinen Hintergrundaufsatz. Der Code zeigt, wie es gelöst wird, also beschreibe die Lösung nicht zuerst in Prosa.

Zeigen, nicht erzählen

Erkläre nicht in vier Absätzen, was ein Satz und ein Codeblock zeigen können. Leser erfassen einen Diff oder einen Schnipsel schneller als Prosa.

Schlecht:
  Drei Absätze, die beschreiben, wie das Konfigurationsobjekt ein
  Middleware-Array akzeptiert, was jeder Slot tut und wie die Reihenfolge funktioniert.

Gut:
  Füge deine Middleware zum `middleware`-Array hinzu. Die Reihenfolge ist von oben nach unten:

  const app = createApp({
    middleware: [auth, logging],
  })

Ein gutes ausführbares Beispiel ist besser als eine Seite voller Beschreibung. Jedes Codebeispiel muss lauffähig sein, wenn es kopiert wird, und keine Fantasie erfordern, um Lücken zu füllen.

Liste alles auf, was eine Liste ist

In dem Moment, in dem ein Satz mehr als ein Element, eine Option, einen Store, ein Flag oder einen Schritt abdeckt, wird er zu einer Liste. Verkette sie nicht mit Kommas und Semikolons zu einem Absatz. Ein Leser, der eine Aufzählung überfliegt, findet sein Element in einer Sekunde. In einem Absatz muss er das Ganze lesen, um zu erfahren, dass es nicht auf ihn zutrifft.

Das Erkennungsmerkmal ist ein Satz, der zwei oder mehr Dinge nennt und etwas über jedes sagt. Schneide ihn in einen Aufzählungspunkt pro Sache, ein oder zwei Sätze pro Punkt.

Schlecht:
  Jeder Store ist unabhängig. Gib nur die an, die du brauchst. Für Chat:
  `messages` für das Transkript, `runs` für den Run-Lebenszyklus, `interrupts` für
  dauerhafte Genehmigungen (benötigt `runs`), `metadata` für namensraumbezogenen
  Schlüssel/Wert-Status. Für Generierung: `generationRuns` für den Run-Lebenszyklus, plus
  `artifacts` und `blobs`, um generierte Bytes zu speichern.

Gut:
  Jeder Store ist unabhängig, also gib nur die an, die du brauchst.

  Für Chat:

  - `messages`: das Transkript.
  - `runs`: Run-Lebenszyklus.
  - `interrupts`: dauerhafte Genehmigungen. Benötigt `runs`.
  - `metadata`: namensraumbezogener Schlüssel/Wert-Status.

  Für Generierung:

  - `generationRuns`: Run-Lebenszyklus.
  - `artifacts`: generierte Bytes.
  - `blobs`: generierte Bytes (große Dateien).

Vermeide Verlaufslecks

Ein Verlaufsleck liegt vor, wenn der Leser sehen kann, wie die Seite oder das Produkt früher funktioniert hat. Das sind Informationen, die nur für jemanden nützlich sind, der das alte Verhalten kannte und migrieren muss. – oder niemandem nützen, aber die Seite aufblähen.

Schlecht:
  Früher hieß die Methode `createClient` und akzeptierte einen anderen Parametersatz.
  In v3 haben wir sie in `createAgent` umbenannt. Wenn du von v2 migrierst, musst du
  deine Aufrufe aktualisieren.

  Der alte Ansatz verwendete optionale Rückrufe. Jetzt verwenden wir Promises.

gut:
  Erstelle einen Agenten mit `createAgent()`:

  const agent = createAgent({...})

Eine Migrationsanleitung kann es wert sein, als eigene Seite geschrieben zu werden, wenn der Vorteil die Seitenkosten übersteigt. Aber eine Seite über das aktuelle Verhalten sollte nicht damit beginnen, wie es früher funktioniert hat. Das ist in einer Migration zu Hause. Jede andere Seite verbirgt die Antwort.

Wenn eine Migration notwendig ist:

• Füge einen kurzen Hinweis auf der Seite zur aktuellen Verwendung hinzu: „Wenn du von v2 migrierst, siehe Migrationsanleitung.“
• Schreibe die Migrationsseite als eine Aufgabenliste von alt zu neu: „Wenn du X tatest, tue jetzt stattdessen Y.“ Keine Einleitung, kein Verlauf. Ein Leser, der migriert, überfliegt nur die Änderungen und möchte weitermachen.

Hoch- und Runterformate sind das Gleiche

Wenn der Benutzer eine Persona-Geschichte oder eine Seite bestätigt und später eine ähnliche, aber nicht identische anfordert, wiederhole nicht bereits getroffene Entscheidungen. Führe das Gate für die neue Arbeit erneut aus.

Schlecht:
  Benutzer: "Schreibe eine Kurzanleitung für das Feature Z."
  Du: "Verwende den gleichen Ton und die gleichen Leser wie für die vorherige Anleitung?"

gut:
  Benutzer: "Schreibe eine Kurzanleitung für das Feature Z."
  Du: [absolviere das Persona-Gat für diese Arbeit und dann das Ton-Gat.]

Vermeide Glyphen

Ein Glyph ist jedes Zeichen, das ein normaler Mensch nicht auf seiner Tastatur hat: Gedankenstriche (–), Anführungszeichen (’ „ “), geschützte Leerzeichen, Mathe-Symbole (≠, ≤, ≥), Pfeile (→, ←) und ähnliches.

Kein Glyph ist so wichtig wie die Tatsache, dass es den Leser ablenkt oder die Kopie und Einfügen kaputt macht.

Schlecht:
  Parameter → werden als „Schlüssel“ bezeichnet – ein Durcheinander von Symbolen.

gut:
  Parameter werden als „Schlüssel“ bezeichnet – ein einfacher Bindestrich und normale Anführungszeichen.

Erlaubte Ausnahmen:

• Codeblöcke und Inline-Code. Code enthält, was die Sprache erfordert.
• Bestehende Markdown-Syntax: **fett**, *kursiv*, `code`, [link](url), > Zitat, | Tabelle |.
• Ein Emoji oder Chevron (>) in einem Commit-Titel, den du zitierst.
• Ein Inline-Bild (keine Emojis). Verwende die Markdown-Syntax für Bilder, wenn ein Bild wirklich eine Erklärung ersetzt.

Wann immer du versucht bist, einen Pfeil (→) zu schreiben, schreibe in Worten: „dann“, „nächstes“, „führe zu“, „gibt“. Verwende eine Aufzählung oder nummerierte Schritte, wenn die Aktion zu einer Richtung führt.

Verboten

Diese Liste erweitert die Standard-Markdown-Regeln. Jeder verstoß macht die Seite ungültig:

1. Kein Produktverlauf. Seite X beschreibt X, nicht wie X früher aussah.
2. Keine Geschichte aus zweiter Hand. Zitiere nicht, wie das Tool funktioniert. Zeige es im Code.
3. Keine erste Person Plural im Leitfaden. Kein „wir“, „unser“, „lass uns“. Sag „du“, „dein“.
4. Keine Anmerkungen wie „Beachte“. Der Leser sollte nicht angehalten werden, um etwas zur Kenntnis zu nehmen, das in den Text selbst gehört.
5. Keine Seiten, die mit Setup-Abhängigkeiten beginnen. Den Benutzer zu zwingen, ein SDK zu installieren, bevor er das Problem sieht, treibt ihn von der Seite.
6. Keine nicht kopierbaren Codeblöcke. Jeder Codeblock muss lauffähig sein, wenn er aus der Seite eingefügt wird. Keine Platzhalter, Ellipsen oder implizite Schritte.
7. Keine vagen Variablennamen in Beispielen. Verwende authMiddleware, nicht thing.
8. Keine globalen Annahmen. „Deployment-Umgebungen“ sind kein Feature der Cloud. Unterschiedliche Produkte haben unterschiedliche Begriffe. Verwende die Begriffe, die der Leser auf dieser Seite sehen wird.

Was tun, wenn der Benutzer gegen eine Regel bittet

Benutzer können um Dinge bitten, die gegen diese Anleitung verstoßen. Ein Entwickler, der einen Chat-Agenten verwendet, kann sagen: „Schreibe eine Seite, die mit einer Liste von Abhängigkeiten beginnt.“ oder „Füge einen Hinweis zur Historie hinzu, es ist wichtig für mein Team.“

In dem Fall:

1. Erkläre kurz, warum die Regel existiert: was passiert, wenn der Leser diesem Muster ausgesetzt ist.
2. Frage, ob sie trotzdem fortfahren sollen.
3. Wenn sie ja sagen, tue es. Es ist ihr Repository.

Integration mit anderen Skills

Diese Fähigkeit ist für die Planung und Struktur verantwortlich. Sie delegiert Satz- und Seitenform an spezialisierte Skills. Die empfohlenen sind:

• simple-english: Kurze Sätze, pragmatischer Modus, Vermeidung von Nominalisierungen. Siehe skills/simple-english/SKILL.md.
• i-have-adhd: Nächste Aktion zuerst, nummerierte Anleitungen, maximale Listengröße von 5, sichtbarer Erfolg am Ende. Siehe skills/i-have-adhd/SKILL.md.

Beide Fähigkeiten müssen in einem lokalen Verzeichnis verfügbar sein (skills/simple-english/SKILL.md und skills/i-have-adhd/SKILL.md), oder diese Fähigkeit gibt einen Fehler aus, bevor Seiten geschrieben werden.

Integration in Drittanbieter-Workflows

Diese Fähigkeit kann in CI/CD-Pipelines oder Planungstools integriert werden. Die Doc-Wirkungsanalyse wird ausgelöst, wenn ein Feature-Plan erstellt wird. Das Persona-Gat muss in einem Chat-Kanal protokolliert werden. Das Ton-Gat kann in einer PR-Vorlage oder einem Issue-Kommentar ausgeführt werden. Die Schreibphase muss immer die beiden Hilfsskills laden.

Fehlerbehebung

• Fehlende simple-english Fähigkeit: Diese Fähigkeit ist erforderlich. Ohne sie können keine Seiten geschrieben werden. Informiere den Benutzer und fahre nicht fort.
• Fehlende i-have-adhd Fähigkeit: Diese Fähigkeit ist erforderlich. Ohne sie können keine Seiten geschrieben werden. Informiere den Benutzer und fahre nicht fort.
• Ton-Gat wird umgangen: Ein Benutzer könnte versuchen, das Ton-Gat zu überspringen, indem er sagt „verwende nur den Standardton“. Das ist nur gültig, wenn der Benutzer explizit „verwende vernünftige Standardeinstellungen“ oder einen gleichwertigen Befehl gegeben hat. Wenn der Benutzer zuvor noch nicht mit dieser Fähigkeit interagiert hat, ist das keine gültige Überspringung. Zeige den abgeleiteten Ton an und frage.
• Persona-Gat wird umgangen, obwohl die Leser offensichtlich sind: Das Persona-Gat erfordert immer eine explizite Liste im Chat. Selbst wenn es nur einen Leser gibt, muss er genannt werden.

Anhänge

Referenz: Zeichen, die nicht als Glyphen gelten

Zeichen	Status
Bindestrich (-)	Normal
Apostroph (')	Normal
Normale Anführungszeichen (" ")	Normal
Schrägstrich (/)	Normal
Backslash ()	Normal
Klammern ( ) [ ] { }	Normal
Pfeile (→, ←, ↑, ↓)	Glyph – vermeiden
Gedankenstrich (–)	Glyph – vermeiden
Geschützte Leerzeichen ( )	Glyph – vermeiden
Geschweifte Anführungszeichen ( „ “ )	Glyph – vermeiden
Mathe-Symbole (≠, ≤, ≥)	Glyph – vermeiden

Referenz: Tools, die das Persona-Gat nicht bestehen

• AskQuestion
• ask_user_question
• Jedes Tool, dessen Ausgabe im Chat des Benutzers nicht sichtbar ist

Ein Tool, das eine Frage stellt, dessen Payload aber nicht im Chat erscheint, kann das Persona-Gat nicht bestehen, da der Benutzer die Liste der Leser nicht sehen kann.