review

/review                              # examiné la branche courante vs main
/review ma-branche-fonctionnalite    # examiné une branche spécifique vs main

Spawne des sub-agents Breaker (correctness) et API Analyst (compatibilité/conventions) dédiés en parallèle tandis que l'orchestrateur effectue la passe Inspector (architecture, tests, performance, sécurité). La profondeur est sélectionnée par l'utilisateur.

Optimisé pour des conclusions haute-confiance et concises. Le silence est préférable à la spéculation.

Entrée

Cible : $ARGUMENTS

Parse $ARGUMENTS :

1. Cible de review (argument positionnel) :
   • Texte non-vide (p. ex. ma-branche-fonctionnalite) -> diff cette branche vs main
   • Vide -> diff branche courante vs main

Étape 1 : Confirmer le mode

Avant tout, demandez à l'utilisateur :

Je peux exécuter une review de code sur votre branche. Choisissez une profondeur (plus rapide à plus lente) :

1. Ignorer — ignorer la review
2. Rapide — passe unique par orchestrateur, tous les domaines, pas de sub-agents
3. Standard — full swarm : sub-agents Breaker + API Analyst + Inspector
4. Approfondie — Standard + lit les fichiers complets modifiés (pas seulement les diffs) pour une analyse plus profonde

Attendez la réponse de l'utilisateur. S'il dit ignorer, arrêtez ici.

<required> Immédiatement après que l'utilisateur choisisse un mode, créez une tâche par étape applicable avec TaskCreate — avant tout autre travail. Marquez chaque tâche in_progress quand vous la démarrez et completed quand vous la terminez.

Tâches à créer par mode :

• Rapide : Collecter les changements -> Lire les diffs -> Effectuer review passe unique -> Dédupliquer et classifier -> Reporter
• Standard : Collecter les changements -> Lire les diffs -> Détecter les changements de surface API -> Extraire les sections pour sub-agents -> Effectuer review (spawner Breaker + API Analyst, exécuter Inspector) -> Dédupliquer et classifier -> Reporter
• Approfondie : Collecter les changements -> Lire les diffs et fichiers complets -> Détecter les changements de surface API -> Extraire les sections pour sub-agents -> Effectuer review (spawner Breaker + API Analyst, exécuter Inspector) -> Dédupliquer et classifier -> Reporter </required>

Étape 2 : Setup et collecte des changements

git fetch origin main && git log origin/main..HEAD --oneline && git diff --stat origin/main...HEAD

Si un nom de branche a été fourni comme argument, remplacez HEAD par origin/<branch-name> et ajoutez-le au fetch :

git fetch origin main <branch-name> && git log origin/main..origin/<branch-name> --oneline && git diff --stat origin/main...origin/<branch-name>

Si vous êtes sur main et aucun nom de branche n'a été fourni, demandez à l'utilisateur quelle branche examiner.

Stockez le log de commits, la liste de fichiers depuis --stat, et le total $LINES_CHANGED.

Gate diff vide : Zéro fichiers modifiés -> reporter "Aucun changement à examiner" et arrêter.

Gate de taille : >10 000 lignes modifiées -> demandez à l'utilisateur de restreindre la portée avant de continuer.

Étape 3 : Lire les diffs et fichiers source

Excluez les fichiers non-examinables de la liste : déclarations de type (.d.ts), lockfiles (pnpm-lock.yaml, package-lock.json), images, polices, binaires, fichiers .map, et fichiers générés de rapport API (*.api.md).

Lisez les diffs par fichier par lots (~50 fichiers ou ~500 lignes modifiées par lot, le plus petit des deux) :

git diff origin/main...HEAD -- <file1> <file2> ...

Pour les branches nommées, utilisez origin/main...origin/<branch>.

Mode Standard : lectures sélectives de fichiers complets

Après lecture des diffs, identifiez les fichiers où un contexte plus complet est nécessaire — typiquement où le changement affecte une fonction qui référence un état partagé, appelle d'autres fonctions du même fichier, ou a des hunks fragmentés. Lisez ces fichiers en un lot avec l'outil Read.

Mode Approfondie : lectures complètes pour tous les fichiers modifiés

Lisez chaque fichier modifié en intégralité (la version sur la branche de review). Utilisez git show HEAD:<file> ou git show origin/<branch>:<file> selon le cas.

Piège de plomberie partagée

Si un changement thread une nouvelle prop, callback, flag, ou champ de données à travers un composant partagé ou helper, lisez chaque call site modifié et wrapper adjacent qui l'accepte ou le forward.

Calculez $LINES_REVIEWED : Comptez le total de lignes uniques examinées — lignes de diff pour fichiers en diff-only, comptages de lignes complets pour fichiers lus intégralement. C'est toujours >= $LINES_CHANGED.

Gate sans code : Si aucun fichier logique exécutable ne reste après exclusions (que docs/config modifiés), skipper Breaker. API Analyst effectue une passe réduite. Inspector uniquement.

Étape 4 : Détecter les changements de surface API

