jakubkrehel/interface-review

Révision de modification

Cette compétence révise une modification plutôt qu'un écran. Elle résout le périmètre, étend les fichiers modifiés aux surfaces qu'ils affectent, lit les deux côtés du diff et classe chaque constat.

Le périmètre lui appartient. Les règles de domaine appartiennent aux compétences better-*. La sévérité, la consolidation, la couverture, la limite et le verdict appartiennent à better-interface, à qui cette compétence remet la révision.

L'exactitude, les tests, la sécurité et les performances appartiennent à la révision de code générale du projet. Mentionnez le problème une fois et passez à autre chose.

La modification, pas le code

L'auteur demande : « Est-ce que j'ai empiré les choses ? ». Signalez ce que la modification a causé et restez plutôt silencieux sur ce qu'elle a simplement touché. Trois constats préexistants sont une courtoisie ; trente sont une révision différente et que personne n'a demandée.

Lisez la modification avant de vous faire une opinion. L'intention déclarée décide ce qui est incomplet, et un diff survolé produit des constats sur du code que le prochain fragment (hunk) a déjà corrigé.

Principes fondamentaux

1. Résolvez d'abord le périmètre de la modification

L'invocation entière est la cible, donc /interface-review pr 482 révise la pull request 482. La résolution du périmètre contient les cibles acceptées et comment chacune se résout.

Sans cible fournie, résolvez dans cet ordre et arrêtez-vous à la première correspondance :

1. HEAD est en avance sur git merge-base origin/<branche-par-défaut> HEAD : cet intervalle plus toutes les modifications non commitées, avec le nombre de commits et le nombre de fichiers non commités indiqués séparément.
2. L'arbre de travail est sale : les modifications non commitées.
3. Ni l'un ni l'autre : il n'y a aucune modification à réviser. Arrêtez-vous et demandez, selon Sans modification, demandez plutôt que d'en inventer une.

L'ordre est important. Vérifiez d'abord l'arbre de travail et une simple modification de formatage éclipse une branche de douze commits, le rapport prétendant toujours une couverture complète.

Excluez les fichiers de verrouillage, les instantanés (snapshots), la sortie générée, le code externalisé (vendored) et les binaires, et nommez ce que vous avez exclu. Un périmètre vide après les exclusions arrive au même endroit par un chemin différent.

2. Sans modification, demandez plutôt que d'en inventer une

Un arbre propre sans rien en avance sur la base de fusion (merge base) signifie que l'utilisateur a demandé une révision pour une modification qui n'existe pas. Ne revenez jamais à HEAD~1..HEAD par vous-même. Le dernier commit est celui qui est arrivé, souvent une fusion, souvent le travail de quelqu'un d'autre, et un rapport à son sujet est impossible à distinguer d'un rapport sur ce que l'utilisateur voulait.

Indiquez les faits du dépôt que vous avez trouvés, puis proposez les options et attendez. Rien à réviser contient les faits à rassembler :

• Le dernier commit HEAD~1..HEAD, nommé par son SHA court et son sujet, afin que l'utilisateur voie ce qu'il obtiendrait avant de le choisir.
• Une cible qu'ils nomment : pr <n>, une branche, une référence (ref) ou un intervalle, résolu selon Résolvez d'abord le périmètre de la modification.
• Un audit d'interface du dépôt entier, qui n'est pas une révision de modification. Transmettez-le à better-interface en tant que révision au niveau du dépôt, sans le bloc de périmètre, les statuts ou la section préexistante de cette compétence. Sans modification, chaque constat est préexistant et la classification ne dit rien.

Vérifiez s'il existe une pull request ouverte sur la branche actuelle avant de demander, et proposez-la en premier. Une branche dont les commits ont déjà été fusionnés se résout en aucune modification, alors que sa pull request est exactement ce que l'utilisateur voulait.

Lorsque le périmètre s'est vidé après les exclusions, dites quels fichiers ont été exclus et demandez de la même manière. Ne rapportez jamais une révision de rien comme Approuver.

3. Un diff n'est pas une surface

