gvozdb/semantic-spec-writer-skill

Semantic Spec Writer

Produisez des fichiers .plan.ctx et .spec.ctx qu'un agent d'implémentation peut utiliser sans avoir à charger ce skill.

Mode

• Nouveau document : rédigez l'artefact sémantique final directement à partir de la demande et des faits ancrés dans le dépôt. Ne créez pas d'abord un brouillon en prose.
• Document existant : convertissez-le uniquement comme demandé, en préservant le sens source et les identifiants. L'artefact final doit être plus court que la source.
• Transfert ou utilisation répétée : optimisez pour une exécution indépendante par un autre agent ou un tour ultérieur.
• Paquet d'exécution de dépôt : lorsque l'utilisateur souhaite un transfert de codage et que la base de code est disponible, lisez references/execution-packets.md. Ancrez un parcours de lecture/édition minimal avant d'écrire le paquet.

N'affirmez pas que la conversion économise des tokens totaux pour une implémentation unique. Elle ajoute une étape de rédaction ; son économie vient d'un contexte réutilisable plus petit et de moins d'ambiguïté d'implémentation.

Cible

Optimisez la boucle d'implémentation entière, pas seulement le nombre de caractères :

• préservez chaque comportement, contrainte, cas limite et identifiant exact ;
• supprimez la narration, les répétitions, les métadonnées décoratives et les conseils génériques ;
• exposez le chemin le plus court et fiable allant de l'exigence à l'édition puis à la vérification ;
• préférez un langage direct aux abréviations nécessitant une interprétation.

Un fichier plus petit n'est utile que s'il reste plus rapide à exécuter correctement. Lors de la conversion d'un document existant, planifiez la structure compacte avant d'écrire et évitez d'étendre la source. N'ajoutez pas de boucles d'outils ou de réécritures répétées uniquement pour réduire la taille du fichier.

Discipline des tokens

• Lisez chaque source fournie une fois, sauf si un fait manquant nécessite une recherche ciblée.
• Inspectez uniquement les fichiers nécessaires pour ancrer le périmètre, les interfaces et la vérification.
• Écrivez un seul artefact final. Rendez-le plus court dès la première écriture. Pour une conversion, exécutez scripts/check_conversion.py SOURCE OUTPUT depuis le répertoire de ce skill une fois. Lorsque le tokenizer cible est connu et que tiktoken est disponible, passez --encoding NAME. Si la vérification échoue, supprimez la redondance une fois et exécutez-la à nouveau une fois ; ne poursuivez jamais une boucle de réduction de taille. N'émettez pas de plan, de brouillon, de notes de conversion, de rapport de taille ou d'explication sauf demande explicite.
• Ne copiez pas les faits du dépôt que l'agent d'implémentation peut obtenir à partir du fichier cible exact sans recherche. Incluez les faits qui empêchent une édition erronée ou une découverte supplémentaire.
• Préférez les chemins exacts et une commande de vérification exécutable aux conseils d'implémentation génériques.
• Pour un paquet d'exécution, consacrez l'effort de rédaction uniquement aux faits qui suppriment la découverte en aval ou empêchent une édition erronée. Ne transformez pas le paquet en vidange de dépôt.
• Donnez aux paquets d'exécution la boucle aval bornée canonique de la référence : une lecture routée, un passage d'implémentation, une vérification déclarée, puis arrêtez-vous en cas de succès. L'expansion nécessite une contradiction ou un échec concret.

Format

• Commencez par plan ou spec en texte brut.
• Utilisez .plan.ctx pour les plans et .spec.ctx pour les spécifications, sauf si le projet a une autre convention.
• Utilisez des noms de blocs locaux évidents. Ce sont des étiquettes, pas des mots-clés réservés du langage.
• Incluez uniquement les blocs qui portent de l'information. N'émettez pas de sections vides.
• Combinez les faits de cible, de périmètre et de contrat lorsque des blocs séparés répéteraient la même information.
• Préservez exactement les chemins de fichiers, symboles, routes API, champs, tables, variables d'environnement, commandes, statuts, rôles et textes d'erreur.
• Préservez exactement la propriété et l'imbrication des champs. Adaptez la notation des champs au langage d'implémentation : pour Python JSON/maps utilisez event["payment_id"], pas event.payment_id. N'inventez jamais un wrapper data, payload ou autre que la source ne définit pas.
• Traitez .ctx comme du texte brut, pas du Markdown. N'entourez pas les identifiants ordinaires de backticks, gras ou autre balisage de présentation. Utilisez des backticks uniquement pour les commandes exécutables sous verify.
• Définissez un terme local uniquement lorsqu'il supprime une répétition réelle. Préférez les termes descriptifs ; évitez les alias d'une lettre et la notation inventée.
• Ajoutez des identifiants uniquement lorsqu'un autre élément y fait référence.
• Utilisez des expressions familières telles que x=true, x dans [a,b] et condition -> resultat. Ne vous fiez pas à une syntaxe cachée.
• Utilisez un court commentaire # uniquement lorsque des champs structurés perdraient une nuance critique.
• Regroupez les validations parallèles, les champs de sortie et les erreurs exactes sous une seule cartographie compacte au lieu de répéter la même structure de phrase.
• Une fois la propriété des champs établie, utilisez des étiquettes courtes et non ambiguës dans les cartographies de validation et d'erreur au lieu de répéter le chemin complet du propriétaire.
• Dans une cartographie d'erreur, laissez le bloc porter la grammaire répétée. Préférez champ : condition | TypeErreur "message exact" à la répétition de owner.champ invalide -> TypeErreur sur chaque ligne.
• Gardez une règle testable indépendamment par ligne. Une cartographie partagée peut contenir des cas de champs connexes lorsque sa grammaire est cohérente.
• Utilisez les identifiants A* une seule fois, sous acceptance. Ne réutilisez pas les identifiants d'acceptance comme identifiants de règle ou de tâche.

