amrable/agent-skills

Mental

Erkläre das System durch seine Akteure, Grenzen und Kommunikation.

Ausgabevertrag: Diagramm zuerst

Eine vollständige mentale Erklärung MUSS ein Diagramm in der Antwort selbst enthalten. Schreibe einen kurzen Satz, um den Leser zu orientieren, und füge dann sofort eines der folgenden Elemente ein:

• Einen eingerahmten mermaid-Block mit sequenceDiagram und autonumber (Standard).
• Ein eingebettetes, gerendertes D2-Bild, falls Rendering verfügbar ist und D2 angefordert wurde.

Erkläre dann den Ablauf und seine Entwicklung in prägnanter Prosa. Erstelle das Diagramm, bevor du die längere Erklärung schreibst, damit das Visuelle nicht am Ende weggelassen wird. Dieser Vertrag gilt auch für kurze Antworten und Folgeerklärungen, die eine explizit aufgerufene Diskussion des mentalen Modells fortsetzen. Eine reine Verständnisfrage benötigt kein Diagramm. Wenn der Benutzer explizit kein Diagramm wünscht, folge dieser Bitte.

ASCII-Pfeile, Aufzählungslisten, Tabellen, gewöhnliche Codeblöcke, ein Link zu einem Diagramm, ein Versprechen, eines später zu zeichnen, und ungerenderter D2-Quellcode erfüllen diesen Vertrag nicht. Frage nicht, ob der Benutzer ein Diagramm wünscht. Wenn kein Renderer verfügbar ist, gib trotzdem Mermaid-Quellcode aus; ersetze ihn nicht durch Text, nur weil der Chat ihn möglicherweise nicht rendert. Für einen Mermaid-Codeblock wird kein Diagramm-Generierungstool benötigt.

Beispiel für die erforderliche Antwortform (passe die Akteure an den tatsächlichen Kontext an):

Der Browser bittet die API, Daten zu speichern; die API besitzt den Datenbankzugriff.

```mermaid
sequenceDiagram
    autonumber
    participant Browser
    participant API
    participant Datenbank
    Browser->>API: Formulardaten speichern
    API->>Datenbank: Akzeptierte Daten speichern
    Datenbank-->>API: Gespeicherter Datensatz
    API-->>Browser: Erfolgsmeldung
```

Das Formular startet im Browser. Durch das Hinzufügen einer API kann es remote speichern; durch das Hinzufügen einer Datenbank überleben die gespeicherten Daten eine einzelne Anfrage.

Expliziter Aufruf

Verwende diesen Skill nur, wenn der Benutzer ihn explizit anfordert: /mental, $mental oder eine direkte Aufforderung zur Nutzung des mentalen Skills. Eine allgemeine Bitte um eine Erklärung aktiviert diesen Skill nicht. Behandle dies als eine Bitte um eine Erklärung, nicht als Erlaubnis, das erklärte System zu implementieren, zu installieren, zu veröffentlichen oder zu ändern.

Verwende das Thema, das dem Aufruf folgt, oder leite es aus dem Gespräch ab. Stelle nur eine gezielte Frage, wenn das Thema nicht vernünftig abgeleitet werden kann.

Die Erklärung aufbauen

1. Verankere das Modell im Gespräch und in den verfügbaren Beweisen. Untersuche bei einer vorhandenen Codebasis nur die Einstiegspunkte oder die Konfiguration, die zum Aufbau der relevanten Beziehungen erforderlich sind. Unterscheide beobachtete Fakten von Annahmen. Erfinde keine Dienste, erfolgreichen Bereitstellungen oder verifiziertes Verhalten.
2. Beginne mit dem kleinsten sinnvollen System: einem lokal laufenden Skript, einem Browser, der eine Seite anzeigt, oder einem Dienst, der auf eine Anfrage antwortet. Erkläre, was bereits funktioniert, bevor du Infrastruktur einführst.
3. Schreite zum diskutierten System fort. Erkläre auf jeder sinnvollen Stufe das neue Bedürfnis, den Akteur oder die Verbindung, die hinzugefügt wurden, um es zu erfüllen, und wie eine Aktion nun durch das System reist. Dies sind erklärende Stufen, keine Behauptungen über den historischen Verlauf. Wenn der Benutzer nach der tatsächlichen Projektevolution fragt, verwende die verfügbare Geschichte und identifiziere Lücken.
4. Wähle Akteure je nach Kontext: Personen, Prozesse, Dienste, Speicher, Registries, Warteschlangen oder externe Anbieter. Gib jedem eine konkrete Rolle. Gruppiere verwandte Akteure nach Maschinen-, Prozess- oder Netzwerkgrenzen, wenn der Standort das Verständnis beeinflusst.
5. Verfolge eine konkrete Aktion der Reihe nach durch die Akteure, einschließlich der Rückkehr des Ergebnisses zum Aufrufer. Beschrifte, was jede Grenze überschreitet: Quellcode, Paketarchiv, HTTP-Anfrage, JSON-Antwort, Ereignis oder gespeicherte Daten. Trenne Setup und Verteilung von der Laufzeitkommunikation, wenn beides wichtig ist.
6. Erkläre Unterscheidungen nur dort, wo sie Verwirrung beseitigen. Zum Beispiel wählt ein Paketname aus, was abgerufen werden soll, ein Befehlsname wählt aus, was ausgeführt werden soll, und ein Argument wird zur Eingabe für diesen Befehl. Für ein Browser/API-Beispiel unterscheide die Codeauslieferung von späteren API-Anfragen.

