Entrée utilisateur
$ARGUMENTS
Vous DEVEZ prendre en compte l'entrée utilisateur avant de poursuivre (si elle n'est pas vide).
Vérifications pré-exécution
Vérification des hooks d'extension (avant clarification) :
- Vérifiez si
.specify/extensions.ymlexiste à la racine du projet. - S'il existe, lisez-le et recherchez les entrées sous la clé
hooks.before_clarify. - Si le YAML ne peut pas être analysé ou est invalide, ne passez pas silencieusement : dites à l'utilisateur que
.specify/extensions.ymln'a pas pu être lu (incluez l'erreur de l'analyseur) et qu'aucun hook n'a été vérifié, y compris les hooks obligatoires (optional: false) qui y sont enregistrés, puis continuez normalement. - Filtrez les hooks où
enabledest explicitementfalse. Traitez les hooks sans champenabledcomme étant activés par défaut. - Pour chaque hook restant, n'essayez pas d'interpréter ou d'évaluer les expressions
conditiondu hook :- Si le hook n'a pas de champ
condition, ou s'il est nul/vide, traitez le hook comme exécutable. - Si le hook définit une
conditionnon vide, ignorez le hook et laissez l'évaluation de la condition à l'implémentation de HookExecutor.
- Si le hook n'a pas de champ
- Lors de la construction des invocations de commande à partir des noms de commande de hook, remplacez les points (
.) par des traits d'union (-). Par exemple,speckit.git.commit→/speckit-git-commit. - Pour chaque hook exécutable, affichez ce qui suit en fonction de son indicateur
optional:- Hook optionnel (
optional: true) :## Hooks d'extension **Pré-hook optionnel** : {extension} Commande : `/{command}` Description : {description} Invite : {prompt} Pour exécuter : `/{command}` - Hook obligatoire (
optional: false) :
Après avoir émis le bloc ci-dessus, vous DEVEZ effectivement invoquer le hook et attendre qu'il se termine avant de continuer. Exécutez-le de la même manière que vous exécuteriez la commande vous-même dans cet agent/session (l'invocation peut différer de l'identifiant## Hooks d'extension **Pré-hook automatique** : {extension} Exécution : `/{command}` EXECUTE_COMMAND : {command} Attendez le résultat de la commande du hook avant de passer au Plan.{command}littéral montré ci-dessus, par exemple un agent en mode skills l'exécute comme/skill:speckit-...ou$speckit-...). Le simple fait d'émettre le bloc n'exécute pas le hook.
- Hook optionnel (
- Si aucun hook n'est enregistré ou si
.specify/extensions.ymln'existe pas, passez silencieusement.
Plan
Objectif : Détecter et réduire l'ambiguïté ou les points de décision manquants dans la spécification fonctionnelle active et enregistrer les clarifications directement dans le fichier de spécification.
Remarque : Ce flux de travail de clarification doit être exécuté (et terminé) AVANT d'invoquer /speckit-plan. Si l'utilisateur indique explicitement qu'il saute la clarification (par exemple, pic exploratoire), vous pouvez continuer, mais devez avertir que le risque de reprise en aval augmente.
Étapes d'exécution :
-
Exécutez
.specify/scripts/bash/check-prerequisites.sh --json --paths-onlydepuis la racine du référentiel une fois (mode combiné--json --paths-only/-Json -PathsOnly). Analysez les champs de charge utile JSON minimaux :FEATURE_DIRFEATURE_SPEC- (Capturez éventuellement
IMPL_PLAN,TASKSpour les flux enchaînés futurs.) - Si l'analyse JSON échoue, abandonnez et demandez à l'utilisateur de ré-exécuter
/speckit-specifyou de vérifier l'environnement de la branche fonctionnelle. - Pour les guillemets simples dans les arguments comme "I'm Groot", utilisez la syntaxe d'échappement : par exemple 'I'''m Groot' (ou des guillemets doubles si possible : "I'm Groot").
-
SI EXISTE : Chargez
.specify/memory/constitution.mdpour les principes du projet et les contraintes de gouvernance. -
Chargez le fichier de spécification actuel. Effectuez une analyse structurée de l'ambiguïté et de la couverture en utilisant cette taxonomie. Pour chaque catégorie, marquez le statut : Clair / Partiel / Manquant. Produisez une carte de couverture interne utilisée pour la priorisation (n'affichagez pas la carte brute sauf si aucune question ne sera posée).
Périmètre fonctionnel et comportement :
- Objectifs utilisateur principaux et critères de succès
- Déclarations explicites hors périmètre
- Rôles utilisateur / différenciation des personas
Domaine et modèle de données :
- Entités, attributs, relations
- Identité et règles d'unicité
- Transitions d'état / cycle de vie
- Hypothèses de volume / échelle des données
Interaction et flux UX :
- Parcours utilisateur critiques / séquences
- États d'erreur / vides / chargement
- Notes d'accessibilité ou de localisation
Attributs de qualité non fonctionnels :
- Performance (latence, objectifs de débit)
- Passage à l'échelle (horizontal/vertical, limites)
- Fiabilité et disponibilité (temps de disponibilité, attentes de reprise)
- Observabilité (journalisation, métriques, signaux de traçage)
- Sécurité et confidentialité (authN/Z, protection des données, hypothèses de menace)
- Conformité / contraintes réglementaires (le cas échéant)
Intégration et dépendances externes :
- Services/API externes et modes de défaillance
- Formats d'importation/exportation de données
- Hypothèses de protocole/versioning
Cas limites et gestion des défaillances :
- Scénarios négatifs
- Limitation de débit / régulation
- Résolution de conflits (par exemple, modifications simultanées)
Contraintes et compromis :
- Contraintes techniques (langage, stockage, hébergement)
- Compromis explicites ou alternatives rejetées
Terminologie et cohérence :
- Termes de glossaire canoniques
- Synonymes évités / termes obsolètes
Signaux d'achèvement :
- Testabilité des critères d'acceptation
- Indicateurs mesurables de style Définition de Fait
Divers / Espaces réservés :
- Marqueurs TODO / décisions non résolues
- Adjectifs ambigus ("robuste", "intuitif") manquant de quantification
Pour chaque catégorie avec un statut Partiel ou Manquant, ajoutez une question candidate à moins que :
- La clarification ne modifie pas matériellement la stratégie de mise en œuvre ou de validation
- L'élément concerne spécifiquement la méthode de mise en œuvre, la comparaison de piles technologiques ou la répartition des tâches (notez-le en interne)
-
Générez (en interne) une file d'attente priorisée de questions de clarification candidates (maximum 5). Ne les affichez PAS toutes en même temps. Appliquez ces contraintes :
- Maximum de 5 questions au total pour toute la session.
- Chaque question doit pouvoir être répondue avec SOIT :
- Une sélection à choix multiples court (2–5 options distinctes et mutuellement exclusives), SOIT
- Une réponse d'un mot / phrase courte (contraignez explicitement : "Répondez en <=5 mots").
- N'incluez que les questions dont les réponses ont un impact matériel sur l'architecture, la modélisation des données, la décomposition des tâches, la conception des tests, le comportement UX, la maturité opérationnelle ou la validation de la conformité.
- Assurez l'équilibre de la couverture des catégories : essayez de couvrir d'abord les catégories non résolues à plus fort impact ; évitez de poser deux questions à faible impact alors qu'un seul domaine à fort impact (par exemple, la posture de sécurité) n'est pas résolu.
- Excluez les questions déjà répondues, les préférences stylistiques triviales ou les détails d'exécution au niveau du plan (sauf s'ils bloquent l'exactitude).
- Favorisez les clarifications qui réduisent le risque de reprise en aval ou empêchent des tests d'acceptation mal alignés.
- Si plus de 5 catégories restent non résolues, sélectionnez les 5 premières selon l'heuristique (Impact * Incertitude).
-
Boucle de questionnement séquentielle (interactive) :
-
Présentez EXACTEMENT UNE question à la fois.
-
Qualité de rédaction des questions (s'applique à chaque question, MC ou réponse courte) :
- Commencez par
**Question :**suivi d'une interrogative complète qui se termine par?. Le texte de la question avant le?doit avoir un sens en soi. - N'utilisez JAMAIS une étiquette de sujet, un titre de section ou un identifiant d'exigence comme question elle-même. Par exemple,
Matrice appareil/environnement d'acceptation (FR-023)est INVALIDE — c'est une étiquette, pas une question. - Après le
?, le seul suffixe autorisé est un identifiant d'exigence/de question facultatif entre parenthèses. Format exact :**Question :** <interrogative>?ou**Question :** <interrogative>? (FR-023). Ne mettez jamais l'identifiant avant le?, et n'utilisez jamais l'identifiant (seul ou avec une étiquette de sujet) comme invite complète. - Immédiatement après la ligne de question, ajoutez une phrase en langage clair "Pourquoi c'est important" (l'enjeu pour l'acceptation ou la livraison) avant la recommandation/les options.
- Utilisez un langage courant ; n'introduisez du jargon que s'il est défini dans la même phrase. Auto-vérification : un lecteur qui ne connaît pas Spec Kit doit pouvoir répondre à partir de la seule ligne de question. Concis est acceptable ; les étiquettes cryptiques ne le sont pas.
- Commencez par
-
Pour les questions à choix multiples :
- Analysez toutes les options et déterminez l'option la plus appropriée en fonction de :
- Les bonnes pratiques pour le type de projet
- Les modèles courants dans des implémentations similaires
- La réduction des risques (sécurité, performance, maintenabilité)
- L'alignement avec les objectifs ou contraintes explicites du projet visibles dans la spécification
- Présentez votre option recommandée de manière proéminente en haut avec un raisonnement clair (1-2 phrases expliquant pourquoi c'est le meilleur choix).
- Formatez comme :
**Recommandé :** Option [X] - <raisonnement> - Ensuite, affichez toutes les options sous forme de tableau Markdown :
Option Description A <Description de l'option A> B <Description de l'option B> C <Description de l'option C> (ajoutez D/E si nécessaire jusqu'à 5) Courte Fournissez une réponse courte différente (<=5 mots) (Incluez uniquement si une alternative en forme libre est appropriée) - Après le tableau, ajoutez :
Vous pouvez répondre avec la lettre de l'option (par exemple, "A"), accepter la recommandation en disant "oui" ou "recommandé", ou fournir votre propre réponse courte.
- Analysez toutes les options et déterminez l'option la plus appropriée en fonction de :
-
Pour le style réponse courte (pas d'options discrètes significatives) :
- Fournissez votre réponse suggérée basée sur les meilleures pratiques et le contexte.
- Formatez comme :
**Suggéré :** <votre réponse proposée> - <bref raisonnement> - Ensuite, affichez :
Format : Réponse courte (<=5 mots). Vous pouvez accepter la suggestion en disant "oui" ou "suggéré", ou fournir votre propre réponse.
-
Après que l'utilisateur a répondu :
- Si l'utilisateur répond par "oui", "recommandé" ou "suggéré", utilisez votre recommandation/suggestion précédemment énoncée comme réponse.
- Sinon, validez que la réponse correspond à une option ou respecte la contrainte <=5 mots.
- Si ambiguë, demandez une désambiguïsation rapide (le comptage appartient toujours à la même question ; n'avancez pas).
- Une fois satisfaisante, enregistrez-la dans la mémoire de travail (n'écrivez pas encore sur le disque) et passez à la question suivante dans la file d'attente.
-
Arrêtez de poser d'autres questions lorsque :
- Toutes les ambiguïtés critiques sont résolues tôt (les éléments restants dans la file deviennent inutiles), OU
- L'utilisateur signale la fin ("fini", "bon", "pas plus"), OU
- Vous avez atteint 5 questions posées.
-
Ne révélez jamais les futures questions en file d'attente à l'avance.
-
Si aucune question valide n'existe au départ, signalez immédiatement qu'il n'y a pas d'ambiguïtés critiques.
-
-
Intégration après CHAQUE réponse acceptée (approche de mise à jour incrémentielle) :
- Maintenez une représentation en mémoire de la spécification (chargée une fois au début) ainsi que le contenu brut du fichier.
- Pour la première réponse intégrée de cette session :
- Assurez-vous qu'une section
## Clarificationsexiste (créez-la juste après la section contextuelle/vue d'ensemble de plus haut niveau selon le modèle de spécification si elle est manquante). - En dessous, créez (s'il n'est pas présent) un sous-titre
### Session AAAA-MM-JJpour aujourd'hui.
- Assurez-vous qu'une section
- Ajoutez immédiatement une ligne de puce après l'acceptation :
- Q : <question> → R : <réponse finale>. - Ensuite, appliquez immédiatement la clarification aux sections les plus appropriées :
- Ambigüité fonctionnelle → Mettez à jour ou ajoutez une puce dans les Exigences Fonctionnelles.
- Interaction utilisateur / distinction des acteurs → Mettez à jour les User Stories ou la sous-section Acteurs (si présente) avec un rôle, une contrainte ou un scénario clarifié.
- Forme des données / entités → Mettez à jour le Modèle de Données (ajoutez des champs, types, relations) en préservant l'ordre ; notez succinctement les contraintes ajoutées.
- Contrainte non fonctionnelle → Ajoutez/modifiez des critères mesurables dans Critères de Succès > Résultats Mesurables (convertissez un adjectif vague en métrique ou cible explicite).
- Cas limite / flux négatif → Ajoutez une nouvelle puce sous Cas Limites / Gestion des Erreurs (ou créez une telle sous-section si le modèle fournit un espace réservé pour cela).
- Conflit de terminologie → Normalisez le terme dans toute la spécification ; ne conservez l'original que si nécessaire en ajoutant
(anciennement appelé "X")une fois.
- Si la clarification invalide un énoncé ambigu antérieur, remplacez cet énoncé au lieu de le dupliquer ; ne laissez aucun texte obsolète contradictoire.
- Enregistrez le fichier de spécification APRÈS chaque intégration pour minimiser le risque de perte de contexte (écrasement atomique).
- Préservez la mise en forme : ne réorganisez pas les sections non liées ; maintenez la hiérarchie des titres intacte.
- Gardez chaque clarification insérée minimale et testable (évitez la dérive narrative).
-
Validation (effectuée APRÈS chaque écriture plus passe finale) :
- La session de clarifications contient exactement une puce par réponse acceptée (pas de doublons).
- Total des questions posées (acceptées) ≤ 5.
- Les sections mises à jour ne contiennent aucun espace réservé vague persistant que la nouvelle réponse était censée résoudre.
- Aucun énoncé antérieur contradictoire ne subsiste (vérifiez que les choix alternatifs désormais invalides ont été supprimés).
- Structure Markdown valide ; seuls les nouveaux titres autorisés :
## Clarifications,### Session AAAA-MM-JJ. - Cohérence de la terminologie : même terme canonique utilisé dans toutes les sections mises à jour.
-
Écrivez la spécification mise à jour dans
FEATURE_SPEC. -
Re-validez la liste de contrôle de qualité de la spécification (si elle existe) :
- Vérifiez si
FEATURE_DIR/checklists/requirements.mdexiste. - S'il n'existe PAS, passez cette étape silencieusement.
- S'il existe :
- Lisez le fichier de liste de contrôle.
- Identifiez toutes les lignes de cases à cocher de la liste de tâches GitHub — les lignes correspondant à
- [ ],- [x], ou- [X](insensible à la casse, tolérant les espaces de début pour les éléments imbriqués) en dehors des blocs de code. Ignorez tout autre contenu (titres, notes, puces sans case à cocher, métadonnées). - Pour chaque ligne de case à cocher, enregistrez son état actuel (cochée ou décochée) et le texte de l'élément dans une liste d'instantané avant.
- Réévaluez chaque élément de case à cocher par rapport à la spécification mise à jour (la version qui vient d'être sauvegardée à l'étape 7).
- Pour chaque élément de case à cocher, mettez à jour uniquement si l'état coché/décoché change réellement :
- Si l'élément passe maintenant et était décoché : changez
[ ]en[x]. - Si l'élément échoue maintenant et était coché : changez
[x]/[X]en[ ]. - Si l'état est inchangé : ne touchez pas à la ligne.
- Si l'élément passe maintenant et était décoché : changez
- Vérifiez si