gvozdb/semantischer-Spezifikationsautor-Skill

Semantischer Spezifikationsautor

Erstelle .plan.ctx- und .spec.ctx-Dateien, die ein Implementierungsagent verwenden kann, ohne diesen Skill laden zu müssen.

Modus

• Neues Dokument: Schreibe das endgültige semantische Artefakt direkt aus der Anfrage und den fundierten Repository-Fakten. Erstelle zuerst keinen Prosa-Entwurf.
• Vorhandenes Dokument: Konvertiere es nur wie angefordert und bewahre die Quellbedeutung und Bezeichner. Das endgültige Artefakt muss kürzer als die Quelle sein.
• Übergabe oder wiederholte Verwendung: Optimiere für die unabhängige Ausführung durch einen anderen Agenten oder einen späteren Durchlauf.
• Repository-Ausführungspaket: Wenn der Benutzer eine Codierungsübergabe wünscht und die Codebasis verfügbar ist, lies references/execution-packets.md. Fundiere eine minimale Lese-/Bearbeitungsroute, bevor du das Paket schreibst.

Behaupte nicht, dass die Konvertierung bei einer einmaligen Implementierung Gesamt-Token spart. Sie fügt einen Autorenschritt hinzu; ihre Wirtschaftlichkeit ergibt sich aus einem kleineren wiederverwendbaren Kontext und weniger Implementierungs-Mehrdeutigkeit.

Ziel

Optimiere den gesamten Implementierungsprozess, nicht nur die Zeichenanzahl:

• bewahre jedes Verhalten, jede Einschränkung, jeden Grenzfall und jede exakte Kennung;
• entferne Erzählung, Wiederholungen, dekorative Metadaten und allgemeine Ratschläge;
• lege den kürzesten zuverlässigen Weg von der Anforderung zur Bearbeitung zur Überprüfung offen;
• bevorzuge direkte Sprache gegenüber Abkürzungen, die Interpretation erfordern.

Eine kleinere Datei ist nur dann nützlich, wenn sie korrekt ausgeführt werden kann. Wenn du ein vorhandenes Dokument konvertierst, plane die kompakte Struktur, bevor du schreibst, und vermeide es, die Quelle zu erweitern. Füge keine Tools-Schleifen oder wiederholten Neuschreibungen hinzu, nur um die Dateigröße zu reduzieren.

Token-Disziplin

• Lies jede bereitgestellte Quelle einmal, es sei denn, eine fehlende Tatsache erfordert eine gezielte Suche.
• Prüfe nur Dateien, die zur Eingrenzung von Umfang, Schnittstellen und Überprüfung erforderlich sind.
• Schreibe ein endgültiges Artefakt. Mache es beim ersten Schreiben kürzer. Führe für die Konvertierung einmal scripts/check_conversion.py QUELLE AUSGABE aus diesem Skill-Verzeichnis aus. Wenn der Ziel-Tokenizer bekannt ist und tiktoken verfügbar ist, übergebe --encoding NAME. Wenn die Prüfung fehlschlägt, entferne Redundanz einmal und führe sie einmal erneut aus; führe niemals eine Größenschleife fort. Gib keinen Überblick, Entwurf, Konvertierungshinweise, Größenbericht oder Erklärung aus, es sei denn, dies wird angefordert.
• Kopiere keine Repository-Fakten, die der Implementierungsagent aus der exakten Zieldatei ohne Suche erhalten kann. Füge Fakten ein, die eine falsche Bearbeitung oder zusätzliche Erkundung verhindern.
• Bevorzuge exakte Pfade und einen ausführbaren Überprüfungsbefehl gegenüber allgemeinen Implementierungsratschlägen.
• Gib bei einem Ausführungspaket Autorenaufwand nur für Fakten aus, die nachgelagerte Erkundungen entfernen oder eine falsche Bearbeitung verhindern. Mache das Paket nicht zu einem Repository-Dump.
• Gib Ausführungspaketen die kanonische begrenzte nachgelagerte Schleife aus der Referenz: eine gelenkte Lektüre, ein Implementierungsdurchlauf, eine deklarierte Überprüfung, dann Stopp bei Erfolg. Erweiterung erfordert einen konkreten Widerspruch oder Fehler.

