branch-review-tracker

Suivi de révision de branche

Une révision d'une branche fixée sur plusieurs rounds. Chaque round re-révise la branche et met à jour une page : une liste numérotée de problèmes, chacun avec un statut et une fenêtre contextuelle Détails donnant les preuves, le commit responsable et les emplacements à vérifier.

La page est un Artifact de claude.ai, et c'est l'enregistrement de la révision. Elle est en lecture seule pour les spectateurs : seul Claude modifie un statut, à mesure que la révision et les corrections progressent. Une nouvelle session reprend à partir du petit context.json de la page, pas de la conversation ni des fichiers locaux.

Le suivi contient trois fichiers :

• index.html : la page, une copie de assets/tracker.html;
• issues.json : chaque problème, et le journal de session;
• context.json : les notes de reprise et un index des problèmes pour la session suivante, l'invite qui la démarre, et la courte liste de ce qui attend l'utilisateur, qui est la seule partie que la page affiche.

1. Demander quoi réviser

Rassemblez d'abord les candidats, puis demandez tout en un seul appel AskUserQuestion. Ignorez une question dont la réponse est venue avec l'invocation, par exemple un numéro ou une URL de PR.

git for-each-ref --sort=-committerdate --count=6 --format='%(refname:short)' refs/heads
git symbolic-ref --short refs/remotes/origin/HEAD      # la base par défaut
git log --format=%s <base>..<target> | grep -oE '[A-Z]+-[0-9]+' | sort -u
gh pr list --head <target> --json number,url,title     # ou : glab mr list --source-branch <target>

Question	Options
Branche cible	la branche head de la PR si une PR a été donnée ; sinon les trois branches locales les plus récemment mises à jour autres que la base
Branche de base	la branche par défaut du dépôt distant (Recommandée), puis les autres branches à longue durée de vie, le cas échéant
Ticket	ids trouvés dans le nom de la branche et ses sujets de commit ; Pas de ticket

L'utilisateur peut toujours taper une autre valeur. Posez la question sur le ticket après que la branche est connue, ou dérivez ses options de la cible la plus probable.

2. Vérifier l'environnement

Exécutez le script de pré-vol et montrez son tableau à l'utilisateur :

<cette compétence>/scripts/preflight --target <branche> [--base <base>] [--ticket <id>]

Il vérifie le dépôt, les deux refs, le checkout de l'utilisateur, si la branche locale correspond à la tête de la PR, la PR sur l'hôte, les filtres de checkout qui peuvent bloquer git worktree, et les CLI que la révision utilise. Le code de sortie 2 signifie un blocage ; 1 signifie avertissements uniquement. Il ne vérifie pas les outils de construction du projet : ceux-ci appartiennent aux compétences d'aide du projet.

Le script récupère les deux branches. Il prend la base depuis origin, où elle est actuelle, et la cible depuis le clone, où l'auteur peut l'avoir poussée. Révisez par rapport aux refs qu'il imprime. S'il avertit que la branche locale diffère de la tête de la PR, révisez la tête de la PR : lisez-la avec git show <sha>:<chemin> au lieu de la checkout.

Ensuite, vérifiez les outils de cette session, qu'un script ne peut pas voir, et ajoutez-les au tableau :

Nécessaire pour	Outil	Sans lui
la révision	compétence code-review, ou l'outil Agent	bloqueur
la page	outil Artifact	gardez les fichiers dans le bloc-notes et donnez leurs chemins à l'utilisateur après chaque round ; dites-le
le contexte du ticket, et la publication de tickets	Outils Atlassian (getJiraIssue, createJiraIssue)	révisez sans ; dites-le
les commentaires et vérifications de la PR	gh ou glab, authentifié	révisez la branche uniquement ; dites-le

Ensuite, recherchez les compétences d'aide du projet, comme décrit dans "Compétences d'aide" ci-dessous, et ajoutez une ligne par aide au tableau : trouvé, avec son nom, ou manquant, avec ce que la révision manquera.

Arrêtez-vous sur un bloqueur et dites ce qui manque. Sur les avertissements, dites ce que la révision ne couvrira pas, et continuez.

