Code Review

Agissez en tant que relecteur senior. Examinez les différences entre HEAD et une base fixe fournie par l'utilisateur. Produisez un artefact traçable :

CODE-REVIEW.md : contexte de la revue, résumé, axe Spécifications, axe Standards, validation suggérée, preuves, hypothèses, questions ouvertes et traçabilité.

Examinez deux axes séparément :

Standards : le code respecte-t-il les conventions de ce dépôt, les politiques de sécurité, les normes de test et les décisions architecturales ?
Spécifications : le code implémente-t-il fidèlement le ticket, le PRD ou le cahier des charges ?

Ne mélangez jamais les deux résultats. Un changement peut respecter toutes les conventions et implémenter malgré tout une exigence erronée.

N'émettez pas d'approbation automatique. Signalez uniquement les risques et les validations requises.

Quand l'utiliser

Utilisez cette compétence lorsque l'utilisateur :

demande une revue d'une branche, d'une PR, d'une demande de fusion ou d'un travail en cours ;
demande d'examiner les modifications depuis une branche, un commit, un tag, une date ou HEAD~N ;
souhaite savoir si un changement respecte les normes du dépôt ;
souhaite savoir si un changement implémente le ticket, le PRD ou le cahier des charges ;
souhaite un artefact de revue traçable avec des preuves et une validation suggérée.

Quand ne pas l'utiliser

N'utilisez pas cette compétence pour :

un audit de sécurité complet avec CVSS, CWE et OWASP ; utilisez security-audit ;
la découverte produit, un PRD, un SPEC, des jalons ou une répartition des tâches ; utilisez techlead ;
les jetons de conception, les bibliothèques de composants ou les audits d'accessibilité ; utilisez design-system ;
une modification d'une seule ligne sans diff ni base fixe ; examinez-la directement ou demandez une base ;
exécuter des tests, des builds, des linters ou des déploiements. Cette compétence examine et suggère une validation ; elle ne l'exécute pas, sauf demande explicite de l'utilisateur.

Règles non négociables

Fixez la base avant d'examiner. Demandez à l'utilisateur lorsque la base est manquante. Ne présumez jamais de main.
Validez la référence avec git rev-parse --verify et examinez git diff <base>...HEAD.
Arrêtez-vous et signalez lorsque la base n'existe pas ou que le diff est vide. Ne continuez pas vers des revues spécialisées.
Gardez les axes Spécifications et Standards séparés dans l'analyse, les constatations et le rapport.
Les normes du dépôt documentées dans le dépôt priment sur les heuristiques générales.
Ignorez les problèmes déjà détectés et bloqués par les linters, formatteurs, vérificateurs de types ou CI.
Distinguez une violation objective d'une suggestion d'amélioration.
Ne proposez pas de refactorisations en dehors du diff, sauf pour la sécurité, l'exactitude ou le risque de régression.
Chaque constatation doit être accompagnée d'une preuve : un extrait de diff, un fichier et une ligne, une exigence de spécification ou une observation reproductible.
N'inventez pas de lignes, de comportements ou d'exigences. Si les preuves sont insuffisantes, écrivez une note ou une question ouverte.
Rédigez les secrets, jetons, données personnelles et données clients. Remplacez les valeurs par [REDACTED].
Lecture seule par défaut : ne modifiez pas le code de l'application, les dépendances, la configuration, les commits ou les pull requests.
N'exécutez pas de tests, linters, builds ou déploiements, sauf demande explicite de l'utilisateur.
N'abaissez pas une sévérité pour débloquer une version. Enregistrez le risque à la place.
N'émettez pas de verdict d'approbation automatique. Signalez les risques et la validation encore requise.
Rédigez l'artefact en anglais par défaut. Conservez les identifiants, marqueurs, valeurs de sévérité, valeurs d'axe et valeurs de statut en anglais.
Préservez chaque marqueur lisible par machine dans le modèle de rapport.
Arrêtez la revue lorsque les questions restantes ne modifieraient pas une constatation, une sévérité ou le plan de validation.

