pedro-oscar/shorts-ai

Revue bidimensionnelle de la différence entre HEAD et un point fixe fourni par l'utilisateur :

• Standards : le code respecte-t-il les normes de codage documentées du dépôt ?
• Spécifications : le code implémente-t-il fidèlement le ticket ou le cahier des charges d'origine ?

Les deux axes sont exécutés par des sous-agents parallèles afin d'éviter toute pollution croisée du contexte ; ensuite cette compétence agrège leurs résultats.

Le système de suivi des tickets devrait vous avoir été fourni. Si ce n'est pas le cas, demandez à l'utilisateur d'exécuter /setup-matt-pocock-skills.

Processus

1. Déterminer le point fixe

Quoi que l'utilisateur ait indiqué comme point fixe (un SHA de commit, un nom de branche, un tag, main, HEAD~5, etc.). S'il n'en a pas précisé, demandez-le.

Capturez la commande de diff une fois : git diff <point-fixe>...HEAD (trois points, pour que la comparaison se fasse via la base de fusion). Notez également la liste des commits avec git log <point-fixe>..HEAD --oneline.

Avant d'aller plus loin, vérifiez que le point fixe se résout bien (git rev-parse <point-fixe>) et que le diff n'est pas vide. Une référence invalide ou un diff vide doit échouer ici, pas au sein des deux sous-agents en parallèle.

2. Identifier la source de la spécification

Recherchez la spécification d'origine, dans cet ordre :

1. Références aux tickets dans les messages de commit (#123, Closes #45, GitLab !67, etc.), récupérées via le workflow du document du tracker.
2. Un chemin passé par l'utilisateur comme argument.
3. Un fichier de spécification sous docs/, specs/ ou .scratch/ correspondant au nom de branche ou à la fonctionnalité.
4. Si rien n'est trouvé, demandez à l'utilisateur où se trouve la spécification. S'il dit qu'il n'y en a pas, le sous-agent Spécifications passera et signalera « aucune spécification disponible ».

3. Identifier les sources de standards

Parcourez le dépôt pour trouver tous les fichiers qui documentent comment le code doit être écrit. Lorsque CODING_STANDARDS.md ou CONTRIBUTING.md existe, ils doivent figurer dans la liste.

En plus de ce que documente le dépôt, l'axe Standards comporte toujours la base de smells ci-dessous : un ensemble fixe de smells de code de Fowler (Refactoring, ch.3) qui s'applique même lorsqu'un dépôt ne documente rien. Deux règles le régissent :

• Le dépôt prime. Une norme documentée du dépôt l'emporte toujours ; là où elle approuve quelque chose que la base signalerait, supprimez le smell.
• Toujours un avis subjectif. Chaque smell est une heuristique nommée (« possible Envie de fonctionnalité »), jamais une violation absolue. Comme pour tout standard ici, ignorez ce qui est déjà appliqué par des outils.

Chaque smell décrit ce que c'est → comment corriger ; faites correspondre au diff :

• Nom mystérieux : une fonction, variable ou type dont le nom ne révèle pas ce qu'il fait ou contient. → renommez-le ; si aucun nom honnête ne vient, la conception est trouble.
• Code dupliqué : la même forme logique apparaît dans plusieurs blocs ou fichiers de la modification. → extrayez la forme partagée, appelez-la depuis les deux.
• Envie de fonctionnalité : une méthode qui fouille dans les données d'un autre objet plus que dans les siennes. → déplacez la méthode vers les données qu'elle envie.
• Groupes de données : les mêmes quelques champs ou paramètres voyagent constamment ensemble (un type qui cherche à naître). → regroupez-les dans un seul type, passez celui-ci.
• Obsession du primitif : un type primitif ou une chaîne qui se substitue à un concept du domaine méritant son propre type. → donnez au concept son propre petit type.
• Commutateurs répétés : le même switch/if en cascade sur le même type se répète dans la modification. → remplacez par du polymorphisme, ou une même carte que les deux sites partagent.
• Chirurgie par chevrotine : un changement logique unique force des modifications dispersées dans de nombreux fichiers du diff. → rassemblez ce qui change dans un seul module.
• Changement divergent : un fichier ou module est modifié pour plusieurs raisons sans rapport. → divisez pour que chaque module ne change que pour une seule raison.
• Généralité spéculative : abstraction, paramètres ou hooks ajoutés pour des besoins absents de la spécification. → supprimez-les ; ramenez à du code simple jusqu'à ce qu'un vrai besoin apparaisse.
• Chaînes de messages : longue navigation a.b().c().d() dont l'appelant ne devrait pas dépendre. → cachez le parcours derrière une méthode sur le premier objet.
• Homme du milieu : une classe ou fonction qui ne fait que déléguer essentiellement. → coupez-la, appelez directement la cible réelle.
• Refus de legs : une sous-classe ou un implémenteur qui ignore ou surcharge la plus grande partie de ce qu'il hérite. → abandonnez l'héritage, utilisez la composition.

4. Lancer les deux sous-agents en parallèle

Émettez les deux appels aux sous-agents ensemble, au premier plan, et agrégez les rapports qu'ils renvoient.

Consigne pour le sous-agent Standards :

• La commande de diff complète et la liste des commits.
• La liste des fichiers sources de standards trouvés à l'étape 3, ainsi que la base de smells de l'étape 3 collée en entier (le sous-agent n'y a pas accès autrement).
• La consigne : « Signalez, par fichier/bloc de code concerné, (a) tout endroit où le diff viole une norme documentée : citez la norme (fichier + règle) ; et (b) tout smell de base que vous repérez : nommez-le et citez le bloc de code. Distinguez les violations absolues des avis subjectifs : les entorses aux normes documentées peuvent être absolues, mais les smells de base sont toujours des avis subjectifs, et une norme documentée du dépôt prime sur la base. Ignorez tout ce qui est déjà appliqué par des outils. Moins de 400 mots. »

Consigne pour le sous-agent Spécifications :

• La commande de diff et la liste des commits.
• Le chemin ou le contenu récupéré de la spécification.
• La consigne : « Signalez : (a) les exigences demandées par la spécification qui sont absentes ou partielles ; (b) les comportements dans le diff qui n'étaient pas demandés (dépassement de périmètre) ; (c) les exigences qui semblent implémentées mais dont l'implémentation paraît erronée. Citez la ligne de la spécification pour chaque constatation. Moins de 400 mots. »

Si la spécification est absente, sautez le sous-agent Spécifications et mentionnez-le dans le rapport final.

5. Agréger

Présentez les deux rapports sous les titres ## Standards et ## Spécifications, textuellement ou légèrement nettoyés. Ne fusionnez pas ni ne reclassifiez les constatations, car les deux axes sont délibérément séparés (voir Pourquoi deux axes).

Terminez par un résumé d'une ligne : nombre total de constatations par axe, et le problème le plus grave au sein de chaque axe (le cas échéant). Ne choisissez pas un gagnant unique entre les axes : c'est le reclassement que la séparation vise à empêcher.

Pourquoi deux axes

Une modification peut réussir sur un axe et échouer sur l'autre :

• Du code qui respecte toutes les normes mais implémente la mauvaise chose → Standards réussi, Spécifications échoué.
• Du code qui fait exactement ce qu'a demandé le ticket mais enfreint les conventions du projet → Spécifications réussi, Standards échoué.

Les rapporter séparément empêche un axe de masquer l'autre.