proof-it-works

Prouve qu'un changement fonctionne réellement avant de le déclarer terminé ; pilote la surface réelle, capture des preuves reproductibles et échoue par défaut lorsque la preuve est absente.

Qu'est-ce que proof-it-works ?

Cette compétence agit comme un garde-fou strict : elle détermine si un travail peut être déclaré 'terminé' en exigeant des preuves reproductibles et automatisées, et non de simples affirmations. Elle ne s'applique qu'aux changements ayant une surface d'exécution (runtime) ou un livrable de conception. Le cœur de la compétence est une table d'assertions avec des conditions vérifiables, des dépendances, et un niveau de preuve minimum (artefact + contre-preuve). L'exécution suit un flux en 8 étapes : création d'un dossier `.proof/`, enregistrement des prédictions, pilotage de la vraie surface (ex: `curl`, navigateur, logs), capture des contre-preuves, écriture du rapport, et jugement final (PASS/FAIL/UNAVAILABLE). Les profils supportés sont DESIGN, FEATURE et DATAFLOW, chacun avec un jeu de preuves spécifique. La compétence est conçue pour être utilisée avec des agents comme Claude Code, Cursor, Codex, ou tout outil capable d'exécuter des commandes et de capturer des artefacts. Les plateformes supportées incluent tout environnement avec un terminal et un système de fichiers. Le fonctionnement repose sur un fichier `report.md` structuré, un système de versions (git ou hachage de fichiers), et une interdiction stricte des affirmations non vérifiées ('devrait marcher', 'a l'air correct').

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fan56/skills/tree/main/public/proof-it-works

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Proof It Works (Preuve de fonctionnement)

Cette compétence prend une seule décision : si le travail peut être considéré comme terminé. C'est une porte verrouillée, pas un conseil.

1. Loi fondamentale : Terminé = Prouvé

  • Une affirmation n'est pas une preuve. Seul un artefact reproductible qu'un second agent peut inspecter compte.
  • Vous ne pouvez pas dire « terminé », « corrigé », « passe » ou « livré » si l'un des éléments de la porte obligatoire de la section 6 est manquant.
  • « Devrait fonctionner », « a l'air correct », « théoriquement bien », « compile » ne sont pas des états de complétion.
  • Si la preuve est impossible, déclarez INDISPONIBLE/BLOQUÉ (section 7) — jamais PASS. Une dérogation écrite de l'utilisateur peut clore un FAIL en FAIL-WAIVED (section 7). Une dimension non testable par machine peut rester PENDING USER et se clore en PASS-BY-USER avec l'approbation de l'utilisateur (section 7). Ces trois — FAIL-WAIVED, PENDING USER, PASS-BY-USER — sont les seules sorties sans preuve machine ; aucune n'est PASS.
  • La preuve doit provenir de l'arbre de travail et du commit de changement nommé dans le rapport (section 3, Change ref) ; les artefacts obsolètes sont invalides.
  • Cette compétence ne contrôle que le travail ayant une surface d'exécution ou un livrable de conception. Pour ce travail, son ensemble de preuves minimal (une positive + une inverse) remplace, et ne s'empile pas, sur toute vérification plus légère. Tout travail sans surface d'exécution est hors du périmètre et cette compétence cède entièrement. Elle ne remplace pas une livraison que l'utilisateur a déjà approuvée comme minimale.

2. Niveaux de preuve

Trois niveaux dans un ordre strict : Affirmation (verbal ou raisonnement, aucune preuve) < Artefact (un vrai fichier artefact brut de cette tâche) < Artefact + cas inverse. La porte n'accepte que les deux derniers ; lequel est requis pour un élément est défini par les éléments de la porte du profil sélectionné, pas par une règle globale. Une Affirmation ne soutient jamais un PASS, et aucun élément ne peut être étiqueté au-dessus de ce qu'il est réellement.