Modes

Sélectionnez le mode avant de commencer et enregistrez-le dans l'artefact.

Examen : fixez la base, lisez le diff, examinez les deux axes et écrivez ou mettez à jour CODE-REVIEW.md.
Validation : validez un CODE-REVIEW.md existant par rapport au contrat de rapport sans refaire la revue.

Workflow

Suivez ces portes dans l'ordre. Ne sautez aucune porte.

Porte 1 : Fixer la base de la revue

Identifiez le point fixe : une branche, un SHA de commit, un tag, main, origin/main, HEAD~N ou une autre référence explicite.
Si l'utilisateur n'a pas fourni de base, demandez quelle base doit être utilisée. Ne devinez pas.
Validez la référence :
```
git rev-parse --verify <base>
```
Vérifiez si le dépôt est superficiel lorsque la base de fusion peut être manquante :
```
git rev-parse --is-shallow-repository
```
Générez le diff par rapport à la base de fusion :
```
git diff <base>...HEAD
```
Listez les commits inclus :
```
git log <base>..HEAD --oneline
```

Collectez la taille du diff et les fichiers modifiés :

git diff --stat <base>...HEAD
git diff --name-status <base>...HEAD

Inspectez l'arbre de travail :
```
git status --short
```
Si des modifications non commitées existent, demandez si elles sont dans le périmètre. Lorsqu'elles le sont, incluez git diff et git diff --cached comme surface d'examen supplémentaire et enregistrez la décision.
Si la base n'existe pas, que la base de fusion ne peut pas être résolue ou que le diff est vide, arrêtez-vous et informez l'utilisateur. Ne continuez pas vers la Porte 2.
Enregistrez chaque commande, sa cible et la sortie pertinente dans la section des preuves du rapport.

Lorsque l'utilisateur donne une date au lieu d'une référence, résolvez le dernier commit avant cette date explicitement :

git rev-list -1 --before=<date> HEAD

Utilisez le commit résultant comme base uniquement après que l'utilisateur l'a confirmé.

Porte 2 : Trouver la spécification

Cherchez la source des exigences dans cet ordre :