Ancrage

Lorsqu'une base de code est disponible, inspectez-la avant d'écrire. Capturez le périmètre d'édition connu, les interfaces existantes, les contraintes et les commandes de vérification exécutables. Incluez verify uniquement pour une commande exacte ou une vérification nommée existante ; n'inventez pas de scénarios de vérification. Ne devinez pas les noms de fichiers ou l'architecture.

Les décisions inconnues appartiennent à open_questions. Omettez ce bloc lorsqu'il n'y a pas d'inconnues.

Ordre de l'information

Placez l'information dans l'ordre dont un agent d'implémentation a besoin. Utilisez uniquement les parties pertinentes :

1. objectif ou cible, y compris le périmètre d'édition exact lorsqu'il est connu ;
2. contrats non déjà énoncés par la cible ;
3. règles, invariants, états ou flux ;
4. travail ordonné uniquement là où les dépendances comptent ;
5. commandes de vérification et acceptation observable ;
6. questions non résolues.

Un périmètre exact et une vérification économisent généralement plus de travail d'agent qu'une compression agressive de la prose.

Règles de compression

• Énoncez chaque fait une fois.
• Fusionnez les exigences en double.
• Omettez un bloc lorsque son contenu est déjà porté par une autre ligne.
• Faites référencer l'acceptance aux identifiants de règle, contrat et vérification existants au lieu de reformuler leur prose.
• Gardez l'acceptance comme références uniquement lorsque les blocs référencés énoncent déjà le comportement observable.
• Gardez les raisons uniquement lorsqu'elles modifient une décision d'implémentation.
• Remplacez les verbes vagues tels que améliorer, supporter, gérer, optimiser et corriger par des résultats observables.
• Gardez les cas limites rares mais importants. Ne les supprimez jamais pour raccourcir le fichier.
• Ne codez pas les exigences ordinaires sous forme de formules uniquement pour réduire les mots.
• Préférez une formule entière exacte dérivée de la source à une description en prose plus longue lorsqu'elle est plus facile à exécuter correctement.

Exemples

Spécification d'implémentation :

spec
cible : [src/payments.ts,tests/payments.test.ts] :: rendre POST /payments idempotent via Idempotency-Key
conserver : schéma de réponse, comportement d'authentification

regles :
  R1 : la portée de la clé est user_id
  R2 : même user + même clé + même corps -> rejouer le statut et le corps d'origine
  R3 : persister le résultat avant de retourner le succès

erreurs :
  E1 : Idempotency-Key manquant -> 400 idempotency_key_required
  E2 : même clé + corps différent -> 409 idempotency_conflict

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

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

Cartographie de validation parallèle :

validation :
  tentatives : int>=0 | ValueError "tentatives doit être non négatif"
  timeout : int>0 | ValueError "timeout doit être positif"

Plan d'implémentation :

plan
objectif : déplacer le stockage de session de la mémoire vers Redis sans modifier le comportement de l'API

faits :
  stockage actuel : src/session/memory.ts
  tests de contrat : tests/session.contract.test.ts

taches :
  T1 : ajouter un adaptateur Redis derrière l'interface SessionStore existante
  T2 : exécuter les tests de contrat contre les adaptateurs mémoire et Redis
  T3 : changer le point d'assemblage après la réussite de T2

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

Porte de qualité

Avant de terminer, vérifiez :

• un nouvel agent d'implémentation peut agir sans ce skill ni contexte non énoncé ;
• chaque ligne modifie le périmètre, le comportement, l'ordre d'implémentation ou la vérification ;
• aucune exigence n'est dupliquée ou remplacée par une abréviation non définie ;
• les fichiers, interfaces et commandes connus sont exacts ;
• l'acceptance est observable et se rattache au contrat énoncé ;
• chaque champ a toujours le même propriétaire et la même imbrication que dans la source ;
• le résultat est plus court en supprimant la redondance, pas en obscurcissant le sens.

Sortez le document sémantique en premier. Ajoutez des notes séparées uniquement pour les décisions non résolues qui bloquent matériellement l'implémentation.