3. Liaison / 任务绑定

  • En haut de report.md, citez textuellement la phrase de la demande de l'utilisateur qui définit l'objectif d'acceptation — une instruction telle que « changer X en Y et le prouver » compte ; elle n'a pas besoin de préciser que le travail est terminé. Étiquetez-la Objectif d'acceptation (texte exact de l'utilisateur). Seulement si la demande ne définit aucun objectif d'acceptation (elle ne dit jamais à quoi « terminé » doit ressembler), dites-le en une ligne, demandez à l'utilisateur d'en préciser un, et arrêtez-vous — il n'y a rien à contrôler. Le niveau de preuve Affirmation de la section 2 est un concept distinct et conserve son nom.
  • Change ref (en-tête du rapport) = le commit qui contient le changement testé — pas le commit qui ajoute ce rapport, et pas nécessairement HEAD. Sans git, utilisez sha256 des fichiers modifiés + liste des fichiers au lieu d'un hash. Après que le rapport est commité, HEAD avance ; c'est normal, et le vérificateur juge selon Change ref, pas HEAD.
  • Arbre de travail (en-tête du rapport) est un texte libre, pas une énumération à deux valeurs, ex. tracked clean; .proof/ untracked.
  • Déclarez les fichiers / fonctions / routes / composants que ce changement a touchés, tirés du diff actuel.
  • Chaque profil sélectionné doit avoir au moins un élément de preuve qui atterrit sur ce diff (exécute ou inspecte un chemin touché). Une preuve qui ne touche rien dans le diff = FAIL, même si tous les artefacts existent.
  • Une base de référence DESIGN doit avoir une source externe (section 6, proof-profiles.md) ; une base de référence introuvable est une Affirmation et échoue son élément de porte.

4. Sélectionner le(s) profil(s) de preuve

Choisissez le profil dont le test en une ligne correspond le mieux à la phrase d'objectif d'acceptation de l'utilisateur ; une tâche peut être DESIGN et FEATURE à la fois et doit alors satisfaire les deux. Si aucun profil ne correspond, dites-le en une ligne et arrêtez-vous — ne forcez pas un profil sur un changement sans surface d'exécution.

ProfilTest en une ligneDétail
DESIGNVous avez produit une spécification, mise en page, interaction, architecture ou contrat qui doit être montré comme implémenté, pas seulement proposé.references/proof-profiles.md
FEATUREVous avez modifié le comportement d'exécution et devez montrer qu'il fonctionne et que les entrées invalides sont rejetées.references/proof-profiles.md
DATAFLOWUne valeur traverse plusieurs étapes (entrée, transformation, persistance, sortie) et chaque saut doit être montré.references/proof-profiles.md
  • « Mon design a-t-il été implémenté ? » -> DESIGN. « Est-ce que ça marche ? » -> FEATURE. « Où sont passées les données / sont-elles persistées ? » -> DATAFLOW.

5. Flux d'exécution

