RaamPrashathT/spec-it

Que fait spec-it ?

Transformez $ARGUMENTS en une spécification qu'un agent de codage peut utiliser sans questions de suivi, accompagnée de maquettes qui montrent chaque exigence et cas limite.

Idée → 1. Contexte (sans questions) → 2. Questions produit → 3. Questions techniques
     → 4. REQUIREMENTS.md → 5. Maquettes → 6. Vérification

Les chemins comme references/… sont relatifs à ${CLAUDE_SKILL_DIR}. La sortie se trouve dans spec-it/<nom-kebab>/ :

spec-it/<nom>/
├── REQUIREMENTS.md      le livrable unique : intention, décisions, phases, FR, EC, hypothèses
└── mockups/             index.html + écrans, ou api.html + openapi.yaml, ou cli.html + transcripts.md
    └── assets/          theme.css, fixtures.js, app.js

Règles

1. Les faits sont vôtres, les décisions sont les leurs. Ne demandez jamais ce que le dépôt, les fichiers joints, le web ou une norme peuvent répondre. Ne décidez jamais du périmètre, des priorités ou des compromis à la place du développeur.
2. Chaque question doit mériter sa place. Exécutez le filtre de questions dans references/questions.md avant chacune. Un détail avec une valeur par défaut défendable et standard est une hypothèse (A-n), pas une question.
3. Pas de quota. Il n'y a pas de minimum. Les exécutions typiques posent 5 à 12 questions. Arrêtez-vous lorsque vous pouvez prédire les prochaines réponses du développeur.
4. Posez via le sélecteur (AskUserQuestion ; texte numéroté simple sans lui). Jusqu'à 3 questions indépendantes par appel ; ne regroupez jamais une question dont les options dépendent d'une autre non répondue.
5. Chaque question s'affiche une fois, en dernier dans votre message. Pas de récapitulatif ensuite.
6. Écrivez l'état sur le disque. Après l'étape de contexte, gardez REQUIREMENTS.md comme fichier de travail : rédigez les §1–2 tôt, remplissez les décisions au fur et à mesure qu'elles se stabilisent. Après une compaction de contexte, relisez-le avant d'agir.
7. Les maquettes fonctionnent hors ligne. Pas de CDN, réseau ou polices web.
8. Le script de vérification valide la complétion : node ${CLAUDE_SKILL_DIR}/scripts/check.mjs spec-it/<nom> retourne 0.

IDs : FR-n exigence, EC-n cas limite, D-n décision, A-n hypothèse. Avec des modules, FR/EC/A prennent un préfixe de module (BOOK-FR-3). Les IDs sont permanents : ne renumérotez jamais ; retirez avec « (supprimé) ».

1. Contexte (pas encore de questions)

Faites ceci avant de demander quoi que ce soit. Exécutez les deux recherches en parallèle, avec des sous-agents à contexte frais si disponibles :