Format

• Beginne mit einfachem plan oder spec.
• Verwende .plan.ctx für Pläne und .spec.ctx für Spezifikationen, es sei denn, das Projekt hat eine andere Konvention.
• Verwende offensichtliche lokale Blocknamen. Sie sind Bezeichnungen, keine reservierten Sprachschlüsselwörter.
• Füge nur Blöcke ein, die Informationen tragen. Gib keine leeren Abschnitte aus.
• Kombiniere Ziel-, Umfangs- und Vertragsfakten, wenn separate Blöcke dieselben Informationen wiederholen würden.
• Bewahre Dateipfade, Symbole, API-Routen, Felder, Tabellen, Umgebungsvariablen, Befehle, Stati, Rollen und Fehlertexte exakt.
• Bewahre Feldbesitz und Verschachtelung exakt. Passe die Feldnotation an die Implementierungssprache an: Verwende für Python JSON/maps event["payment_id"], nicht event.payment_id. Erfinde niemals einen data, payload oder anderen Wrapper, den die Quelle nicht definiert.
• Behandle .ctx als einfachen Text, nicht als Markdown. Umfasse gewöhnliche Kennungen nicht mit Backticks, Fettdruck oder anderem Präsentations-Markup. Verwende Backticks nur für ausführbare Befehle unter verify.
• Definiere einen lokalen Begriff nur dann, wenn er echte Wiederholungen vermeidet. Bevorzuge beschreibende Begriffe; vermeide Ein-Buchstaben-Aliase und erfundene Notationen.
• Füge IDs nur hinzu, wenn ein anderer Gegenstand darauf verweist.
• Verwende vertraute Ausdrücke wie x=true, x in [a,b] und bedingung -> ergebnis. Verlasse dich nicht auf versteckte Syntax.
• Verwende einen kurzen #-Kommentar nur, wenn strukturierte Felder entscheidende Nuancen verlieren würden.
• Gruppiere parallele Validierungen, Ausgabefelder und exakte Fehler unter einer kompakten Zuordnung, anstatt denselben Satzrahmen zu wiederholen.
• Verwende nach der Feststellung des Feldbesitzes kurze eindeutige Bezeichnungen in Validierungs- und Fehlerzuordnungen, anstatt den vollständigen Besitzerpfad zu wiederholen.
• Lasse in einer Fehlerzuordnung den Block die wiederholte Grammatik tragen. Bevorzuge feld: bedingung | ErrorType "genaue Nachricht" vor der Wiederholung von ungültig.besitzer.feld -> ErrorType in jeder Zeile.
• Halte eine unabhängig testbare Regel pro Zeile ein. Eine gemeinsame Zuordnung kann verwandte Feld-Fälle enthalten, wenn ihre Grammatik konsistent ist.
• Verwende A*-IDs nur einmal, unter acccceptance. Verwende Akzeptanz-IDs nicht als Regel- oder Aufgaben-IDs wieder.

Fundierung

Wenn eine Codebasis verfügbar ist, prüfe sie vor dem Schreiben. Erfasse den bekannten Bearbeitungsumfang, vorhandene Schnittstellen, Einschränkungen und ausführbare Überprüfungsbefehle. Füge verify nur für einen genauen Befehl oder eine vorhandene benannte Prüfung ein; erfinde keine Überprüfungsszenarien. Rate nicht bei Dateinamen oder Architektur.

Unbekannte Entscheidungen gehören in open_questions. Lasse diesen Block weg, wenn es keine Unbekannten gibt.

Informationsreihenfolge

Ordne Informationen in der Reihenfolge an, die ein Implementierungsagent benötigt. Verwende nur die relevanten Teile:

1. Ziel oder Vorgabe, einschließlich des genauen Bearbeitungsumfangs, wenn bekannt;
2. Verträge, die nicht bereits durch die Vorgabe festgelegt sind;
3. Regeln, Invarianten, Zustände oder Abläufe;
4. geordnete Arbeit nur dort, wo Abhängigkeiten wichtig sind;
5. Überprüfungsbefehle und beobachtbare Akzeptanz;
6. ungelöste Fragen.

