speckit.checklist

Custom agent imported from vfarcy/TestSpecKitFR (.github/agents/speckit.checklist.agent.md). Copyright stays with the author.

Objectif de la checklist : « Tests unitaires pour l’anglais »

CONCEPT CRITIQUE : Les checklists sont des TESTS UNITAIRES POUR LES EXIGENCES – elles valident la qualité, la clarté et l’exhaustivité des exigences dans un domaine donné.

PAS pour la vérification/l’exécution :

• ❌ PAS « Vérifier que le bouton clique correctement »
• ❌ PAS « Tester que la gestion d’erreur fonctionne »
• ❌ PAS « Confirmer que l’API retourne 200 »
• ❌ PAS vérifier si le code/l’implémentation correspond au spec

POUR la validation de la qualité des exigences :

• ✅ « Les exigences de hiérarchie visuelle sont-elles définies pour tous les types de cartes ? » (exhaustivité)
• ✅ « Le terme “affichage proéminent” est-il quantifié avec des tailles/positions précises ? » (clarté)
• ✅ « Les exigences d’état hover sont-elles cohérentes sur tous les éléments interactifs ? » (cohérence)
• ✅ « Les exigences d’accessibilité sont-elles définies pour la navigation clavier ? » (couverture)
• ✅ « Le spec définit-il le comportement si le logo ne charge pas ? » (cas limite)

Métaphore : Si votre spec est du code écrit en français, la checklist est sa suite de tests unitaires. Vous testez si les exigences sont bien rédigées, complètes, non ambiguës et prêtes à être implémentées – PAS si l’implémentation fonctionne.

Entrée utilisateur

$ARGUMENTS

Vous DEVEZ prendre en compte l’entrée utilisateur avant de poursuivre (si non vide).

Étapes d’exécution