• Analyse de la base de code (ignorer si le dossier est vide) : pile, fonctionnalités existantes qui chevauchent l'idée, modèles de données, authentification, kit UI et tokens de design, API et conventions CLI, tout ce qui est à moitié construit. Au maximum 25 lignes en retour.
• Analyse des références (recherche web, 2–4 recherches) : comment 2–3 produits établis ou normes résolvent cela ; les problèmes difficiles connus du domaine (ce qui va mal dans l'utilisation réelle) ; l'ensemble des fonctionnalités standards ; toute spécification pertinente (RFC, clig.dev, WCAG, règles de paiement ou de confidentialité). Au maximum 25 lignes en retour, avec des liens sources.

Présentez ensuite au développeur un résumé de contexte, d'au plus 15 lignes :

Ce que j'ai trouvé
- Dépôt : <ce qui existe que cela touche ou réutilise>
- Comment les autres font : <produit A fait X, produit B fait Y>
- Problèmes difficiles dans ce domaine : <2–4, ex. les no-shows laissent les salles vides ; réservations récurrentes>
- Mon analyse : <hypothèse en une phrase de ce que vous voulez et pourquoi> · confiance <n>%

Classifiez le type (UI, API, CLI, mixte) et créez REQUIREMENTS.md à partir de assets/requirements-template.md avec §1 et la section Contexte remplie. Les problèmes difficiles que vous avez trouvés sont la matière première de vos meilleures questions.

2. Questions produit

Lisez references/questions.md. Partez de l'inconnu le plus risqué : est-ce le bon problème, pour qui, qu'est-ce qui est livré en premier, qu'est-ce qui est exclu, puis les problèmes difficiles du domaine sous forme de scénarios concrets. Enregistrez chaque réponse comme D-n dans §Décisions au fur et à mesure.

Passez aux questions techniques lorsque les trois conditions sont remplies :

• vous pouvez écrire le récapitulatif (résultat, utilisateur, pourquoi maintenant, succès, hors périmètre) dans les propres mots du développeur ;
• le périmètre de la Phase 1 et les non-objectifs sont convenus ;
• ce qui reste concerne comment, pas quoi, qui ou pourquoi.

Exception : une contrainte forte qui modifie le périmètre (« doit fonctionner hors ligne », « réutiliser notre locataire Auth0 », « les données restent dans l'UE ») est demandée dès qu'elle apparaît, car elle remodèle les questions produit.

3. Questions techniques

Uniquement aux points de bifurcation : endroits où le dépôt et les normes ne le tranchent pas, et où la réponse change le modèle de données, un contrat ou le comportement visible par l'utilisateur. La liste se trouve dans references/questions.md § Techniques. De nombreux passages nécessitent 0–4 questions. Ne demandez jamais d'hébergement, CI, framework ou choix de fournisseur déjà fixés par le dépôt.

Porte de confirmation. Un message : le récapitulatif (6 lignes), puis chaque hypothèse que vous avez prise (A-n, une ligne chacune, avec sa valeur par défaut). Demandez : confirmer, ou nommer celles à modifier. Intégrez les modifications. Écrivez Statut : Confirmé sur la ligne de statut de la spécification seulement après un oui explicite.

Phases et modules

Phases (toujours considérées). La question produit « qu'est-ce qui est livré en premier ? » les détermine. La Phase 1 est la tranche la plus fine où un utilisateur accomplit la tâche principale de bout en bout (squelette fonctionnel). Si le développeur veut tout en une fois, il y a une phase. Chaque FR porte Phase : n. La Phase 1 est spécifiée en détail ; les phases ultérieures sont un puce par capacité dans §Plan de livraison jusqu'à ce que --next-phase les détaille.

Modules (uniquement sur signaux). Traitez un domaine comme un module seulement lorsqu'il répond à deux critères ou plus : personnes ou vocabulaire différents ; possède ses propres données ; utile s'il est livré seul ; nécessiterait 10+ questions à lui seul. Avec 2+ domaines qualifiés, demandez une fois : une seule spécification avec sections de modules (recommandé), ou spécifiez le module le plus important maintenant et esquissez le reste. Ne déduisez jamais de modules de la taille perçue de l'idée. Les modules restent dans le même REQUIREMENTS.md sous forme de sections ## dans §Exigences fonctionnelles, avec des préfixes d'ID.

Limite de taille. Si la Phase 1 dépasse environ 25 FR Obligatoires ou 12 artefacts de maquette, demandez lesquels déplacer en Phase 2.

4. Rédiger REQUIREMENTS.md

Remplissez le modèle. Chaque FR a un ID, une priorité, une phase, un Given/When/Then, et un Source : IDs de décision ; chaque cas limite soulevé devient un EC-n avec des valeurs de fixture concrètes. Les FR disent ce que l'utilisateur observe ; la technologie va dans §Décisions techniques. Puis auto-vérifiez une fois sur cette liste et corrigez ce qui échoue :

• Deux affirmations qui ne peuvent pas être vraies en même temps ; une règle énoncée deux fois.
• Un FR qu'un développeur pourrait construire de deux manières différentes (limite, unité, rôle ou comportement d'échec manquant).
• Un critère qui ne peut pas passer ou échouer par observation, ou un mot vague sans nombre.
• Un rôle, entité ou flux sans FR ; une décision citée par rien.
• Un mot utilisé à l'encontre du glossaire.

5. Maquettes

Listez les artefacts (écrans, groupes de points d'API ou groupes de commandes), au maximum 12, chacun avec ses états, et chaque EC mappé à un état. Affichez la liste en un message et continuez sauf si le développeur s'y oppose. Puis lisez references/screens.md (UI) ou references/api-cli.md (API, CLI) et construisez :

1. Écrivez d'abord mockups/assets/fixtures.js : chaque nom, ID, montant et date qu'un artefact affiche.
2. UI : écrivez l'orientation de design dans §Orientation de design. Si le dépôt a un système de design ou des tokens, suivez-le et ignorez la question de design ; sinon posez une question d'orientation de design avec des croquis ASCII dans les aperçus d'options.
3. Copiez ${CLAUDE_SKILL_DIR}/assets/theme.css et app.js dans mockups/assets/, définissez les tokens, et exécutez la vérification jusqu'à ce que le contraste soit acceptable.
4. Construisez chaque artefact à partir de references/renderer.md : avec 4+ artefacts et un outil sous-agent, un sous-agent par artefact en parallèle ; sinon un à la fois ici. CLI : écrivez mockups/transcripts.md, puis node ${CLAUDE_SKILL_DIR}/scripts/cli-render.mjs spec-it/<nom>.
5. Remplissez mockups/index.html à partir de ${CLAUDE_SKILL_DIR}/assets/index.html.
6. UI avec un outil navigateur : exécutez éventuellement references/critic.md et appliquez ses meilleures corrections une fois.

6. Vérification et rapport

Exécutez le script de vérification jusqu'à ce qu'il retourne 0 ; traitez les avertissements d'ambiguïté comme des formulations à améliorer. Rapportez en au plus 10 lignes : le chemin, les comptes (questions posées, FR, EC, hypothèses, artefacts), la ligne de résumé de vérification, comment voir les maquettes (ouvrir mockups/index.html, ou node ${CLAUDE_SKILL_DIR}/scripts/serve.mjs spec-it/<nom>), et la phase suivante s'il y en a une. node ${CLAUDE_SKILL_DIR}/scripts/export.mjs spec-it/<nom> écrit des copies fichier unique pour le partage, sur demande.

Exécutions ultérieures

• --next-phase : lisez la spécification, prenez les puces de la phase suivante, exécutez les étapes 2 à 6 pour elles uniquement (les questions partent de ce que la Phase 1 a laissé ouvert). Les nouveaux FR continuent la numérotation ; les ID antérieurs ne changent jamais.
• --revise (ou une demande de modification) : enregistrez la nouvelle décision, mettez à jour les FR et EC affectés, ne re-rendez que les artefacts affectés, exécutez à nouveau la vérification.

Rationalisations

Pensée	Réalité
« Je devrais couvrir tous les domaines, donc je vais demander les intégrations. »	Demandez seulement si la réponse change la spécification. « Aucune dans v1 » est une hypothèse.
« Je vais demander quel pas de temps ils veulent. »	Une valeur par défaut standard existe. Enregistrez A-n ; la porte de confirmation l'affiche.
« L'idée est claire, ignorez l'étape de contexte. »	L'étape de contexte est d'où viennent les bonnes questions. Exécutez-la toujours.
« L'idée semble grosse, donc des modules. »	Les modules nécessitent les signaux, puis le choix du développeur.
« Ils ont accepté toutes les recommandations, super. »	Les recommandations peuvent être trop sûres. Votre prochaine question devrait être une avec laquelle ils ne seraient pas d'accord.