Un fichier modifié est une preuve, pas le sujet de la révision. Son rayon d'explosion (blast radius) est l'ensemble des surfaces dans lesquelles il est restitué ; révisez ces surfaces.

Étendez le rayon d'explosion d'un saut par défaut : les importateurs et appelants directs. Étendez un deuxième saut uniquement pour les jetons de conception (design tokens), les valeurs de thème et les primitives partagées, où une ligne atteint l'ensemble du produit.

Révisez au maximum cinq consommateurs, triés selon la règle dans Résolution du périmètre, puis indiquez combien vous n'avez pas étendus. Un balayage sans limite ne peut pas soutenir la couverture qu'il prétend, et une limite non déclarée ressemble à de l'exhaustivité.

4. Lisez les lignes supprimées

Les régressions sont invisibles dans l'état post-modification. Lisez le côté - de chaque fragment (hunk) par rapport aux Signaux supprimés.

Un signal est une piste, pas un constat. Une suppression n'est une régression que lorsque rien dans la modification ne la remplace, et la compétence de domaine possède ce jugement. Acheminez chaque suppression non remplacée à son propriétaire, rapportez uniquement ce que cette compétence confirme et statuez-la Régression. Cela indique à l'auteur qu'il a cassé quelque chose qui fonctionnait plutôt que de faire une nouvelle erreur.

5. Classez chaque constat

Donnez à chaque constat un statut :

• Introduit : la modification l'a créé.
• Régression : la modification a affaibli quelque chose de correct auparavant.
• Préexistant : présent dans le code touché mais pas causé par cette modification.

Statut basé sur ce que le diff a touché, pas sur le fichier dans lequel il se trouve : une ligne que la modification n'a jamais touchée est Préexistant, même à trois lignes d'un fragment. Confirmez par rapport à la référence de base quand c'est important :

git blame -L <ligne>,<ligne> "$BASE" -- chemin/vers/fichier

Transmettez chaque constat avec son statut attaché et laissez better-interface appliquer ses règles de limite et de verdict.

6. Tenez la modification à son intention déclarée

Lisez le titre et le corps de la pull request, le problème lié et les messages de commit, puis révisez si l'interface délivre ce qu'ils prétendent.

C'est ce qui révèle la modification incomplète. Une révision de surface ne peut pas le voir, car elle inspecte les états qui sont présents, et ici le point concerne ceux qui sont absents :

• Une nouvelle variante, taille ou thème appliqué à certains états mais pas à tous : survol, focus, actif, désactivé, chargement, sélectionné.
• Une nouvelle chaîne destinée à l'utilisateur sans entrée dans le catalogue de traduction que le projet maintient.
• Un nouveau composant sans état vide, chargement, erreur, désactivé ou de largeur étroite.
• Un contrôle ajouté à une surface mais pas aux surfaces sœurs qui portent déjà ses pairs.

Ne signalez pas l'élargissement du périmètre (scope creep). Si une modification en fait trop est une question de processus, pas d'interface.

7. Remettez la révision à better-interface

Remettez à better-interface le bloc de périmètre, les surfaces affectées et un statut pour chaque constat. Il achemine vers les compétences de domaine, applique la sévérité, consolide, applique la limite et émet le verdict.

Si better-interface n'est pas disponible, rapportez le périmètre résolu et l'inventaire des fichiers, nommez-le comme la compétence manquante et arrêtez-vous. N'inventez pas d'échelle de sévérité, de limite ou de verdict.

8. Ne modifiez jamais l'arbre de travail

Une révision de modification est en lecture seule, y compris le checkout (extraction). Récupérez (fetch) les références de pull request ; ne les extrayez (checkout) jamais. git fetch écrit uniquement dans .git et est autorisé. gh pr checkout, git checkout, git switch et git stash réécrivent les fichiers que l'auteur a ouverts. Ils échouent contre les modifications locales ou les suppriment, donc ils ne sont jamais autorisés.

La vérification rendue est facultative. Marquez les affirmations visuelles et d'exécution comme Non vérifié sauf si le projet expose un aperçu peu coûteux ou si l'utilisateur demande une révision rendue. Lorsqu'ils le font, utilisez un arbre de travail isolé (git worktree add /tmp/review-<n> refs/remotes/pr/<n>) et supprimez-le une fois terminé.

