lggarrison/agent-skills

Révision de PR

Ces règles s'appliquent à tout réviseur, humain ou agent (Copilot code review, Claude, et autres). La compétence sœur github couvre le côté de l'auteur : corriger les commentaires, répondre, et demander la prochaine révision. En cas de conflit entre les règles de révision propres au dépôt (AGENTS.md, CONTRIBUTING.md, un guide de style) et cette compétence, les règles du dépôt prévalent.

L'objectif d'une révision est de faire fusionner une PR correcte. Il ne s'agit pas de trouver quelque chose à dire. « Aucun problème trouvé » est un bon résultat.

Le seuil pour un constat

Ne postez un constat que si vous pouvez nommer une défaillance réaliste : un appelant réel, une entrée, ou une configuration, et le résultat erroné qu'elle produit. Si vous ne pouvez pas écrire ce scénario en une ou deux phrases, ne le postez pas.

Sévérité	Utilisation pour
Bloquant	Résultats erronés sur un chemin courant, failles de sécurité, perte de données, une construction ou des tests cassés, un changement cassant d'une API publique, ou une violation claire d'une règle écrite dans le dépôt
À corriger	Un vrai bug sur un chemin moins courant, un test manquant pour un nouveau comportement, ou une documentation ou des instructions qui conduiraient un lecteur à faire la mauvaise chose dans un cas normal
Nit	Nommage, formulation, ou petites corrections de clarté. Optionnel par définition. Au maximum trois par révision, et uniquement lors du premier tour

Ne postez pas :

• Des hypothèses nécessitant une entrée irréaliste, un environnement mal configuré, ou un attaquant qui a déjà l'accès que l'attaque lui donnerait.
• Du code défensif pour un cas qu'aucun appelant ne peut atteindre (« envisagez d'ajouter une vérification null »).
• Tout ce qu'un formateur, un linter ou un vérificateur de types présent dans le dépôt applique déjà.
• Une préférence personnelle entre deux approches raisonnables.
• Des préoccupations de performance sans chemin chaud ou mesure sous-jacente.
• Des demandes d'élargir la PR : fonctionnalités, refactorisations, ou nettoyages qu'elle n'avait pas pour but de faire.
• Des problèmes dans du code que la PR n'a pas modifiés, sauf si la PR les aggrave. Si quelque chose de sérieux existe de toute façon, mentionnez-le une fois, marqué préexistant, non bloquant.

Pour la documentation, les compétences et autres instructions, posez-vous une question : un lecteur suivant ce texte ferait-il la mauvaise chose dans un cas normal ? Les lacunes pour des configurations rares sont des nits au maximum. Ne demandez pas que chaque cas limite soit détaillé.

Converger au fil des tours

Une PR doit devenir plus silencieuse à chaque révision, pas plus bruyante.

• Tour 1 (première révision) : le diff complet, toutes les sévérités, les nits limités comme ci-dessus.
• Tour 2 et suivants (nouveaux commits depuis votre dernière révision) :
  • Révisez uniquement ce qui a changé depuis votre dernière révision, et vérifiez si vos constats précédents ont été corrigés.
  • Ne soulevez pas de nouveaux constats sur du code que vous avez déjà révisé et qui n'a pas changé. Si vous avez manqué quelque chose là-dedans, postez-le uniquement s'il est bloquant.
  • Pas de nits.
  • Ne relancez pas un constat auquel l'auteur a répondu avec une raison, sauf si vous avez de nouvelles preuves que la raison est erronée. Le désaccord seul n'est pas une nouvelle preuve.
• Si rien ne répond au seuil, dites-le en une ligne et arrêtez. Ne gonflez pas la révision.

Rédiger les constats

• Un problème par commentaire, ancré à la ligne concernée.
• Commencez par la sévérité : Bloquant :, À corriger :, ou Nit :.
• Ensuite, le scénario de défaillance en une ou deux phrases, puis la plus petite correction qui fonctionne.
• Au maximum cinq constats par révision, du plus sévère au moins sévère. S'il y en a plus, listez le reste brièvement dans le résumé. Fusionnez les doublons en un seul commentaire listant chaque endroit.
• Soyez précis et neutre. Pas d'éloges excessifs, pas de « vous pourriez envisager » atténué.

Le résumé

Terminez par un court résumé :

1. Un verdict : Approuver, Approuver avec nits, ou Modifications demandées (uniquement lorsqu'il y a au moins un constat bloquant).
2. Le nombre par sévérité.
3. Au tour 2 ou ultérieur : quels constats précédents sont maintenant corrigés, et lesquels sont encore ouverts.

Réviser en tant qu'agent dans une boucle

Lorsqu'un autre agent corrige vos constats et vous demande la prochaine révision :

• Traitez les réponses de l'auteur comme faisant partie de la révision. « Corrigé dans abc1234 » signifie vérifiez ce commit. « Je laisse tel quel, parce que… » signifie que le constat est clos sauf si la raison est erronée.
• Après trois tours, postez uniquement les constats bloquants, et dites que les éléments restants sont à la discrétion de l'auteur.