ramon-sg/agent-skills

Auf den Punkt erklären

Das Ziel: Wer liest, versteht das Wichtigste in weniger als einer Minute. Am Bildschirm wird wenig gelesen (knapp 20 % des Textes) und vor allem der Anfang jeder Zeile. Deshalb kommt das Wichtige zuerst und jede Überschrift sagt etwas aus.

Stilregeln

Sie gelten in allen Modi:

1. Der erste Satz enthält die Entscheidung oder die Antwort. Der Kontext kommt danach.
2. Sätze mit 25 Wörtern oder weniger, idealerweise 15 bis 20, mit je einer Idee.
3. Subjekt, Prädikat, Objekt im Aktiv, mit wer was tut („Der Server wiederholt“, nicht „Es wird wiederholt“).
4. Alltagssprache. Client, Sitzung, Meldung, Server, Datenbank sind in Ordnung. Funktions-, Datei- oder Variablennamen gehören nicht hierher; sie leben im Detail.
5. Ein konkretes Beispiel ist mehr wert als eine allgemeine Beschreibung: ein Akteur, was er tut und was er sieht.
6. Aussagekräftige Überschriften: „Heute: Meldungen gehen verloren“, nicht „Wie es heute ist“. Die ersten beiden Wörter sagen etwas für diesen Text Eigenes aus.
7. Kein Füllmaterial oder Eigenlob: weg mit „im Grunde“, „einfach“, „vielleicht“, „grundsätzlich“, „robust“, „leistungsstark“.
8. Aufzählungen nur für gleichrangige Dinge, ohne Verschachtelung, und Absätze maximal drei Sätze lang.
9. Auch Schlechtes wird genannt: das eingegangene Risiko, im Vergleich zur Alternative, und was ausgeklammert bleibt.

Dokument-Modus: Plan

Die genaue Form und die Grenzen stehen in der Skill planning (Schritt 2, „Auf den Punkt“) und werden von deren check-plan.sh geprüft: „Entscheidung“, „Heute“, „Danach“, „Risiko“ und optional „Neu“, „Draußen“. Jeder Fakt in „Heute“ verlinkt auf seinen Beleg und jedes Ergebnis in „Danach“ auf seine Phase.

„Neu“ kommt nur, nachdem das Muster im Repo gesucht wurde (rg): ein falsches „das ist neu“ nimmt dem gesamten Plan die Glaubwürdigkeit.

Dokument-Modus: Issue

Der Issue-Kopf besteht aus drei Zeilen, vor allem anderen. Die vollständige Form steht in der Skill github-issues.

**Was fehlt:** <Akteur und Wirkung, in einem Satz>.      (oder **Was wird gewünscht:**)
**Warum wichtig:** <ein Satz mit einer Zahl oder einem Beispiel>.
**Erledigt, wenn:** <das wichtigste beobachtbare Ergebnis>.

Listen-Modus (Standard im Gespräch)

Jemand bittet um eine Erklärung, ohne dass ein Dokument dahintersteckt:

• Ein Punkt pro Idee, 3 bis 7 Punkte; bei mehr werden sie gruppiert.
• Alle beginnen mit dem gleichen Worttyp (alle mit Verb oder alle mit Nomen). Bedingungen kommen ans Ende („… wenn die Bank ablehnt“).
• Keine Überschriften, keine Fettungen und kein erzwungener Vorher/Nachher-Vergleich: Es wird genau das beantwortet, was gefragt wurde.
• Wenn die Antwort nur eine Idee enthält, kommt sie direkt, ohne Aufzählungszeichen.

Beispiel: „Wie funktionieren Zahlungswiederholungen?“

- Bucht den Betrag, sobald der Kunde auf „Bezahlen“ tippt.
- Zeigt „Zahlung wiederholen“, wenn die Bank wegen fehlender Deckung ablehnt.
- Wiederholt nur bis zu drei Mal mit zunehmender Wartezeit, wenn das Netz ausfällt.
- Zeichnet jeden fehlgeschlagenen Versuch in der Bestellung auf, mit Grund.

Prosa-Modus

Das Gleiche, in kurzen Absätzen. Nur, wenn darum gebeten wird („erzähl es mir zusammenhängend“) oder wenn die Punkte ohne den vorherigen nicht verständlich sind.

Beispiel: Vorher und Nachher

Vorher (schwer verständlich):

1. Wie es heute ist

• Der RetryLink wendet maxRetries=3 pro Operation an, was – zusammen mit dem Fehlen eines globalen Koordinationsmechanismus – bei Störungen zu einer erheblichen Lastverstärkung führen kann.

Nachher:

Entscheidung: Die App wird nicht mehr wiederholen, wenn die API ausgefallen ist.

Heute: ein Ausfall vervielfacht die Last

Jede Abfrage wiederholt drei Mal eigenständig. Fällt die API aus, erhält sie genau dann die dreifache Anzahl Anfragen, wenn sie versucht, wieder hochzukommen.