Avant de terminer

Erreur	Correction
Une seule modification isolée révisée au lieu de la branche	Vérifiez merge-base avant l'arbre de travail, et rapportez les deux nombres
Le dernier commit révisé parce qu'il n'y avait pas de modification	Indiquez les faits et proposez le dernier commit, une cible nommée ou un audit du dépôt
Fragments (hunks) révisés sans leurs consommateurs	Étendez d'un saut, deux pour les jetons et primitives, et nommez ce que vous avez sauté
Seul le côté + du diff a été lu	Cherchez dans le côté - les signaux d'accessibilité, de focus, de mouvement et de texte supprimés
Un remplacement équivalent rapporté comme une régression	Acheminez la suppression à son propriétaire ; rapportez uniquement ce qu'il confirme
Une suppression rapportée comme une nouvelle erreur	Statuez-la Régression afin que l'auteur sache que ça fonctionnait avant
Une ligne près d'un fragment statuée Introduit	Statuez en fonction de ce que le diff a touché, confirmé avec git blame par rapport à la référence de base
Une pull request extraite (checkout) pour la réviser	Récupérez (fetch) la référence (ref) et révisez-la sur place
Numéros de lignes cités qui n'existent pas sur la ref révisée	Citez par rapport à la ref de tête nommée dans le bloc de périmètre
L'échelle de sévérité ou la limite de constats répétée ici	Déléguez à better-interface
Constats d'exactitude, de test ou de sécurité dans le rapport	Mentionnez le problème une fois, pointez vers la révision de code du projet et abandonnez-le

Format de sortie de la révision

Ouvrez avec le bloc de périmètre :

Champ	Valeur
Cible	branche, en-cours, staging, pr 482, ou l'intervalle tel que saisi
Ref de base	origin/main à a1b2c3d
Ref de tête	refs/remotes/pr/482 à e4f5g6h
Commits	7 commités, 2 fichiers non commités
Fichiers dans le périmètre	12 après exclusions
Exclus	pnpm-lock.yaml, src/__snapshots__/ : fichier de verrouillage et instantanés
Surfaces étendues	CheckoutPage, SettingsPanel ; 3 autres consommateurs de Button non étendus

Le tableau de couverture le suit inchangé. Un domaine sans preuve dans le périmètre de modification est Non révisé : aucune preuve dans le périmètre de modification, ce qui est une déclaration de couverture plutôt qu'une lacune.

Ensuite, les constats, avec une colonne Statut selon Classez chaque constat :

Sévérité	Domaine	Statut	Emplacement	Avant	Après	Raison
ÉLEVÉE	Accessibilité	Régression	src/Dialog.tsx:42	aria-label="Close" supprimé dans cette modification	Restaurez aria-label="Close" sur le contrôle à icône uniquement	Le contrôle de fermeture avait un nom accessible avant cette modification et ne l'a plus

Sans constats Introduit ou Régression, omettez le tableau et indiquez « Aucun constat d'interface exploitable dans cette modification. »

Ensuite, les constats Préexistant, au maximum trois, par ordre de sévérité décroissante, énoncés simplement comme n'étant pas de la responsabilité de cette modification. Omettez la section lorsqu'il n'y en a pas.

Sévérité	Domaine	Emplacement	Problème
MOYENNE	Typographie	src/Toolbar.tsx:7	Les badges numériques utilisent des chiffres proportionnels ; prédate cette modification

La limite et le verdict couvrent uniquement les constats Introduit et Régression. Les constats Préexistant se situent en dehors de la limite, donc toucher un fichier hérité ne peut pas se transformer en audit complet du fichier. Ils se situent également en dehors du verdict, donc une modification dont les seuls constats sont préexistants est une Approbation.

Terminez par Bloquer lorsque des constats ÉLEVÉS subsistent et Approuver sinon, laissant les constats restants dans le tableau comme travail à faire. Lorsque better-interface est disponible, l'échelle de sévérité et la limite proviennent de lui.