Une référence de ticket dans les commits, le nom de la branche ou la description de la PR (#123, Closes #45, Fixes #78).
Un chemin de spécification fourni par l'utilisateur.
Un fichier dans docs/, specs/, .scratch/ ou tasks/ lié au nom de la branche ou à la fonctionnalité.
Demandez à l'utilisateur où se trouve la spécification.

Lisez la source et extrayez :

le problème et le résultat attendu ;
les critères d'acceptation ;
les éléments explicitement dans le périmètre et hors périmètre ;
les contraintes, cas limites et exigences non fonctionnelles ;
les exigences que le diff ne touche pas mais doit préserver.

Mappez chaque exigence aux fichiers, comportements et tests qui l'implémentent.

Si l'utilisateur dit qu'il n'y a pas de spécification, enregistrez exactement :

Aucune spécification disponible ; l'examen des spécifications a été ignoré.

Définissez Spec review: skipped et n'examinez pas l'axe Spécifications et n'inventez pas d'exigences.

Porte 3 : Charger les normes du dépôt

Lisez, lorsqu'ils existent :

CONTRIBUTING.md ;
CODING_STANDARDS.md ;
ARCHITECTURE.md ;
SECURITY.md ;
les ADR dans docs/adr/ ;
la configuration des linters, formateurs, tests et CI ;
les exemples approuvés récents dans le dépôt.

Règles :

Les normes documentées du dépôt priment sur les heuristiques générales.
Ignorez les problèmes que les linters, formateurs, vérificateurs de types ou CI détectent et bloquent déjà.
Distinguez une violation objective d'une suggestion d'amélioration.
Citez la norme qui fonde chaque constatation dans l'axe Standards.
Si aucune norme n'est documentée, utilisez des heuristiques générales et étiquetez-les comme telles dans la référence de la constatation.
Si une norme est ambiguë, enregistrez une question ouverte au lieu d'inventer une règle.

Porte 4 : Examiner par catégorie

Examinez chaque fichier modifié et chaque section significative. N'examinez pas seulement les lignes ajoutées ; tenez compte du code environnant et des consommateurs du comportement modifié.

Axe Spécifications

Exigences remplies : mappez chaque critère d'acceptation à l'implémentation et à ses tests.
Lacunes ou implémentation incorrecte : exigence manquante, implémentation partielle, comportement erroné, contradiction avec la spécification ou exigence non testée.
Périmètre supplémentaire : comportement ajouté en dehors de la spécification, refactorisations non demandées, contrats publics modifiés ou dérive du périmètre.
Pour chaque lacune, citez l'exigence exacte ainsi que le fichier et la ligne où l'implémentation échoue.

Axe Standards

Exactitude : bugs, cas limites, gestion d'erreurs, concurrence, null/indéfini, types et comportement inattendu.
Sécurité : injection, authentification et autorisation, validation des entrées, exposition de données, secrets, SSRF, XSS, CSRF, gestion de fichiers non sécurisée et limites de permissions.
Tests : couverture des chemins nouveaux ou modifiés, cas négatifs, régressions, qualité des assertions et fiabilité.
API et compatibilité : changements cassants, contrats publics, versionnage, migrations et compatibilité des consommateurs.
Performances : requêtes N+1, boucles inutiles, allocations, comportement du cache, index et travail synchrone évitable.
Maintenabilité : noms, duplication, couplage, responsabilités, abstractions prématurées et cohérence avec le domaine.
Observabilité : logs, métriques, traces, alertes et messages d'erreur utiles lorsque le changement affecte l'exploitation en production.

Utilisez references/review-checklist.md pour la liste de vérification détaillée.

Porte 5 : Rédiger le rapport

Créez ou mettez à jour CODE-REVIEW.md en utilisant references/report-template.md. L'emplacement par défaut est la racine de l'espace de travail actuel. Acceptez un chemin différent lorsque l'utilisateur en fournit un.

Exigences :

Préservez le marqueur d'artefact et chaque marqueur de section requis.
Enregistrez la base, la tête, la base de fusion, le nombre de commits, les fichiers modifiés, les sources des normes et la source de la spécification.
Gardez les sections Spécifications et Standards séparées. Ne déplacez jamais une constatation de Spécification dans Standards, ni l'inverse.
Utilisez des identifiants de constatation stables : CR-001, CR-002, et ainsi de suite. Ne renumérotez pas les constatations approuvées sans enregistrer le changement.
Utilisez une seule sévérité par constatation : blocking, recommended ou note. Suivez references/severity-baseline.md.
Donnez à chaque constatation un axe, une catégorie, un emplacement, un problème, une preuve, une suggestion, une référence et une étape de vérification.
Faites correspondre exactement le marqueur des comptes avec les constatations.
Faites correspondre les résumés des comptes avec le marqueur des comptes.
Mappez chaque constatation à une preuve et une validation suggérée dans la section de traçabilité.
Indiquez si l'examen des spécifications a été effectué ou ignoré. Lorsqu'il est ignoré, incluez la phrase exacte de la Porte 2.
Écrivez Aucune constatation dans une catégorie lorsqu'elle n'a pas de constatations. Ne laissez pas de sections vides.
N'incluez pas de secrets, données personnelles ou données clients. Rédigez-les sous forme de [REDACTED].
N'incluez pas de verdict d'approbation, LGTM ou Ship it.

Porte 6 : Validation

Résolvez le chemin du validateur par rapport à ce SKILL.md et exécutez :

python3 skills/code-review/scripts/validate_review.py CODE-REVIEW.md

Options :

--strict                     Traite les avertissements comme des erreurs.
--json                       Émet un rapport lisible par machine.
--min-findings N             Exige au moins N constatations. La valeur par défaut est 0.
--require-spec               Échoue lorsque l'examen des spécifications a été ignoré.
--require-standards-sources  Échoue lorsque aucune source de normes n'est listée.

Corrigez chaque erreur et réexécutez le validateur. Ne livrez pas un rapport qui échoue à la validation.

Si Python n'est pas disponible, effectuez la liste de vérification manuelle dans references/validation-checklist.md.

Porte 7 : Remise

Signalez :

où CODE-REVIEW.md a été écrit ;
la base examinée, la base de fusion, le nombre de commits et les fichiers modifiés ;
les décomptes de constatations par sévérité et par axe ;
le statut de l'examen des spécifications et la lacune la plus risquée dans les spécifications ;
les constatations les plus risquées dans l'axe Standards et leur impact ;
le résultat de la validation ;
les limites, fichiers exclus et vérifications qui n'ont pas été exécutées ;
qu'aucun code d'application, dépendance ou configuration n'a été modifié.

Proposez de suggérer des correctifs ou un plan de remédiation, mais ne modifiez pas le code, ne commitez pas, ne poussez pas et n'ouvrez pas de pull request, sauf demande explicite de l'utilisateur.

Règle des deux axes

Les axes répondent à des questions différentes et doivent rester séparés :

Axe	Question	Preuve typique
Spécifications	Le changement implémente-t-il l'exigence demandée ?	Ticket, PRD, spécification, critères d'acceptation
Standards	Le changement respecte-t-il les conventions du dépôt et les normes d'ingénierie ?	CONTRIBUTING, ADRs, configuration lint/test/CI, code review

Une constatation peut exister sur les deux axes uniquement lorsque la cause racine est différente et que la correction est différente. Sinon, enregistrez-la une fois sous l'axe qui possède la cause racine et référez-vous croisés à l'autre axe dans le champ de référence.

Exemples :

Un changement respecte toutes les conventions mais omet un critère d'acceptation : une constatation blocking dans Spécifications et aucune constatation dans Standards.
Un changement implémente l'exigence mais introduit un contournement d'autorisation : une constatation blocking dans Standards et une note dans Spécifications indiquant que l'exigence est implémentée mais dangereuse.
Un changement implémente l'exigence avec un modèle documenté mais mauvais : une constatation recommended dans Standards et une entrée "exigences remplies" dans Spécifications.

Contrat d'artefact

CODE-REVIEW.md commence par :

<!-- code-review:artifact type=review version=1 -->

Les sections requises utilisent des marqueurs :

<!-- code-review:section id=summary -->
<!-- code-review:section id=context -->
<!-- code-review:section id=spec -->
<!-- code-review:section id=standards -->
<!-- code-review:section id=validation -->
<!-- code-review:section id=evidence -->
<!-- code-review:section id=assumptions -->
<!-- code-review:section id=traceability -->

La section Spécifications utilise également un marqueur de statut :

<!-- code-review:spec status=performed -->
<!-- code-review:spec status=skipped -->

Le marqueur des comptes doit correspondre aux constatations :

<!-- code-review:counts blocking=1 recommended=2 note=0 -->

Chaque constatation utilise un marqueur immédiatement avant son titre :

<!-- code-review:finding id=CR-001 axis=standards severity=blocking category=security status=open -->
### CR-001 : Titre court de la constatation

Chaque corps de constatation contient :

Axe : Spécifications ou Standards
Sévérité : Bloquant, Recommandé ou Note
Catégorie : spec-gap, scope, correctness, security, tests, api, performance, maintainability ou observability
Emplacement : path/to/file.ext:42, path/to/file.ext ou n/a pour une constatation dans Spécifications sans emplacement de code
Problème : le défaut, le risque ou la lacune
Preuve : un extrait de diff, un fichier et une ligne, une exigence de spécification ou une o...

rmsaitam/code-review

Qu'est-ce que code-review ?

Demander à votre IA préférée

Documentation