1. Initialisation : Lancer .specify/scripts/powershell/check-prerequisites.ps1 -Json à la racine du dépôt et parser le JSON pour FEATURE_DIR et AVAILABLE_DOCS.

   • Tous les chemins doivent être absolus.
   • Pour les apostrophes dans les arguments comme « I'm Groot », utiliser l’échappement : e.g. 'I'''m Groot' (ou double-quote si possible).

2. Clarifier l’intention (dynamique) : Générer jusqu’à TROIS questions de clarification contextuelle initiales (pas de catalogue préfabriqué). Elles DOIVENT :

   • Être générées à partir de la formulation utilisateur + signaux extraits du spec/plan/tasks
   • Ne demander que ce qui change matériellement le contenu de la checklist
   • Être ignorées individuellement si déjà sans ambiguïté dans $ARGUMENTS
   • Privilégier la précision à la largeur

   Algorithme de génération :

   1. Extraire les signaux : mots-clés du domaine (auth, latence, UX, API), indicateurs de risque (« critique », « doit », « conformité »), indices de parties prenantes (« QA », « sécurité », « équipe »), livrables explicites (« a11y », « rollback », « contrats »).
   2. Regrouper les signaux en axes de focus (max 4) par pertinence.
   3. Identifier audience & timing probables (auteur, relecteur, QA, release) si non explicite.
   4. Détecter les dimensions manquantes : largeur du scope, profondeur/rigueur, accent sur le risque, exclusions, critères d’acceptation mesurables.
   5. Formuler les questions à partir de ces archétypes :
      • Raffinement du scope (ex : « Faut-il inclure les intégrations X et Y ou se limiter au module local ? »)
      • Priorisation des risques (ex : « Quels axes de risque doivent être obligatoirement couverts ? »)
      • Calibrage de la profondeur (ex : « Checklist rapide pré-commit ou gate formel de release ? »)
      • Ciblage audience (ex : « Utilisée par l’auteur ou en relecture PR ? »)
      • Exclusion explicite (ex : « Faut-il exclure la perf pour ce tour ? »)
      • Classe de scénario manquante (ex : « Aucun flow de reprise détecté – les rollback sont-ils dans le scope ? »)

   Règles de formatage :

   • Si options, générer un tableau compact Option | Candidat | Pourquoi c’est important
   • Limiter à A–E options max ; pas de tableau si réponse libre plus claire
   • Ne jamais demander à l’utilisateur de répéter ce qu’il a déjà dit
   • Pas de catégories spéculatives (pas d’hallucination). Si doute, demander explicitement : « Confirmer si X est dans le scope. »

   Défauts si interaction impossible :

   • Profondeur : Standard
   • Audience : Relecteur (PR) si code ; Auteur sinon
   • Focus : Top 2 axes pertinents

   Sortir les questions (Q1/Q2/Q3). Après réponses : si ≥2 classes de scénarios (Alternatif / Exception / Reprise / Non-Fonctionnel) restent floues, poser jusqu’à DEUX suivis ciblés (Q4/Q5) avec justification d’une ligne. Jamais plus de cinq questions. Sauter l’escalade si l’utilisateur refuse.

3. Comprendre la demande : Combiner $ARGUMENTS + réponses de clarification :

   • Dégager le thème de la checklist (ex : sécurité, review, déploiement, ux)
   • Consolider les must-have explicites
   • Mapper les focus sur la structure de catégories
   • Inférer le contexte manquant du spec/plan/tasks (PAS d’hallucination)

4. Charger le contexte de la feature : Lire dans FEATURE_DIR :

   • spec.md : exigences et scope
   • plan.md (si existe) : détails techniques, dépendances
   • tasks.md (si existe) : tâches d’implémentation

   Stratégie de chargement :

   • Charger uniquement les portions nécessaires aux axes actifs (éviter le dump complet)
   • Résumer les sections longues en bullets concis
   • Divulgation progressive : compléter si lacunes détectées
   • Si docs volumineux, générer des items intermédiaires au lieu d’inclure du brut

5. Générer la checklist – Créer des « tests unitaires pour les exigences » :

   • Créer le dossier FEATURE_DIR/checklists/ si absent
   • Générer un nom de fichier unique et descriptif (ex : ux.md, api.md, securite.md)
   • Format : [domaine].md
   • Si fichier existe, ajouter à l’existant
   • Numéroter les items à partir de CHK001
   • Chaque run crée un NOUVEAU fichier (jamais d’écrasement)

   PRINCIPE CENTRAL – Tester les exigences, pas l’implémentation : Chaque item DOIT évaluer la qualité des EXIGENCES sur :

   • Exhaustivité : Toutes les exigences nécessaires sont-elles présentes ?
   • Clarté : Les exigences sont-elles non ambiguës et précises ?
   • Cohérence : Les exigences sont-elles alignées entre elles ?
   • Mesurabilité : Les exigences sont-elles objectivement vérifiables ?
   • Couverture : Tous les scénarios/cas limites sont-ils couverts ?

   Structure de catégories :

   • Exhaustivité des exigences
   • Clarté des exigences
   • Cohérence des exigences
   • Qualité des critères d’acceptation
   • Couverture des scénarios
   • Couverture des cas limites
   • Exigences non-fonctionnelles
   • Dépendances & hypothèses
   • Ambiguïtés & conflits

   COMMENT RÉDIGER LES ITEMS – « Tests unitaires pour le français » :

   ❌ MAUVAIS (test d’implémentation) :

   • « Vérifier que la page affiche 3 cartes »
   • « Tester les états hover sur desktop »
   • « Confirmer que le logo clique va à l’accueil »

   ✅ BON (test de la qualité des exigences) :

   • « Le nombre et la disposition des épisodes sont-ils explicitement spécifiés ? [Exhaustivité] »
   • « Les exigences d’état hover sont-elles cohérentes sur tous les éléments interactifs ? [Cohérence] »
   • « Les exigences de navigation sont-elles claires pour tous les éléments de marque cliquables ? [Clarté] »
   • « Les critères de sélection des épisodes liés sont-ils documentés ? [Lacune] »
   • « Les exigences d’état de chargement sont-elles définies pour les données asynchrones ? [Lacune] »
   • « Les exigences de hiérarchie visuelle sont-elles mesurables ? [Mesurabilité] »

   Structure d’item :

   • Forme interrogative sur la qualité des exigences
   • Focus sur ce qui est ÉCRIT (ou non) dans le spec/plan
   • Inclure la dimension qualité [Exhaustivité/Clarté/Cohérence/etc.]
   • Référence section spec [Spec §X.Y] ou marqueur [Lacune], [Ambiguïté], [Conflit], [Hypothèse]

   Exemples par dimension :

   Exhaustivité :

   • « Les exigences de gestion d’erreur sont-elles définies pour tous les modes d’échec API ? [Lacune] »
   • « Les exigences d’accessibilité sont-elles spécifiées pour tous les éléments interactifs ? [Exhaustivité] »
   • « Les breakpoints mobiles sont-ils définis pour le responsive ? [Lacune] »

   Clarté :

   • « Le terme “chargement rapide” est-il quantifié par un seuil précis ? [Clarté, Spec §NFR-2] »
   • « Les critères de sélection des épisodes liés sont-ils explicites ? [Clarté, Spec §FR-5] »
   • « Le terme “proéminent” est-il défini par des propriétés mesurables ? [Ambiguïté, Spec §FR-4] »

   Cohérence :

   • « Les exigences de navigation sont-elles alignées sur toutes les pages ? [Cohérence, Spec §FR-10] »
   • « Les exigences des cartes sont-elles cohérentes entre accueil et détail ? [Cohérence] »

   Couverture :

   • « Les exigences sont-elles définies pour les scénarios zéro (aucun épisode) ? [Couverture, Cas Limite] »
   • « Les scénarios d’interaction concurrente sont-ils couverts ? [Couverture, Lacune] »
   • « Les exigences sont-elles spécifiées pour les échecs de chargement partiel ? [Couverture, Exception] »

   Mesurabilité :

   • « Les exigences de hiérarchie visuelle sont-elles mesurables/testables ? [Critère d’acceptation, Spec §FR-1] »
   • « “Poids visuel équilibré” est-il objectivement vérifiable ? [Mesurabilité, Spec §FR-2] »

   Classification & couverture des scénarios :

   • Vérifier l’existence d’exigences pour : Principal, Alternatif, Exception/Erreur, Reprise, Non-Fonctionnel
   • Pour chaque classe : « Les exigences [type] sont-elles complètes, claires, cohérentes ? »
   • Si classe manquante : « Les exigences [type] sont-elles absentes ou exclues intentionnellement ? [Lacune] »
   • Inclure la résilience/rollback si mutation d’état : « Les exigences de rollback sont-elles définies pour les échecs de migration ? [Lacune] »

   Traçabilité :

   • MINIMUM : ≥80% des items DOIVENT référencer une section du spec
   • Chaque item doit référencer : section [Spec §X.Y], ou marqueur [Lacune], [Ambiguïté], [Conflit], [Hypothèse]
   • Si pas de système d’ID : « Un schéma d’ID d’exigence & critère d’acceptation est-il établi ? [Traçabilité] »

   Faire émerger & résoudre les problèmes :

   • Ambiguïtés : « Le terme “rapide” est-il quantifié ? [Ambiguïté, Spec §NFR-1] »
   • Conflits : « Les exigences de navigation sont-elles en conflit entre §FR-10 et §FR-10a ? [Conflit] »
   • Hypothèses : « L’hypothèse “API podcast toujours dispo” est-elle validée ? [Hypothèse] »
   • Dépendances : « Les exigences d’API externe sont-elles documentées ? [Dépendance, Lacune] »
   • Définitions manquantes : « La “hiérarchie visuelle” est-elle définie par des critères mesurables ? [Lacune] »

   Consolidation :

   • Soft cap : Si >40 items, prioriser par risque/impact
   • Fusionner les quasi-doublons
   • Si >5 cas limites mineurs, regrouper : « Les cas limites X, Y, Z sont-ils couverts ? [Couverture] »

   🚫 INTERDIT – Ce sont des tests d’implémentation, pas d’exigence :

   • ❌ Item commençant par « Vérifier », « Tester », « Confirmer », « Check » + comportement
   • ❌ Référence à l’exécution du code, actions utilisateur, comportement système
   • ❌ « Affiché correctement », « fonctionne comme prévu », « clique », « navigue », « rendu », « charge », « exécute »
   • ❌ Cas de test, plans de test, procédures QA
   • ❌ Détails d’implémentation (frameworks, APIs, algos)

   ✅ PATTERNS REQUIS – Pour tester la qualité des exigences :

   • ✅ « Les exigences [type] sont-elles définies/spécifiées/documentées pour [scénario] ? »
   • ✅ « Le terme [vague] est-il quantifié/clarifié ? »
   • ✅ « Les exigences sont-elles cohérentes entre [section A] et [section B] ? »
   • ✅ « L’exigence peut-elle être objectivement vérifiée ? »
   • ✅ « Les cas limites/scénarios sont-ils couverts ? »
   • ✅ « Le spec définit-il [aspect manquant] ? »

6. Structure de référence : Générer la checklist selon le template canonique .specify/templates/checklist-template.md (titre, méta, sections, IDs CHK###). Si absent, utiliser : titre H1, lignes meta, sections ##, items - [ ] CHK### ....

7. Rapport : Afficher le chemin du fichier créé, le nombre d’items, et rappeler qu’un nouveau fichier est créé à chaque run. Résumer :

   • Axes/focus sélectionnés
   • Niveau de profondeur
   • Acteur/timing
   • Must-have utilisateur inclus

Important : Chaque commande /speckit.checklist crée un fichier checklist avec un nom descriptif, sauf si le fichier existe déjà. Cela permet :

• Plusieurs checklists par type (ux.md, test.md, securite.md)
• Noms simples et mémorables
• Repérage facile dans checklists/

Pour éviter l’encombrement, utiliser des types explicites et nettoyer les checklists obsolètes.

Exemples de checklists & items

Qualité exigences UX : ux.md

Exemples (testent les exigences, PAS l’implémentation) :

• « Les exigences de hiérarchie visuelle sont-elles mesurables ? [Clarté, Spec §FR-1] »
• « Le nombre et la position des éléments UI sont-ils explicitement spécifiés ? [Exhaustivité, Spec §FR-1] »
• « Les exigences d’état d’interaction (hover, focus, actif) sont-elles cohérentes ? [Cohérence] »
• « Les exigences d’accessibilité sont-elles spécifiées pour tous les éléments interactifs ? [Couverture, Lacune] »
• « Le fallback est-il défini si les images ne chargent pas ? [Cas Limite, Lacune] »
• « “Affichage proéminent” est-il mesurable ? [Mesurabilité, Spec §FR-4] »

Qualité exigences API : api.md

Exemples :

• « Les formats d’erreur sont-ils spécifiés pour tous les échecs ? [Exhaustivité] »
• « Les limites de rate sont-elles quantifiées ? [Clarté] »
• « Les exigences d’authentification sont-elles cohérentes sur tous les endpoints ? [Cohérence] »
• « Les exigences de retry/timeout sont-elles définies pour les dépendances externes ? [Couverture, Lacune] »
• « La stratégie de versionning est-elle documentée ? [Lacune] »

Qualité exigences performance : performance.md

Exemples :

• « Les exigences de performance sont-elles quantifiées ? [Clarté] »
• « Des cibles de perf sont-elles définies pour les parcours critiques ? [Couverture] »
• « Les exigences de perf sous charge sont-elles spécifiées ? [Exhaustivité] »
• « Les exigences de perf sont-elles mesurables ? [Mesurabilité] »
• « Les exigences de dégradation sont-elles définies pour forte charge ? [Cas Limite, Lacune] »

Qualité exigences sécurité : securite.md

Exemples :

• « Les exigences d’authentification sont-elles spécifiées pour toutes les ressources protégées ? [Couverture] »
• « Les exigences de protection des données sont-elles définies pour les infos sensibles ? [Exhaustivité] »
• « Le threat model est-il documenté et aligné ? [Traçabilité] »
• « Les exigences sécurité sont-elles cohérentes avec la conformité ? [Cohérence] »
• « Les exigences de gestion d’incident sont-elles définies ? [Lacune, Exception] »

Anti-exemples : À NE PAS FAIRE

❌ MAUVAIS – testent l’implémentation, pas les exigences :

- [ ] CHK001 - Vérifier que la page affiche 3 cartes [Spec §FR-001]
- [ ] CHK002 - Tester les états hover sur desktop [Spec §FR-003]
- [ ] CHK003 - Confirmer que le logo clique va à l’accueil [Spec §FR-010]
- [ ] CHK004 - Vérifier que la section épisodes liés affiche 3-5 items [Spec §FR-005]

✅ BON – testent la qualité des exigences :

- [ ] CHK001 - Le nombre et la disposition des épisodes sont-ils explicitement spécifiés ? [Exhaustivité, Spec §FR-001]
- [ ] CHK002 - Les exigences d’état hover sont-elles cohérentes sur tous les éléments interactifs ? [Cohérence, Spec §FR-003]
- [ ] CHK003 - Les exigences de navigation sont-elles claires pour tous les éléments de marque cliquables ? [Clarté, Spec §FR-010]
- [ ] CHK004 - Les critères de sélection des épisodes liés sont-ils documentés ? [Lacune, Spec §FR-005]
- [ ] CHK005 - Les exigences d’état de chargement sont-elles définies pour les données asynchrones ? [Lacune]
- [ ] CHK006 - Les exigences de hiérarchie visuelle sont-elles mesurables ? [Mesurabilité, Spec §FR-001]

Différences clés :

• Mauvais : Teste si le système fonctionne
• Bon : Teste si les exigences sont bien rédigées
• Mauvais : Vérification du comportement
• Bon : Validation de la qualité des exigences
• Mauvais : « Fait-il X ? »
• Bon : « X est-il clairement spécifié ? »