Castle-Solutions/landing

Revue sur deux axes du diff entre HEAD et un point de référence 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 problème ou le cahier des charges d'origine ?

Les deux axes sont exécutés en tant que sous-agents parallèles afin de ne pas polluer leurs contextes respectifs, puis cette compétence agrège leurs conclusions.

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

Processus

1. Définir le point de référence

Peu importe ce que l'utilisateur a indiqué comme point de référence (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-de-référence>...HEAD (trois points, pour que la comparaison se fasse par rapport à la base de fusion). Notez également la liste des commits via git log <point-de-référence>..HEAD --oneline.

Avant d'aller plus loin, vérifiez que le point de référence est correct (git rev-parse <point-de-référence>) et que le diff n'est pas vide. Une référence erronée ou un diff vide doit échouer ici, et non pas à l'intérieur des deux sous-agents parallèles.

2. Identifier la source du cahier des charges

Cherchez le cahier des charges 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 documenté dans le document de suivi.
2. Un chemin passé par l'utilisateur comme argument.
3. Un fichier de spécifications 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 le cahier des charges. 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 des normes

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

En plus de ce que le dépôt documente, l'axe Standards embarque toujours la grille de mauvaises odeurs ci-dessous : un ensemble fixe de « code smells » de Fowler (Refactoring, chapitre 3) qui s'applique même si le 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 ; si elle approuve quelque chose que la grille signalerait, supprimez l'odeur.
• Toujours un jugement subjectif. Chaque odeur est une heuristique étiquetée (« possible Feature Envy »), jamais une violation absolue. Comme pour toute norme ici, ignorez ce que les outils automatisés imposent déjà.

Chaque odeur indique ce qu'elle est → comment la corriger ; comparez-la 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 plus aux données d'un autre objet qu'aux siennes. → déplacez la méthode sur les données qu'elle convoite.
• Data Clumps : les mêmes quelques champs ou paramètres voyagent toujours ensemble (un type qui veut naître). → regroupez-les dans un seul type, passez celui-ci.
• Primitive Obsession : une primitive ou une chaîne utilisée à la place d'un concept métier qui mériterait son propre type. → donnez au concept son propre petit type.
• Repeated Switches : la même cascade de switch/if sur le même type se répète dans la modification. → remplacez par polymorphisme, ou une carte partagée par les deux sites.
• Shotgun Surgery : un changement logique unique oblige à éditer des fichiers dispersés dans le diff. → rassemblez les changements dans un seul module.
• Divergent Change : un fichier ou module est modifié pour plusieurs raisons sans rapport. → divisez pour que chaque module change pour une seule raison.
• Spéculation généralisée : abstraction, paramètres ou accroches ajoutés pour des besoins absents du cahier des charges. → supprimez-les ; intégrez jusqu'à ce qu'un vrai besoin apparaisse.
• Chaînes de messages : une longue navigation a.b().c().d() dont l'appelant ne devrait pas dépendre. → cachez la traversée derrière une méthode sur le premier objet.
• Middle Man : une classe ou fonction qui ne fait surtout que déléguer. → coupez-la, appelez directement la cible réelle.
• Refused Bequest : une sous-classe ou implémentation qui ignore ou surcharge la plupart de ce qu'elle hérite. → abandonnez l'héritage, utilisez la composition.

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

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

Invite du sous-agent Standards doit inclure :

• La commande de diff complète et la liste des commits.
• La liste des fichiers sources de normes trouvés à l'étape 3, ainsi que la grille de mauvaises odeurs de l'étape 3 copiée intégralement (le sous-agent n'y a pas accès autrement).
• La consigne : « Signalez, par fichier/bloc concerné, (a) chaque endroit où le diff viole une norme documentée : citez la norme (fichier + règle) ; et (b) toute odeur de base que vous repérez : nommez-la et citez le bloc. Distinguez les violations strictes des jugements subjectifs : les infractions aux normes documentées peuvent être strictes, mais les odeurs de la grille sont toujours subjectives, et une norme documentée du dépôt prime sur la grille. Ignorez ce que les outils automatisés imposent. 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é du cahier des charges.
• La consigne : « Signalez : (a) les exigences demandées par le cahier des charges qui sont absentes ou partielles ; (b) les comportements dans le diff qui n'étaient pas demandés (glissement de périmètre) ; (c) les exigences qui semblent implémentées mais où l'implémentation semble erronée. Citez la ligne du cahier des charges pour chaque constat. Moins de 400 mots. »

Si le cahier des charges est manquant, ignorez le sous-agent Spécifications et notez-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 et ne re-classez pas les résultats, 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 constats par axe, et le pire problème au sein de chaque axe (le cas échéant). 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 un axe et échouer sur l'autre :

• Du code qui suit toutes les normes mais implémente la mauvaise chose → Standards OK, Spécifications KO.
• Du code qui fait exactement ce que demande le ticket mais casse les conventions du projet → Spécifications OK, Standards KO.

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