Genaue Reichweite und Überprüfung sparen normalerweise mehr Agentenarbeit als aggressive Prosa-Kompression.

Komprimierungsregeln

• Gib jede Tatsache einmal an.
• Führe doppelte Anforderungen zusammen.
• Lasse einen Block weg, wenn sein Inhalt bereits durch eine andere Zeile getragen wird.
• Lasse die Akzeptanz auf vorhandene Regel-, Vertrags- und Überprüfungs-IDs verweisen, anstatt deren Prosa zu wiederholen.
• Behalte die Akzeptanz nur als Referenzen bei, wenn die referenzierten Blöcke bereits das beobachtbare Verhalten angeben.
• Behalte Gründe nur bei, wenn sie eine Implementierungsentscheidung ändern.
• Ersetze vage Verben wie verbessern, unterstützen, behandeln, optimieren und korrigieren durch beobachtbare Ergebnisse.
• Behalte seltene, aber folgenreiche Grenzfälle. Lasse sie niemals fallen, um die Datei kürzer zu machen.
• Kodiere keine gewöhnlichen Anforderungen als Formeln, nur um die Wortanzahl zu reduzieren.
• Bevorzuge eine exakte quellenbezogene ganzzahlige Formel gegenüber einer längeren Prosa-Beschreibung, wenn sie korrekt auszuführen einfacher ist.

Beispiele

Implementierungsspezifikation:

spec
ziel: [src/payments.ts,tests/payments.test.ts] :: POST /payments durch Idempotency-Key idempotent machen
behalten: Antwortschema, Authentifizierungsverhalten

regeln:
  R1: Schlüsselbereich ist user_id
  R2: gleicher Benutzer + gleicher Schlüssel + gleicher Body -> ursprünglichen Status und Body wiederholen
  R3: Ergebnis vor Rückgabe des Erfolgs speichern

fehler:
  E1: fehlender Idempotency-Key -> 400 idempotency_key_required
  E2: gleicher Schlüssel + anderer Body -> 409 idempotency_conflict

verify:
  V1: `pnpm test tests/payments.test.ts`

acceptance:
  A1: R1,R2,R3,E1,E2 -> V1

Parallele Validierungszuordnung:

validierung:
  retries: int>=0 | ValueError "retries must be non-negative"
  timeout: int>0 | ValueError "timeout must be positive"

Implementierungsplan:

plan
ziel: Sitzungsspeicher von Speicher zu Redis verschieben, ohne das API-Verhalten zu ändern

fakten:
  aktueller speicher: src/session/memory.ts
  vertragstests: tests/session.contract.test.ts

aufgaben:
  T1: Redis-Adapter hinter vorhandenem SessionStore-Interface hinzufügen
  T2: Vertragstests gegen Speicher- und Redis-Adapter ausführen
  T3: Zusammensetzungs-Wurzel nach Bestehen von T2 wechseln

verify:
  V1: `pnpm test tests/session.contract.test.ts`

Qualitätssicherung

Überprüfe vor Abschluss:

• ein neuer Implementierungsagent kann ohne diesen Skill oder unausgesprochenen Kontext handeln;
• jede Zeile ändert den Umfang, das Verhalten, die Implementierungsreihenfolge oder die Überprüfung;
• keine Anforderung ist dupliziert oder durch eine undefinierte Abkürzung ersetzt;
• bekannte Dateien, Schnittstellen und Befehle sind exakt;
• die Akzeptanz ist beobachtbar und geht auf den angegebenen Vertrag zurück;
• jedes Feld hat immer noch denselben Besitzer und dieselbe Verschachtelung wie in der Quelle;
• das Ergebnis ist kürzer durch das Entfernen von Redundanz, nicht durch das Verschleiern der Bedeutung.

Gib zuerst das semantische Dokument aus. Füge separate Notizen nur für ungelöste Entscheidungen hinzu, die die Implementierung materiell blockieren.