verification-before-completion

Aperçu

Qu’est-ce que la skill verification-before-completion ?

La skill verification-before-completion définit une règle de workflow stricte pour les développeurs et les agents : ne jamais dire qu’un travail est terminé, que les tests passent, ou qu’un bug est corrigé sans avoir juste avant exécuté la commande de vérification concernée et vérifié sa sortie. Son principe central est :

Toujours des preuves avant les affirmations.

Concrètement, cela signifie qu’avant d’écrire « les tests passent », « le build est vert » ou « le bug est corrigé », vous devez :

• Identifier la commande qui prouve votre affirmation
• L’exécuter à nouveau (sans vous reposer sur d’anciens résultats ni sur des suppositions)
• Lire la sortie et le code de retour
• Ne formuler votre conclusion qu’après, sur la base de ces preuves

À qui s’adresse cette skill ?

Utilisez la skill verification-before-completion si vous :

• Travaillez sur des bases de code où des tests en échec, des builds cassés ou des correctifs non vérifiés passent trop souvent au travers
• Vous appuyez sur des agents ou des outils automatisés susceptibles d’annoncer un succès sans lancer réellement les vérifications
• Souhaitez une pratique de test et de vérification disciplinée, reproductible, intégrée à votre workflow de développement

Elle est particulièrement pertinente pour :

• L’automatisation des tests : s’assurer que les suites de tests sont réellement exécutées et correctement interprétées
• L’automatisation de workflow : imposer que les étapes de « completion » incluent toujours des commandes de vérification
• Les équipes pratiquant la revue de code, l’intégration continue et la livraison continue, qui veulent moins de mauvaises surprises après un statut « done ».

Quel problème verification-before-completion résout-il ?

Sans garde-fou, il est facile de :

• Supposer que les tests vont passer parce que le changement est « petit »
• Déclarer qu’un bug est corrigé après avoir édité du code, sans rejouer le scénario qui échouait
• Se reposer sur un build précédent réussi au lieu de reconstruire après des modifications

La skill verification-before-completion définit ce que le dépôt appelle une Iron Law :

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

En adoptant cette skill, vous transformez cette loi en règle de workflow concrète pour vous-même, votre équipe ou vos agents. Cela réduit :

• Les faux statuts « vert » dans les pull requests
• Les régressions cachées qui n’ont jamais été testées
• Les malentendus entre développeurs, reviewers et automatisation

Quand cette skill est-elle adaptée ?

Choisissez verification-before-completion lorsque :

• Vous disposez déjà de commandes de test, de lint ou de build et vous voulez être sûr qu’elles sont toujours exécutées
• Vous utilisez des agents ou des scripts pour vous aider dans les tâches de développement et avez besoin qu’ils soient stricts sur la vérification
• Vous privilégiez la fiabilité des statuts rapportés plutôt que de gagner quelques secondes sur votre workflow

Elle sera moins utile si :

• Votre projet ne possède pas encore de vérifications automatiques significatives (pas de tests, pas de lints, pas de commandes de build)
• Vous faites du travail exploratoire pour lequel vous n’êtes pas encore prêt à affirmer que « ça passe » ou que « c’est corrigé »
• Vous utilisez le dépôt uniquement comme référence conceptuelle, et non comme workflow à faire respecter

Dans ces cas, vous pouvez tout de même utiliser la skill comme guide pour concevoir vos futurs tests et vérifications.

Comment l’utiliser

Installation et configuration

Pour installer la skill verification-before-completion via npx :

npx skills add https://github.com/obra/superpowers --skill verification-before-completion

Après l’installation :

1. Ouvrez le répertoire skills/verification-before-completion dans le dépôt obra/superpowers.
2. Commencez par SKILL.md pour voir la règle complète et sa justification.
3. Intégrez la règle dans la documentation de votre projet, la configuration de vos agents ou vos guides de développement.

Vous n’avez pas besoin de copier exactement la structure du dépôt. Utilisez-la plutôt comme référence pour décrire et faire respecter la règle dans votre environnement.

Workflow central : la Gate Function

La skill définit une Gate Function qui doit être exécutée avant toute affirmation de completion. Dans votre travail quotidien, appliquez-la ainsi :

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

Si vous sautez une étape, vous ne suivez plus la logique de verification-before-completion.

Exemples de commandes typiques :

• Tests : npm test, pytest, go test ./..., mvn test
• Lint : eslint ., flake8, golangci-lint run
• Build : npm run build, make, cargo build --release
• Vérification ciblée d’un bug : le script, test ou contrôle manuel spécifique qui reproduit le problème d’origine

Exemple : utiliser la skill dans un workflow de développement

Scénario : vous avez mis à jour du code et souhaitez affirmer « Tous les tests passent ».

Appliquez verification-before-completion :

1. IDENTIFY la commande : par exemple pytest.
2. RUN la commande après vos changements :

   pytest
   