Si le ticket peut être lu, récupérez son résumé et son statut. Écrivez un statut entre parenthèses après l'id : PROJ-123 (en cours).

3. Premier round

1. Réviser. Invoquez code-review sur <cible> contre <base>, ou sur le numéro de PR. Dites au réviseur de lire les autres commits avec git show <rev>:<chemin>, et de ne jamais checkout quoi que ce soit dans le répertoire de l'utilisateur.

2. Réviser la prose, comme décrit dans "La révision de la prose" ci-dessous. code-review recherche les défauts dans le code et ne la couvre pas.

3. Vérifier chaque constatation, comme décrit dans "Vérification des constatations" ci-dessous. Un problème ne va sur la page qu'après cette étape. Une constatation qui n'y survit pas est soit abandonnée avant d'être listée, soit, une fois listée, mise à dismissed avec sa raison.

4. Classer chaque problème.

   • Le commit responsable : git log -S'<symbole>' <base>..<cible>, ou git blame -s <cible> -- <chemin>.
   • Si la base l'a aussi : git show <base>:<chemin>. Un problème que la base a déjà obtient "commitRole": "Préexistant sur" et "commit": "<base>". Ce n'est pas une régression de la branche, mais cela peut toujours bloquer la fusion lorsque la branche l'aggrave, par exemple en exposant plus de données à travers elle.
   • fichier:ligne pour chaque emplacement, au commit révisé.

5. Écrire le suivi dans le bloc-notes de session, dans un dossier nommé d'après la branche (/ remplacé par -) :

   • index.html : une copie de assets/tracker.html, avec __TITLE__ remplacé par le nom de la page. Le nom est le sujet de la branche en deux à quatre mots, suivi de "Review", comme API Key Authorization Review.
   • issues.json et context.json, comme décrit dans "Les fichiers de données" ci-dessous.

6. Valider les deux fichiers. Le validateur vérifie le schéma, que chaque emplacement existe au commit révisé, et que l'index dans context.json correspond aux problèmes :

   python3 -I <cette compétence>/scripts/validate-issues.py <dossier>/issues.json --repo <dépôt>
   

7. Publier avec l'action de publication de l'outil Artifact, file_path défini sur <dossier>/index.html, files défini sur {"issues.json": "<dossier>/issues.json", "context.json": "<dossier>/context.json"}, icon: "checklist" et une description d'une phrase. Écrivez l'URL retournée dans les deux fichiers ("artifact"), republiez, et donnez le lien à l'utilisateur.

4. Rounds ultérieurs

Exécutez un round lorsque l'utilisateur dit que la branche a été mise à jour, ou qu'il demande une re-révision.

1. Confirmer que la branche a bougé. Comparez la tête de la PR, ou la ref cible, avec reviewed, et regardez git reflog -3 --date=iso <cible>. Un push peut arriver en retard, et la branche locale de l'utilisateur peut prendre du retard sur la PR. Si rien n'a bougé, dites-le et arrêtez-vous.
2. Récupérer la base (git fetch origin <base>). Si la base a bougé, notez-le, et comparez la branche avec git range-diff <ancienne-base>..<ancien-bout> <nouvelle-base>..<nouveau-bout>.
3. Voir ce qui a changé :
   • git range-diff <base>..<reviewed> <base>..<cible> montre quels commits ont été réécrits, ajoutés ou supprimés ;
   • git diff <reviewed> <cible> montre le changement net ;
   • les nouveaux commentaires, révisions et vérifications de la PR (gh pr view <n> --json comments,reviews, gh api repos/<propriétaire>/<dépôt>/pulls/<n>/comments, gh pr checks <n>).
