PR tidy
Un balayage de cohérence d'une branche avant qu'elle ne devienne une pull request. Il examine ce que le diff a modifié, puis tout ce que le diff aurait dû modifier également.
Travaillez sur les propres modifications de la branche. Laissez intouchée la dette ailleurs dans le dépôt, sauf si le diff la rend erronée.
0. Périmètre
-
Lisez d'abord les instructions du dépôt :
AGENTS.md,CLAUDE.md,CONTRIBUTING*,README*, et toute documentation vers laquelle elles pointent. -
Trouvez la base et le diff :
base=$(git merge-base origin/main HEAD) # ou la branche par défaut du dépôt git log --oneline "$base"..HEAD git diff --stat "$base"...HEAD git diff --name-only "$base"...HEAD -
Vérifiez l'arbre de travail (
git status). Conservez les modifications non commitées. Si une modification que vous feriez entre en conflit avec elles, arrêtez-vous et demandez. -
Si vous êtes sur la branche par défaut sans rien à comparer, arrêtez-vous et dites-le.
1. Classifier le diff
Classez les modifications en :
- Nouveau : fichiers, commandes, fonctions, options, drapeaux, clés de configuration, variables d'environnement, scripts, compétences.
- Modifié : comportement, valeurs par défaut, API, signatures, règles, et conception : un guide ou une spécification qui dit désormais quelque chose de différent.
- Supprimé ou renommé : tout élément supprimé, renommé, déplacé ou remplacé.
- Infrastructure : build, CI, tests, outils.
À partir de cela, dressez la surface : chaque nom, chemin, drapeau, option, terme et règle auxquels un lecteur ou un autre fichier pourrait faire référence. Pour les changements de conception, listez également les expressions clés de l'ancienne idée, pas seulement son nom (un « contrôle par niveau » supprimé peut encore être décrit comme « un contrôle sous chaque niveau »).
2. Références obsolètes
Pour chaque élément supprimé, renommé ou redessiné, recherchez dans l'intégralité du dépôt, pas seulement dans les fichiers modifiés :
git grep -n -w "ancien_nom" # noms, chemins, drapeaux
git grep -n -i "phrase de l'ancien design"
Recherchez dans le code, les commentaires, les tests, la documentation, les README, les exemples, les notebooks, les templates, les fichiers de compétence, les diagrammes (Mermaid et ASCII) et la configuration. Chaque résultat est soit mis à jour, soit signalé avec une raison.
Ensuite, construisez une carte de couverture pour chaque élément nouveau ou modifié : où est-il documenté ?
Carte de couverture :
élément référence procédure exemple explication
--nouveau-drapeau README - - -
check_levels.py scripts/ - - -
Un élément sans couverture est une lacune ; signalez-la. N'écrivez pas de nouvelles pages de documentation complètes sans qu'on vous le demande.
3. Tests et documentation pour un nouveau comportement
Pour chaque comportement nouveau ou modifié :
- Un test l'exerce, au niveau qui le possède, et son chemin d'échec lorsque celui-ci a changé. Privilégiez le modèle de test existant du dépôt et le test le plus étroit qui détecterait la régression.
- La documentation le décrit partout où l'ancien comportement était décrit : référence, exemples et tout guide qui enseignait l'ancienne méthode.
- Signalez un test manquant uniquement lorsque vous pouvez nommer l'échec concret qu'il détecterait. Évitez les spéculations et la dette de couverture non touchée.
4. Les vérificateurs échouent bruyamment
Pour chaque vérificateur, linter, validateur ou script de vérification nouveau ou modifié :
- Intégré. Trouvez chaque point d'entrée utilisé par le dépôt :
.pre-commit-config.yaml,.github/workflows/*,Makefile,justfile,noxfile.py,tox.ini,pyproject.tomlou les scriptspackage.json, et tout validateur qui appelle d'autres vérifications. Confirmez que le vérificateur est appelé par au moins l'un d'eux. Sinon, intégrez-le de la même manière que ses homologues, ou signalez-le. - Échoue sur une mauvaise entrée. Exécutez-le sur une entrée délibérément cassée ; il doit se terminer avec un code de sortie non nul.
- Échoue sur rien. Exécutez-le sur une entrée vide ou manquante (aucun fichier, aucune correspondance, rien analysé) ; il doit se terminer avec un code de sortie non nul ou dire clairement qu'il n'a rien vérifié, jamais réussir silencieusement.
- A un test couvrant les points 2 et 3.
Pour garantir cela plus tard, ajoutez un test d'intégration tel que references/test_checkers_wired.py.
5. Nombres, versions et exemples
Listez chaque nombre, version, date, URL, citation, commande et exemple de code dans les fichiers touchés par le diff ou la documentation qui les décrit. Pour chacun :
- Nommez sa source : le code ou la commande qui le produit, une valeur de configuration, un ensemble de données, ou un article avec sa version exacte (arXiv
v3, un DOI). - Revérifiez-le : réexécutez la commande ou relisez la source. Corrigez-le, ou signalez-le si vous ne pouvez pas vérifier.
- Conservez sa condition : l'ensemble de données, le paramètre, la machine ou le moment pour lequel un nombre est valide (« N points en T heures sur machine M », pas « N points »).
- Ancrez les sources externes sur une version.
- Les nombres qui continueront à changer sont mieux générés à partir du code (par exemple avec
cog, vérifié parcog --check) que tapés à la main ; suggérez-le.
6. Informations personnelles et identifiants
Vérifiez tout ce que la branche ajoute, et tout fichier non suivi sur le point d'être ajouté, avant qu'il ne quitte la machine. Ceci est bloquant : rien ci-dessous n'est « réglé » en passant à autre chose.
git diff "$base"...HEAD # commité sur la branche
git diff; git diff --cached # pas encore commité
git status --short # fichiers non suivis qui pourraient être ajoutés
Recherchez :
- Identifiants : clés API, jetons, mots de passe, chaînes de connexion avec mots de passe, clés privées (
-----BEGIN … PRIVATE KEY-----), secrets cloud et CI, cookies de session. - Fichiers qui les contiennent :
.env*,*.pem,*.key,id_rsa*,credentials*,secrets*,*.p12, JSON de compte de service,.npmrcou.pypircavec jetons, fichiers de paramètres locaux. - Informations personnelles : adresses e-mail, numéros de téléphone, adresses postales ou domiciliaires, vrais noms dans les exemples ou données de test, numéros de compte ou d'identification, et données identifiantes concernant d'autres personnes.
- Détails de la machine : chemins absolus du répertoire personnel (
/Users/<nom>,/home/<nom>,C:\Users\<nom>), noms d'hôte internes, adresses IP privées, noms d'utilisateur dans les journaux ou sorties de notebook. - Endroits cachés : sorties et métadonnées de notebook, journaux, captures d'écran, fixtures, rapports générés, messages de commit, et l'historique complet de la branche, pas seulement son état final.
Exécutez un scanner si le dépôt en possède un (gitleaks, detect-secrets, pre-commit run --all-files), et lisez également le diff vous-même ; les scanners manquent les données personnelles.
Lorsque vous trouvez quelque chose :
- Ne répétez jamais la valeur dans le rapport ou un message de commit. Nommez le fichier, la ligne et le type d'élément (
clé AWS,adresse e-mail). - Pas encore commité : supprimez-le, déplacez-le vers un fichier ignoré ou une variable d'environnement, et ajoutez le motif à
.gitignores'il s'agit d'un fichier. - Déjà commité sur la branche : arrêtez-vous et informez l'utilisateur. Un identifiant qui a déjà été commité doit être révoqué et remplacé, même après réécriture de l'historique, car il a peut-être déjà été copié. Ne réécrivez pas un historique partagé sans l'utilisateur.
- Informations personnelles que l'utilisateur y a mises intentionnellement (son propre nom public dans une licence, par exemple) : demandez, ne supprimez pas.
7. Corriger ou signaler
Modifiez minimalement, dans la voix, la structure et la terminologie du fichier. Lisez un fichier entièrement avant de le modifier.
Corrigez sans demander :
- les corrections factuelles qui découlent directement du diff ;
- les noms, chemins, comptages, versions et références croisées obsolètes ;
- l'ajout d'un nouvel élément à un tableau ou une liste existante ;
- l'intégration d'un vérificateur là où ses homologues montrent le motif.
Signalez, ou demandez avant de modifier :
- le texte narratif, de conception ou de politique, et tout ce qui contredit l'intention apparente de la branche ;
- les suppressions et les réécritures importantes ;
- les modifications sensibles à la sécurité ;
- les entrées
CHANGELOGet les incrémentations de version ; - les fichiers appartenant à une autre personne ou équipe ;
- les nouveaux tests nécessitant une décision de conception.
Ne jamais : réécrire ou régénérer des entrées de changelog existantes, incrémenter une version silencieusement, modifier manuellement des fichiers générés (utilisez leur générateur), ou coller des secrets ou des identifiants réels.
8. Vérifier avec des preuves
Aucune affirmation sans preuve fraîche de cette session, après la dernière modification pertinente :
- Nommez la commande qui prouve l'affirmation.
- Exécutez-la en entier.
- Lisez l'intégralité de la sortie et le code de sortie.
- Énoncez le résultat avec cette preuve, ou énoncez le statut réel.
Exécutez ce que le dépôt possède déjà : ses tests, ses linters, pre-commit run --all-files, la construction de la documentation et les vérifications de liens. Un outil qui n'est pas installé ou un service qui est indisponible est une lacune de vérification, signalée comme telle, jamais une réussite. « Devrait réussir » et un « fait » d'un agent ne sont pas des preuves.
9. Rapport
Périmètre : <base>..HEAD, N fichiers, M commits
Bloquant
- chemin:ligne — type d'identifiant ou d'information personnelle (valeur non affichée), et ce qui est nécessaire
Modifié
- chemin:ligne — ce qui a changé, et pourquoi le diff l'exigeait
Signalé (non corrigé)
- chemin:ligne — le problème, pourquoi il n'a pas été corrigé, la correction suggérée
Lacunes de couverture
- élément — où il devrait être documenté ou testé
Vérifié
- `commande` → résultat (code de sortie)
Non vérifié
- quoi, et pourquoi (outil manquant, service externe, nécessite une décision)
La couche mécanique
La plupart des sections 2 à 6 nécessitent du jugement, mais certaines peuvent être exécutées à chaque commit. Pour un dépôt qui n'en a pas, proposez la configuration de démarrage dans references/pre-commit-config.yaml : hygiène des fichiers, ruff, codespell, détection de clés privées et de secrets (gitleaks), et pytest avec diff-cover lors du push. Les vérifications de liens lychee et la CI basée sur les chemins sont mieux placées dans un workflow que dans un crochet de commit.
Crédits
Adapté, avec modifications, de compétences sous licence MIT : docs-sync et review-test-coverage par Jakub Merta (jMerta/codex-skills) ; la classification du diff, la carte de couverture et les règles de correction ou signalement de document-release par Garry Tan (garrytan/gstack) ; et la règle de preuve de verification-before-completion par Jesse Vincent (obra/superpowers). Des idées, pas du texte, provenant des agents pr-review-toolkit d'Anthropic (anthropics/claude-plugins-official). Licences : THIRD_PARTY_NOTICES.md.