3. READ la sortie et vérifiez un code de retour 0.
4. VERIFY :
   • Si des tests échouent, ne revendiquez pas le succès. Indiquez plutôt quelque chose comme : « Les tests échouent : 3 tests en échec dans test_user_flow.py. Voir la sortie pytest. »
   • Si les tests passent, vous pouvez écrire : « Tous les tests passent (pytest, exit code 0). »
5. ONLY THEN marquez la tâche comme terminée, poussez vos commits ou ouvrez une pull request.

Vous pouvez appliquer ce schéma à toute affirmation de statut : builds, linters, formatage ou correction de bugs.

Intégration avec des agents et l’automatisation

Si vous utilisez des agents ou des scripts pour assister le développement :

• Configurez-les pour que toute affirmation concernant des tests, builds ou correctifs soit précédée par l’exécution d’une commande concrète et un résumé de la sortie.
• Exigez que l’agent référence la commande exécutée et son résultat, par exemple :
  • « Ran npm test: exit code 0, 0 failing tests. »
  • « Ran npm run build: exit code 1, build failed. Not claiming completion. »

En revue ou dans les pipelines CI, vous pouvez considérer qu’une affirmation sans preuve est incomplète au regard de verification-before-completion.

Adapter la skill à vos outils et à votre environnement

Le dépôt ne prescrit aucun langage ni framework spécifique. Pour adapter la skill :

• Associez à chaque affirmation courante une commande unique et non ambiguë qui la prouve.
• Documentez ces correspondances dans votre propre dépôt (par exemple dans CONTRIBUTING.md ou WORKFLOW.md).
• Incitez ou imposez aux contributeurs et aux agents de toujours :
  • Exécuter ces commandes avant de dire « done »
  • Coller ou résumer les sorties pertinentes quand ils formulent leurs affirmations

Exemples de correspondances affirmation → commande :

• « Backend tests pass » → pytest backend/tests
• « Frontend builds successfully » → npm run build dans frontend/
• « Go module is clean » → go test ./... et golangci-lint run

FAQ

Quelle est la règle principale de verification-before-completion ?

La règle principale est l’« Iron Law » :

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Si vous n’avez pas exécuté à l’instant la commande de vérification pertinente et inspecté sa sortie, vous ne pouvez pas honnêtement revendiquer un succès.

Qu’est-ce qui compte comme « verification evidence » ?

Une preuve de vérification, c’est la sortie fraîche d’une commande qui teste directement votre affirmation, par exemple :

• Une exécution de suite de tests montrant 0 échec et un code de retour 0
• Un run de linter sans erreurs et avec un statut de sortie réussi
• Une commande de build qui se termine sans erreur (exit 0)
• Un script de reproduction ou un test pour un bug qui passe désormais

D’anciens résultats, des suppositions ou des « ça devrait marcher » ne comptent pas comme preuves dans le cadre de cette skill.

Puis-je me fier à des tests passés si rien n’a changé ?

Avec verification-before-completion, par défaut non. La skill met l’accent sur une vérification fraîche avant chaque nouvelle affirmation de completion. Si vous voulez vous reposer sur des exécutions précédentes, vous devez être explicite et prudent sur les conditions qui rendent cela acceptable, en sachant que cela affaiblit la garantie.

Cette skill nécessite-t-elle des outils ou langages spécifiques ?

Non. La skill verification-before-completion est agnostique en matière d’outils. Elle fonctionne avec toute stack pour laquelle vous pouvez :

• Définir des commandes qui vérifient le comportement (tests, linters, builds, scripts)
• Les exécuter à la demande
• Interpréter leurs codes de retour et leurs sorties

Il vous suffit de renseigner les commandes propres à votre projet et de suivre les étapes de la Gate Function.

En quoi est-ce différent du fait de « lancer les tests » de temps en temps ?

La différence tient à la discipline et la constance :

• Vous exécutez la commande de vérification à chaque fois avant d’affirmer une completion.
• Vous lisez toujours la sortie au lieu de supposer que tout est vert.
• Vous traitez toute affirmation sans preuve comme invalide.

Ainsi, les exécutions de tests et de builds deviennent un véritable garde-barrière, pas une option facultative.

verification-before-completion convient-il aux tests manuels ?

Oui, tant que vous pouvez définir une procédure claire qui joue le rôle de « commande » pour l’affirmation. Par exemple :

• Documenter un test manuel pas-à-pas qui reproduit un bug
• Le lancer après votre modification
• Enregistrer le résultat comme preuve

Cependant, la skill donne ses meilleurs résultats lorsque la vérification est automatisée via des scripts ou frameworks de test, afin que les résultats soient reproductibles et faciles à relancer.

Où trouver la définition originale de la skill ?

La description de référence de la skill verification-before-completion se trouve dans le fichier SKILL.md du dépôt obrа/superpowers :

• Repository : https://github.com/obra/superpowers
• Skill file : skills/verification-before-completion/SKILL.md

Référez-vous à ce fichier pour le texte exact du principe, de l’Iron Law, de la Gate Function, ainsi que des exemples de défaillances courantes à éviter.