4. Évaluer chaque correction. Pour chaque problème que le changement adresse, lisez la correction et enregistrez dans fix ce qu'elle fait et comment le code se comporte maintenant. Ne mettez fixed que lorsque la lecture le confirme, et dites dans verified jusqu'où cela a été vérifié.
5. Rechercher les problèmes causés par les corrections. Une correction déplace souvent le problème au lieu de le supprimer. Vérifiez les entrées que l'ancien code gérait accidentellement :
   • une valeur manquante, vide ou nulle, par exemple une propriété qu'un client ne définit pas, qui produisait un littéral inoffensif et qui signifie maintenant "aucune restriction" ;
   • les valeurs par défaut auxquelles une valeur se rabat ;
   • les chemins de code que le changement atteint sans les toucher, comme les appelants, d'autres points de terminaison, les clients plus anciens et le côté import d'une exportation ;
   • le comportement que le changement modifie pour les requêtes qu'il ne ciblait pas. Ajoutez chaque problème comme un nouveau problème, et notez la correction qui l'a causé sur les deux problèmes. Exécutez "La révision de la prose" sur le changement net.
6. Réévaluer chaque problème qui n'est pas corrigé par rapport au nouveau code, et regardez à nouveau ceux corrigés dont le code a changé.
7. Exécuter les tests uniquement comme "Reproduction avec des tests" ci-dessous le permet.
8. Mettre à jour le suivi, comme décrit dans "Maintenir le suivi à jour" ci-dessous :
   • Définissez reviewed sur le nouveau bout.
   • Réécrivez commits avec les nouveaux hachages. Un commit réécrit obtient son nouveau hachage ; un commit supprimé quitte la carte ; un nouveau est ajouté.
   • Modifiez status, commit, commitRole, note, fix et detail des problèmes qui ont changé.
   • Retrouvez la ligne de chaque emplacement au nouveau bout avec git grep -n. Ne décalez pas les lignes par calcul arithmétique.
   • Ajoutez de nouveaux problèmes avec le prochain numéro libre. Ne renumérotez jamais.
9. Valider, puis republier vers la même URL.
10. Rapporter à l'utilisateur : ce que ce round a corrigé, ce qui est toujours ouvert, et ce qui est nouveau, avec fichier:ligne et ce qui a été exécuté. Terminez par le lien de la page.

Vérification des constatations

Lisez le code vous-même au commit révisé avant qu'un problème ne soit mis sur la page.

1. Tracer le scénario de bout en bout. Suivez l'entrée de là où elle entre à là où le dommage se produit, et nommez chaque étape avec fichier:ligne. Une constatation qui a besoin d'une étape que le code ne prend pas est rejetée, avec cette étape comme raison.
2. Vérifier les préconditions. Demandez comment l'état déclencheur peut survenir :
   • qui peut créer l'entrée, par exemple via quelle API, et si un validateur ou une valeur par défaut l'arrête ;
   • si une valeur par défaut configurée, comme une durée de vie illimitée ou un rôle attribué quand aucun n'est donné, rend le scénario inaccessible, ou en fait le cas normal ;
   • si des données existantes peuvent le contenir. Quand seules des données en dehors du dépôt peuvent répondre, utilisez l'aide de vérification de données du projet ; sans une, demandez à l'utilisateur comment le savoir. Enregistrez la réponse dans verified, et dans le journal.
3. Séparer "intentionnel" de "acceptable". Un runbook, un test ou un commentaire de code qui montre qu'un comportement est délibéré ne le rend pas inoffensif. Vérifiez la rétrocompatibilité par elle-même : les clients existants et les versions déployées, les données existantes, et les fournisseurs ou utilisateurs qui n'ont jamais utilisé la nouvelle fonctionnalité. Une rupture délibérée d'un workflow existant est un problème, et un bloqueur à moins que l'utilisateur ne l'accepte.
4. Dire comment cela a été vérifié. Écrivez-le dans verified : "Reproduit par un test au niveau du contrôleur ; la couche service était simulée", "Par la lecture du code ; non exécuté", "Vérification des données : aucun enregistrement correspondant". Rapportez ce que la preuve prouve et nommez ce qu'elle ne prouve pas. N'affirmez pas un verdict causal ou comparatif que les données ne montrent pas.
5. Rejeter avec un enregistrement. Un rejet définit status: "dismissed" et une dismissal avec qui a décidé, quand, et pourquoi. Quand Claude rejette, dites-le, et que personne ne l'a signé ; la page le montre.
6. Rouvrir lorsqu'il est contesté. Lorsque l'utilisateur remet en question un rejet ou un verdict, revérifiez-le à partir du code au lieu de le défendre. Si c'était faux, rouvrez le problème, supprimez le rejet, et dites clairement dans note ce que le verdict précédent avait de faux.