Vérifiez si des fichiers de rapport API ont changé (noms uniquement, pas le contenu — ces fichiers sont exclus de la lecture des diffs à l'étape 3) :

git diff --name-only origin/main...HEAD | grep -E '\.api\.md$' || true

Si des correspondances, flaggez ces packages pour l'API Analyst (déclenche un examen supplémentaire sur les tags de release, les breaking changes, et les conventions).

Étape 5 : Extraire les sections pour sub-agents (Standard et Approfondie seulement)

Skipper cette étape en mode Rapide.

Pour les fichiers lus intégralement qui sont >200 lignes, extrayez uniquement : fonctions modifiées (corps complets), leurs appelants (même fichier), et état partagé. Format :

### file.ts (extracted — N lines from M total)
// Fields
#cache: Map<string, Promise<Foo>> = new Map();
// Modified: someMethod() — line 816
async someMethod(arg) { ... }
// Caller: #helperMethod — line 1118
async #helperMethod(arg) { ... }

Fichiers <=200 lignes : embarquez intégralement. Stockez comme $EXTRACTED_SECTIONS.

Étape 6 : Effectuer la review

Domaines de review

Toutes les reviews couvrent ces domaines. Le mode détermine si des sub-agents en gèrent certains.

• Correctness — Bugs logiques, dangers null/undefined, race conditions, gestion d'erreurs, cas limites, préoccupations des systèmes distribués (ordonnancement ops, cohérence finale, conflits de fusion), cycle de vie DDS (attach/detach, summarization), patterns SharedTree (validation de schéma, transactions tree)
• API Quality — Breaking changes, correction des tags de release, conventions de nommage, design de types, ergonomie, impact cross-package, patterns de dépréciation (informés par api-conventions.md)
• Architecture — Lisibilité, structure, surface API, références obsolètes
• Tests — Couverture, cas limites, qualité des assertions, cohérence code-test
• Performance — Complexité algorithmique, fuites mémoire, exactitude de la télémétrie (les événements se déclenchent-ils avec les bonnes données ?)
• Security — Injection, validation d'entrée, fuites PII, gestion de tokens

Gate haute-confiance

Avant qu'un finding ne puisse apparaître dans le rapport, vérifiez TOUS ces critères :

1. Le chemin de code affecté (modifié ou directement impacté chemin adjacent) est identifié.
2. Le mécanisme d'échec ou l'invariant violé est concret, pas hypothétique.
3. L'impact revendiqué est proportionnel à la preuve.
4. Le fix suggéré adresse le problème exact.

Si une revendication dépend d'un conseil d'hardening générique, d'une nullabilité devinée, d'un comportement spéculatif, ou d'une hypothèse non-vérifiée sur une dépendance, lisez plus de contexte ou abandonnez-le.

Format de sortie pour tous les findings : [SEVERITY] file:line — description — suggested fix (CRITICAL, HIGH, MEDIUM).

Mode Rapide

L'orchestrateur couvre tous les domaines en une passe unique, puis passe à l'étape 7.

Mode Standard et Approfondie

Deux pistes parallèles :

The Breaker — possède Correctness

Pensez comme un chaos monkey travaillant sur un framework de systèmes distribués. Votre unique focus est de trouver des manières que ce code produit des résultats incorrects, s'écrase, ou se comporte de façon inattendue.

Vous n'êtes PAS ici pour féliciter du bon code. Vous êtes ici pour CASSER les choses.

Votre mentalité :

• "Et si deux clients envoient des ops conflictuelles simultanément ?"
• "Et si le réseau meurt en milieu d'opération ?"
• "Et si j'attach, detach, puis réattache ?"
• "Que se passe-t-il aux limites — collections vides, tailles maximales, ops de longueur zéro ?"
• "Et si la dépendance change ou une garde était supprimée mais ses siblings ne l'étaient pas ?"
• "Et si la summarization s'exécute pendant que des ops sont en vol ?"
• "Et si j'appelle ça avant que le conteneur soit connecté ?"

The API Analyst — possède API Quality

Pensez comme un developer advocate qui comprend profondément le design d'API TypeScript. Votre unique focus est d'assurer que ce code présente une surface d'API propre, cohérente, user-friendly qui suit les conventions du Fluid Framework.

Vous n'êtes PAS ici pour féliciter du bon code. Vous êtes ici pour trouver des problèmes de design d'API.

Votre mentalité :

• "Un nouvel utilisateur comprendrait-il cette API par IntelliSense seul ?"
• "Ce nommage suit-il nos conventions ?"
• "C'est un breaking change ? Le tag de release est-il correct ?"
• "Les generics gagnent-ils leur place ou ajoutent-ils juste du bruit ?"
• "Ce design de type joue-t-il bien avec les autres — données plaintext, JSON-compatible ?"
• "Ce chemin de dépréciation fonctionnera-t-il réellement pour les consumers ?"
• "Y a-t-il une complexité inutile qui pourrait être une surcharge plus simple ?"

The API Analyst reçoit le contenu de api-conventions.md (dans le répertoire de cette skill) dans sa prompt.

Lisez api-conventions.md :

cat .claude/skills/review/api-conventions.md

The Inspector (orchestrateur)

Tandis que les sub-agents s'exécutent, effectuez la passe Architecture, Tests, Performance, et Security vous-même en utilisant le contexte diff complet et le raisonnement cross-file.

Spawning Sub-agents

Spawner tous les sub-agents en un seul batch parallèle avec l'outil Agent.

Chaque prompt de sub-agent inclut — littéralement collé dans le texte de prompt :

1. Description de persona (ci-dessus)
2. Liste de fichiers modifiés
3. Diff complet de l'étape 3 — coller la sortie diff entière
4. Sections extraites de l'étape 5 — coller le code extrait complet
5. Conventions API (API Analyst uniquement) — coller le contenu de api-conventions.md
6. Format de sortie : [SEVERITY] file:line — description — suggested fix
7. Instruction de mode de review :
   • Si reviewing la branche courante : "Ceci est une review LOCALE — le checkout workspace correspond au code sous review. Vous pouvez lire les fichiers workspace pour du contexte supplémentaire (appelants, définitions de type, logique adjacente) quand le matériel embarqué est insuffisant."
   • Si reviewing une branche nommée : "Ceci est une review DISTANTE — le checkout workspace peut être sur une branche différente. N'UTILISEZ PAS read sur les fichiers workspace. TOUT le code dont vous avez besoin est embarqué ci-dessus. Basez votre analyse UNIQUEMENT sur le diff et les sections extraites fournies."

Effectuez la passe Inspector vous-même tandis que les sub-agents s'exécutent. Attendez que tous se complètent.

Étape 7 : Dédupliquer et classifier

Classifiez chaque finding et ajustez la sévérité :

Findings multi-domaines : classifier dans le domaine qui donne la sévérité la plus haute. Abandonner les findings incertains. Si une préoccupation dépend de devinage, de mauvaise utilisation hypothétique, ou d'hardening au-delà d'une couche déjà-appliquée, l'omettre.

Étape 8 : Reporter

Dédupliquez sur file:line, triez par sévérité. Abandonner les findings "looks correct".

Routage de sortie :

• 5 ou moins de findings : Imprimer le rapport complet au terminal.
• Plus de 5 findings : Écrire le rapport complet à /tmp/review-report.md et imprimer un résumé au terminal : verdict line, comptages de findings par domaine, et le chemin du fichier.

Toujours imprimer : Review report written to /tmp/review-report.md quand écrivant au fichier.

Si zéro findings restent après la gate d'evidence, utilisez la ligne de résumé exacte : 0 CRITICAL, 0 HIGH, 0 MEDIUM — No high-confidence issues found in the current diff.

Modèle de rapport

# Code Review Report

**Target**: Branch: <branch-name>
**Mode**: quick | standard | deep
**Lines reviewed**: $LINES_REVIEWED ($LINES_CHANGED changed)

## Verdict: Approve | Approve with suggestions | Request changes

N CRITICAL, N HIGH, N MEDIUM — résumé d'une ligne de l'évaluation générale.

### Findings

| Sev | # | Area | File | What | Fix |
|---|---|---|---|---|---|
| :red_circle: | C1 | Correctness | file.ts:42 | Description of violation and impact | Concrete fix suggestion |
| :orange_circle: | H1 | API Quality | file.ts:80 | Description | Fix |
| :yellow_circle: | M1 | Tests | file.test.ts:12 | Description | Fix |

**By area:** Correctness: 1:red_circle:  API Quality: 1:orange_circle:  Tests: 1:yellow_circle:

### Changes Overview

Tableau de chaque fichier modifié -> ce qui a changé et pourquoi.

### Suggestions

Améliorations optionnelles, non-bloquantes. Chacune doit proposer une **action concrète** — jamais juste décrire ce qui est déjà là. Omettre cette section s'il n'y en a pas.

---
Generated with review (mode)

Règles de Verdict

Après caps de sévérité et promotions :

• Approve : 0 CRITICAL, 0 HIGH
• Approve with suggestions : 0 CRITICAL, 0 HIGH en Correctness/API Quality, certains HIGH/MEDIUM ailleurs
• Request changes : 1+ CRITICAL, ou 1+ HIGH en Correctness/API Quality, ou 3+ HIGH à travers d'autres domaines

Étape 9 : Proposer les prochaines étapes

What next?
1. Explain a specific finding
2. Fix all critical/high issues
3. Re-review after changes

Cas limites

• Diff vide : Reporter "Aucun changement à examiner" et arrêter.

• 10 000 lignes modifiées : Demandez à l'utilisateur de restreindre la portée.

• Sur main sans argument de branche : Demandez quelle branche examiner.
• Aucun code exécutable après exclusions : Skipper Breaker. API Analyst passe réduite. Inspector uniquement.
• Timeout sub-agent : Noter "Review incomplete" pour ce domaine.