Bevorzuge eine kurze Abfolge mit verbundener Prosa gegenüber einem Glossar oder einem Katalog von Komponenten. Wenn der Benutzer nur die aktuelle Interaktion möchte, zeige diesen Ablauf, ohne eine lange Evolution zu erzwingen. Befehle und Codeausschnitte sollten das Modell verankern; vermeide Flag-Inventare, Implementierungsdurchläufe und nicht verwandte Alternativen. Behalte Details bei, die das Modell ändern, wie z. B. einen Cache, der einen Download vermeidet, oder eine asynchrone Bestätigung, die vor dem Abschluss der Arbeit eintrifft.

Diagrammgenauigkeit

Jede mit diesem Skill erstellte Antwort MUSS mindestens ein Mermaid-Diagramm oder ein gerendertes D2-Bild enthalten. Standardmäßig wird ein eingerahmter mermaid-Block verwendet: Er erfordert keine Rendering-Werkzeuge und der Quellcode bleibt lesbar, wenn Rendering nicht verfügbar ist.

• Bevorzuge ein nummeriertes Sequenzdiagramm: Beginne Mermaid-Diagramme mit sequenceDiagram gefolgt von autonumber. Mache die Reihenfolge von Aufrufen, Nachrichten und Antworten sichtbar. Führe die Teilnehmer in einer lesbaren Reihenfolge von links nach rechts ein.
• Nummeriere Antworten ebenso wie Anfragen, damit der Leser die vollständige Interaktion nachvollziehen kann. Verfolge die nummerierten Schritte in der Prosa; halte die Referenzen konsistent mit dem Diagramm. Die Nummerierung zeigt das dargestellte Szenario, nicht eine Behauptung, dass nebenläufige Arbeit immer in einer festen Reihenfolge abläuft. Verwende par, alt oder opt, wenn Nebenläufigkeit, Alternativen oder optionale Schritte das Modell ändern.
• Verwende für eine Evolution separate kleine nummerierte Sequenzen für sinnvolle Stufen; halte die Teilnehmernamen stabil und erkläre, welcher Akteur oder welche Nachricht hinzugefügt wurde.
• Verwende ein Flussdiagramm nur, wenn die Topologie oder Struktur die Hauptfrage ist und eine Sequenz sie verdecken würde, oder wenn der Benutzer eines anfordert. Für D2-Bilder, die eine Interaktion zeigen, bevorzuge ein Sequenzlayout und nummeriere die Nachrichten explizit.
• Verwende konkrete Akteursnamen und gerichtete Pfeile, die mit Aktionen oder Daten beschriftet sind. Vermeide unbeschriftete Pfeile und dekorative Kästen, die nichts erklären.
• Halte jedes Diagramm auf die zu erklärende Interaktion fokussiert. Teile verschiedene Phasen oder überladene Systeme in kleine Diagramme auf. Markiere in gestuften Diagrammen, welche Akteure und Verbindungen neu eingeführt wurden.
• Halte Beschriftungen einfach und setze Flussdiagrammbeschriftungen mit Satzzeichen in Anführungszeichen. Überprüfe Knotenreferenzen, Pfeilrichtung, Subgraphen und eingerahmte Syntax vor dem Senden.
• Eine Paketregistry verteilt Code; zeichne sie nicht so, als würde sie die CLI des Benutzers ausführen. Eine Datenbank speichert Daten; zeichne sie nicht so, als würde sie normale Anwendungsanfragen initiieren, es sei denn, dies ist ein tatsächliches Merkmal des Systems.
• Wenn der Benutzer D2 bevorzugt und ein Renderer verfügbar ist, rendere und überprüfe das Ergebnis und bette dann das Bild ein. D2-Quellcode allein erfüllt die Bildanforderung nicht. Wenn Rendering nicht verfügbar ist, verwende Mermaid und erwähne kurz den Fallback. Installiere keinen Renderer nur, um das Modell zu erklären.

Folge dem Diagramm mit einer kurzen Erläuterung der konkreten Aktion. Beende, sobald das Modell klar ist; füge keine Implementierungsaufgaben oder generischen Zusammenfassungen an.

Vor dem Senden

Überprüfe die Antwort selbst: Enthält sie einen eingerahmten mermaid-Block oder ein eingebettetes gerendertes D2-Bild? Wenn keines vorhanden ist, ist die Erklärung unvollständig. Füge das Diagramm vor dem Senden hinzu. Überprüfe bei einem Mermaid-Sequenzdiagramm, dass autonumber vorhanden ist. Stelle sicher, dass die Pfeile mit der Prosa übereinstimmen und mindestens eine reale Interaktion mit konkreten Akteuren und beschrifteter Kommunikation nachvollziehen.

Beispiele

Lies references/examples.md, wenn Beispiele helfen würden, die Erklärung zu kalibrieren. Es enthält npm-Verteilung, Frontend/Backend-Aufrufe, Service-zu-Service-Aufrufe und asynchrone Jobs. Passe den Ansatz an den tatsächlichen Kontext an, anstatt diese Akteure in jede Erklärung zu importieren.