Reproduction avec des tests

Exécutez les builds et les tests uniquement lorsque l'utilisateur le demande, ou lorsque les instructions du dépôt et de l'utilisateur le permettent sans le demander. Comment construire et tester le projet, avec quelle chaîne logicielle et quels paramètres, provient de l'aide de build et de test du projet et de ses instructions, pas de cette compétence.

1. Ne jamais utiliser le checkout de l'utilisateur. Mettez le commit sous test dans un répertoire séparé :
   • git worktree add --detach <bloc-notes>/<nom>-wt <sha> ;
   • si quelque chose bloque l'arbre de travail, exportez le commit à la place, en laissant de côté les chemins qui le bloquent : git archive <sha> -- . ':(exclude)<chemin-bloqué>' | tar -x -C <rép>. Par exemple, un filtre smudge git-crypt échoue sur les chemins cryptés lorsque la clé n'est pas disponible. Le script de pré-vol nomme les chemins qui ont des filtres de checkout.
2. Construire et exécuter comme le projet le dit. Un échec d'outil, comme une chaîne logicielle que le projet ne supporte pas, n'est pas un résultat de test : corrigez l'environnement comme l'aide ou les instructions du projet le disent, puis réexécutez. Sans aide, demandez à l'utilisateur plutôt que de deviner, et notez ce qui a été appris pour les notes du projet.
3. Écrire le test pour qu'il affirme le comportement correct. Un échec reproduit alors le problème, et le même test devient le test de régression pour la correction. Pilotez les vraies classes le long du chemin, et simulez uniquement ce dont le scénario a besoin. Faites en sorte que chaque simulacre reflète ce que le vrai code fait, et nommez chaque couche simulée ou non exercée dans verified, comme HTTP, la chaîne de sécurité ou la base de données.
4. Exécuter l'ensemble le plus restreint : le nouveau test, plus les tests qui couvrent le code modifié.
5. Garder la source du test dans le suivi. Le bloc-notes peut être effacé entre les sessions. Publiez le test comme tests/<Nom>.<ext> dans files, avec contentType: "text/plain", et nommez-le dans le problème.
6. Nettoyer. Supprimez l'arbre de travail ou l'exportation, et toute sortie de build qu'une exécution a laissée dans le checkout de l'utilisateur, comme des classes de test compilées, qu'un build ultérieur pourrait ramasser. Vérifiez ensuite que git status et git worktree list montrent le checkout de l'utilisateur inchangé.

Compétences d'aide

Le flux de révision est le même pour chaque projet ; ce que le projet sait vit dans ses propres compétences. Utilisez-les quand elles existent ; cette compétence ne code jamais en dur l'outillage du projet.

Trouvez-les dans la liste des compétences disponibles de cette session, par leurs descriptions. Ne devinez pas les noms. Chargez-en une avec l'outil Skill lorsque l'étape en a besoin.

Aide	Utilisé pour	Sans elle
liste de contrôle de révision	les zones de risque du projet : modèle de sécurité, promesses de compatibilité, contrats API, migrations	la révision se base sur des connaissances générales ; dites quelles zones elle peut manquer
build et test	construire et tester un commit isolément : commandes, chaîne logicielle, paramètres, bloqueurs connus	les tests ne s'exécutent qu'après avoir demandé à l'utilisateur comment ; les constatations restent "par la lecture du code"
vérifications de données	répondre aux questions à partir de données en dehors du dépôt, en toute sécurité	l'utilisateur est interrogé sur la façon de le savoir
règles de prose	commentaires, docstrings, journaux de modifications, messages de commit et texte de PR, comme un gener
…
[tronqué pour la traduction]