Exécutez dans l'ordre. Ne sautez pas et ne réordonnez pas.

  1. Créez .proof/<nom-de-la-tâche>/ dans le dépôt (nom court en kebab-case). Un artefact n'est pas une preuve tant qu'il n'est pas un fichier ici.
  2. Écrivez 3 à 7 assertions d'acceptation dans report.md AVANT de collecter les preuves. Utilisez les 8 colonnes id | assertion | attendu | critère de réussite (vérifiable) | chemin modifié (fichier:fonction/route) | niveau requis | fichier preuve | dépend de. Interdisez « a l'air correct », « semble bien », « fonctionne comme prévu » ; utilisez des conditions vérifiables comme « HTTP 200 avec corps.champ X = Y », « largeur rect = 120px », « jeton invalide retourne 401 ».
    • attendu est le résultat prédit rempli AVANT toute preuve (ex. 401 + BAD_CREDENTIALS, largeur rect 240px) ; FEATURE/DATAFLOW doit le remplir sur chaque ligne, DESIGN peut écrire n/a. Enregistrez l'heure d'enregistrement dans l'en-tête du rapport comme Attendu enregistré (UTC) : <heure> — le pré-enregistrement est autodéclaré ; pas de hash ou de rituel sur disque.
    • attendu et critère de réussite sont deux expressions d'une même condition (prédiction vs vérification décidable). Ils ne doivent pas entrer en conflit ; une ligne en conflit doit être corrigée AVANT la collecte. Le statut est décidé uniquement par le critère de réussite par rapport à l'observé. Si observé satisfait le critère mais s'écarte de l'attendu, corrigez l'implémentation pour correspondre à l'attendu ou marquez l'assertion comme FAIL — ne réécrivez jamais l'attendu à la valeur observée (section 8).
    • Remplissez chemin modifié avec le fichier/fonction/route que l'assertion exerce ; écrivez n/a uniquement pour les lignes DESIGN qui n'exécutent aucun chemin de code. Au moins une assertion doit exécuter un chemin de code modifié dans ce diff et le nommer ; une assertion sur un chemin non touché ne lie pas. FEATURE/DATAFLOW doit avoir au moins une cellule chemin modifié non-n/a ; DESIGN peut utiliser n/a.
    • dépend de = identifiants de prérequis séparés par des virgules (vides si aucun), collectés dans l'ordre topologique. Un prérequis est considéré comme satisfait uniquement lorsque son statut est PASS ou PASS-BY-USER ; s'il est autre chose, la ligne en aval est NON EXÉCUTÉ (section 7) et tout NON EXÉCUTÉ fait échouer la porte. Le graphe dépend de doit être acyclique — un cycle est FAIL. Une ligne USER-JUDGMENT est une feuille : aucune ligne ne peut lister un identifiant USER-JUDGMENT dans dépend de.
  3. Pilotez la surface réelle avec des commandes réellement disponibles sur cette machine (ex. npm run dev pour démarrer, curl -i -X POST http://localhost:3000/login -d '{"utilisateur":"a","mot_de_passe":"wrong"}' pour API, un vrai navigateur + DevTools pour UI, tail -f pour les logs). Sauvegardez la sortie brute stdout/stderr/réponse/capture d'écran dans des fichiers numérotés (section 11). brut = la sortie complète telle que capturée, non résumée, extraite ou réordonnée ; la désensibilisation est une transformation unique appliquée au moment de la capture, donc elle ne casse pas « brut ». Remplacez les jetons / mots de passe / clés par *** dans le fichier sauvegardé, et enregistrez dans l'index des preuves et à côté de chaque bloc brut collé masqué : <nom du champ> (N occurrence(s)) plus le sha256 du fichier, afin qu'un relecteur puisse confirmer qu'il n'y a pas eu d'édition après capture. Ne désensibilisez jamais les codes de statut, les codes d'erreur ou toute valeur dont une assertion dépend. Tout espace réservé de style <启动命令> / <截图工具> laissé dans le rapport = FAIL ; remplacez-le par la commande exacte que vous avez exécutée.
  4. Cas inverse EN PREMIER. Définissez « un comportement modifié » comme chaque branche ajoutée ou modifiée dans le diff (un if/else, garde, validation, ou nouvelle route) ; listez-les tous dans le rapport et donnez à chacun une ligne dans la table d'assertions. Un cas limite est décidable : la même entrée est acceptée (ou se comporte différemment) sur l'implémentation d'avant le changement et rejetée (ou se comporte correctement) après le changement. Capturez la base de référence d'avant le changement en reconstruisant l'original — git stash, un worktree/checkout du commit d'avant le changement, ou une copie sauvegardée du fichier original — indiquez laquelle dans le rapport, exécutez la même commande dessus, et sauvegardez le résultat sous 00-pre-change.log (section 11). Cette « étape montrant qu'il échouerait avant le changement » est la base de référence du cas inverse, jamais une ligne d'assertion terminale-FAIL (section 9). Ensuite, pour chaque comportement modifié, exécutez un cas inverse (mauvaise entrée, permission manquante, valeur limite, précondition retirée) et enregistrez qu'il échoue de la manière attendue. Un mauvais cas qui échouait aussi avant le changement ne compte pas. Si le cas est accepté après le changement, le test n'est pas sur le vrai chemin ; corrigez et recollectez.
  5. Dataflow : avant la collecte, écrivez une ligne de transformation attendue dans report.md (forme d'entrée -> forme de sortie) et référencez-la à chaque saut. Capturez ensuite un échantillon réel par saut — entrée -> intermédiaire -> persistance -> sortie — avec le même identifiant de corrélation. Pour la persistance, collez la vraie requête de lecture et son retour brut ; réimprimer la valeur que vous avez écrite n'est pas un instantané. Capturez également la base de référence d'avant le changement pour le cas inverse selon l'étape 4 (00-pre-change.log) : elle doit montrer la valeur rejetée atteignant la sortie avant le changement.
  6. Les valeurs observées DESIGN doivent provenir de sources mécaniquement capturées (JSON de style calculé, getBoundingClientRect, textContent DOM, sortie CDP) sauvegardées dans des fichiers ; ne lisez pas les nombres sur une capture d'écran à l'œil. La base de référence doit donner une tolérance numérique (par côté <=2px, par canal <=8) ; son dépassement = FAIL. Une capture d'écran est uniquement une revue à l'œil humain, jamais la source numérique.
  7. Écrivez le rapport à partir de references/report-template.md ; copiez-le, n'inventez pas de format. Gardez uniquement les sections pertinentes pour le(s) profil(s) sélectionné(s) et supprimez complètement les sections inapplicables — les supprimer ne viole pas « copiez-le, n'inventez pas de format ».
  8. Jugement de la porte (section 6) : PASS uniquement si chaque élément requis existe au niveau requis, chaque assertion non-USER-JUDGMENT est PASS/PASS-BY-USER, au moins une assertion porte un verdict machine, et il n'y a pas de cycle dépend de ; sinon FAIL, INDISPONIBLE/BLOQUÉ, ou PENDING USER (section 7). Porte et Résultat utilisent la même énumération et doivent être identiques.

6. Porte dure (un seul élément manquant = FAIL)

« Terminé » exige que chaque case soit cochée. Un fichier manquant, un cas inverse manquant, un mock sur le vrai chemin, ou une preuve hors du diff est FAIL, indépendamment du récit.

  • Complétude (aucun élément inconnu) : le rapport indique le nombre total N d'assertions et liste un statut pour chacune des N assertions. Les seuls statuts légaux sont PASS | FAIL | NON EXÉCUTÉ | INDISPONIBLE | BLOQUÉ | USER-JUDGMENT | PASS-BY-USER. Un statut vide, un statut en dehors de cet ensemble, ou un nombre listé qui diffère de N est FAIL. PASS exige que chaque ligne non-USER-JUDGMENT soit PASS/PASS-BY-USER et qu'il n'y ait pas de FAIL/NON EXÉCUTÉ/INDISPONIBLE/BLOQUÉ.
  • USER-JUDGMENT n'est légal que pour une dimension SANS critère machine décidable. Si une machine peut juger la ligne, ou l'a jugée et la condition n'est pas remplie, son statut est ce verdict machine (PASS/FAIL) — jamais USER-JUDGMENT. Tout ce qu'une machine peut mesurer doit être sa propre ligne avec un verdict machine. L'assertion liée à ce diff (section 3) ne peut jamais être USER-JUDGMENT. Un rapport dont chaque assertion est USER-JUDGMENT a une condition PASS trivialement vraie et est FAIL : au moins une ligne doit porter un verdict machine. Testé par machine et ne satisfaisant pas le critère = FAIL, pas USER-JUDGMENT.
  • dépend de est un DAG : un cycle est FAIL. Un prérequis n'est satisfait que par PASS ou PASS-BY-USER ; aucune ligne ne peut dépendre d'une ligne USER-JUDGMENT, donc ces lignes sont des feuilles.
  • Global : la liaison tient (section 3), au moins une assertion lie au diff (section 5 étape 2) ; une ligne USER-JUDGMENT ne compte jamais comme PASS et ne bloque jamais le PASS d'un autre élément.
ProfilEnsemble de preuves minimal — tous requis
DESIGN(a) artefact de base avec une source externe : fichier de conception préexistant + commit de création, ou message textuel de l'utilisateur le contenant/l'approuvant, ou une table de spécifications placée comme fichier de base avant tout fichier d'implémentation, avec le bloc de métadonnées fixe (source_type, source_quote_or_path, captured_at_utc, sha256, baseline_method) rempli au moment de la mise en place ; l'ingénierie inverse des valeurs de l'implémentation dans la base est interdite ; (b) capture d'écran réelle du rendu au commit du changement ; (c) comparaison de la taille, couleur, espacement, texte, état pour chaque élément dans le périmètre (périmètre = chaque élément nommé dans le livrable de conception ; listez les éléments exclus et pourquoi), chaque ligne citant la valeur de base et une valeur observée mécaniquement sourcée, avec une tolérance numérique (<=2px par côté, <=8 par canal) déclarée dans la base ; (d) un élément inverse avec une valeur SUR la limite de tolérance (ex. 243px pour une spécification de 240px à +/-2), montrée absente/différente via la sortie brute ; (e) lacunes de spécification déclarées explicitement : Interprétation (lecture de base écrite avant l'implémentation, ajoute uniquement la position/le mappage, ne contredit jamais une valeur utilisateur), Exclu (aucune valeur de base n'existe, écrit textuellement), INDISPONIBLE (la valeur existe mais est non mesurable ici) — Exclu et INDISPONIBLE dans des sections séparées du rapport, aucune omission silencieuse ; (f) >=1 élément de preuve sur le diff.
FEATURE(a) un véritable transcript I/O piloté qui exécute un chemin de code modifié au commit du changement ; (b) un cas inverse par comportement modifié, son entrée invalide sur la limite décidable (acceptée/différente avant le changement, rejetée/correcte après), soutenu par une base de référence pré-changement 00-pre-change.log et une sortie brute montrant le rejet correct — les cas qui échouaient aussi avant le changement ne comptent pas ; (c) commande/action exacte et ref de changement enregistrés ; (d) chaque assertion mappée à un fichier avec un chemin modifié rempli, et >=1 assertion exécute le chemin modifié et nomme le fichier/fonction/route modifié ; (e) aucun mock/stub se substituant à la chaîne ; (f) >=1 élément de preuve sur le diff.
DATAFLOW(0) ligne de transformation attendue (forme d'entrée -> forme de sortie) écrite avant la collecte et référencée à chaque saut ; (a) un instantané par saut (entrée, intermédiaire, persistance, sortie) avec le même identifiant de corrélation ; (b) l'instantané de persistance colle la vraie requête de lecture + le retour brut du magasin, pas une réimpression de la valeur écrite ; (c) la base de référence pré-changement capture... (le texte est tronqué)

7. Résultats finaux

RésultatDéfinition
PASSToutes les assertions sont vérifiées. Le changement est prouvé.
FAILAu moins une assertion est fausse ou un artefact manque.
FAIL-WAIVEDL'utilisateur a renoncé par écrit à cette preuve.
INDISPONIBLEPreuve impossible car l'environnement, l'outil ou le droit d'accès manque.
BLOQUÉPreuve impossible car un prérequis non rempli bloque la collecte.
PENDING USERL'utilisateur doit approuver une dimension non testable par machine.
PASS-BY-USERL'utilisateur a approuvé après inspection manuelle.
NON EXÉCUTÉDépendance non satisfaite, l'assertion n'a pas été évaluée.

8. Règles strictes

  • attendu est une prédiction, pas une description. Ne mettez jamais à jour attendu avec la valeur observée ; corrigez le code ou marquez FAIL.
  • Un cycle dans dépend de est toujours FAIL.
  • Pas de mock sur le vrai chemin. Si un mock est nécessaire, déclarez-le comme BLOCKED.
  • Les artefacts doivent être dans .proof/<task-name>/. Tout fichier ailleurs n'est pas une preuve valide.
  • La sortie brute doit être complète et non modifiée (sauf désensibilisation déclarée avec le sha256 du fichier original).
  • Les captures d'écran sont pour la revue humaine, jamais comme source de mesure numérique.

9. Flux de travail recommandé

  1. L'utilisateur demande un changement (ex. « Ajoute la validation de l'email sur la page de login »).
  2. L'agent implémente le changement.
  3. L'agent crée .proof/<task-name>/.
  4. L'agent écrit les assertions dans report.md (prédictions AVANT preuve).
  5. L'agent exécute le cas inverse (pré-changement) et sauvegarde 00-pre-change.log.
  6. L'agent pilote la vraie surface, capture les résultats.
  7. L'agent écrit le rapport complet à partir du template.
  8. L'agent rend le jugement final.
  9. Le rapport est commité avec le changement.

10. Références

  • Template du rapport : references/report-template.md
  • Profils de preuve : references/proof-profiles.md
  • Exemples : examples/

Skills associés