Razsk/VideoStudio

Revue sur deux axes du diff entre HEAD et un point fixe fourni par l'utilisateur :

• Normes : le code respecte-t-il les standards de codage documentés du dépôt ?
• Spécifications : le code implémente-t-il fidèlement l'issue ou le cahier des charges d'origine ?

Les deux axes s'exécutent en tant que sous-agents parallèles afin qu'ils ne polluent pas leurs contextes respectifs, puis cette compétence agrège leurs conclusions.

Le tracker d'issues doit vous avoir été fourni. Sinon, demandez à l'utilisateur d'exécuter /setup-matt-pocock-skills.

Processus

1. Définir le point fixe

Quel que soit le point fixe mentionné par l'utilisateur (un SHA de commit, un nom de branche, un tag, main, HEAD~5, etc.). S'il n'en a pas spécifié, demandez-le.

Capturez la commande de diff : git diff <point-fixe>...HEAD (trois points, la comparaison se fait donc par rapport à la merge-base). Notez également la liste des commits via git log <point-fixe>..HEAD --oneline.

Avant d'aller plus loin, vérifiez que le point fixe existe (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 à l'intérieur des deux sous-agents parallèles.

2. Identifier la source des spécifications

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

1. Références aux issues 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 spec sous docs/, specs/ ou .scratch/ correspondant au nom de la branche ou de la fonctionnalité.
4. Si rien n'est trouvé, demandez à l'utilisateur où se trouve la spec. S'il indique qu'il n'y en a pas, le sous-agent Spécifications passera et rapportera « aucune spécification disponible ».

3. Identifier les sources de normes

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 le dépôt documente, l'axe Normes inclut toujours la baseline de smells ci-dessous : un ensemble fixe de code smells de Fowler (Refactoring, ch.3) qui s'applique même lorsqu'un dépôt ne documente rien. Deux règles la régissent :

• Le dépôt prime. Un standard documenté l'emporte toujours ; là où il approuve quelque chose que la baseline signalerait, supprimez le smell.
• Toujours un jugement. Chaque smell est une heuristique étiquetée (« possible Feature Envy »), jamais une violation dure. Comme pour tout standard ici, ignorez ce que les outils automatisent déjà.

Chaque smell se lit de la manière suivante : ce que c'est → comment le corriger ; mettez-le en correspondance avec le 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.
• Feature Envy : une méthode qui accède aux données d'un autre objet plus qu'aux siennes. → déplacez la méthode sur les données qu'elle envie.
• Data Clumps : les mêmes champs ou paramètres voyagent ensemble (un type qui demande à naître). → regroupez-les en un seul type, passez-le.
• Obsession primitive : une primitive ou une chaîne de caractères qui représente un concept du domaine qui mériterait son propre type. → donnez au concept son propre petit type.
• Switchs répétés : la même cascade switch/if sur le même type apparaît dans la modification. → remplacez par polymorphisme, ou par une carte partagée entre les deux sites.
• Chirurgie par chevrotine : un changement logique oblige à modifier des fichiers éparpillés dans toute la modification. → rassemblez ce qui change dans un même module.
• Changement divergent : un fichier ou module est modifié pour plusieurs raisons non liées. → divisez pour que chaque module change pour une seule raison.
• Généralité spéculative : abstraction, paramètres ou hooks ajoutés pour des besoins que la spécification n'a pas. → supprimez ; remplacez en ligne 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 seule méthode sur le premier objet.
• Homme du milieu : une classe ou fonction qui ne fait que déléguer. → coupez-la, appelez la cible réelle directement.
• Refus d'héritage : une sous-classe ou un implémenteur qui ignore ou redéfinit la plupart de ce qu'il hérite. → abandonnez l'héritage, utilisez la composition.

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

Lancez les deux appels de sous-agents ensemble, au premier plan, et agréguez les rapports qu'ils renvoient.

Invite du sous-agent Normes doit inclure :

• La commande de diff complète et la liste des commits.
• La liste des fichiers de normes que vous avez trouvés à l'étape 3, plus la baseline de smells de l'étape 3 recopiée en entier (le sous-agent n'y a pas accès autrement).
• Les consignes : « Rapportez, par fichier/bloc concerné, (a) chaque endroit où le diff viole un standard documenté : citez le standard (fichier + règle) ; et (b) tout smell de baseline que vous repérez : nommez-le et citez le bloc. Distinguez les violations dures des jugements de valeur : les violations de standards documentés peuvent être dures, mais les smells de baseline sont toujours des jugements de valeur, et un standard documenté du dépôt prime sur la baseline. Ignorez ce que les outils automatisent. Moins de 400 mots. »

Invite du sous-agent Spécifications doit inclure :

• La commande de diff et la liste des commits.
• Le chemin ou le contenu récupéré de la spécification.
• Les consignes : « Rapportez : (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 semble erronée. Citez la ligne de la spécification pour chaque constat. Moins de 400 mots. »

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

5. Agréger

Présentez les deux rapports sous les titres ## Normes et ## Spécifications, textuellement ou légèrement nettoyés. Ne fusionnez pas et ne réordonnez pas les conclusions, 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 conclusions par axe, et le pire problème dans chaque axe (s'il y en a). Ne choisissez pas un seul gagnant entre les axes : c'est le reclassement que la séparation vise à empêcher.

Pourquoi deux axes

Un changement peut réussir sur un axe et échouer sur l'autre :

• Du code qui respecte tous les standards mais implémente la mauvaise chose → Normes OK, Spécifications KO.
• Du code qui fait exactement ce qui a été demandé dans l'issue mais qui brise les conventions du projet → Spécifications OK, Normes KO.

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