jzjizhe/research-review

Révision de Recherche (Portes de Révision Modulaires et Combinées)

Planification, Codage et Test peuvent être exécutés seuls ou combinés :

• Si vous avez seulement planifié, exécutez le Mode A (Révision du Plan).
• Si vous avez écrit du code et immédiatement écrit/exécuté des tests (le flux naturel), exécutez le Mode B+C Combiné (Révision Conjointe du Code et du Test) en un seul cycle de révision parallèle — ne gaspillez pas de temps à lancer deux cycles de révision séparés l'un après l'autre.
• Si vous avez seulement écrit du code sans tests, ou seulement écrit/exécuté des tests pour du code existant, exécutez le Mode B ou le Mode C seul.

1. Dispatch du Sous-agent Réviseur (spawn_subagent)

• Réviseurs par Défaut (channel=mcli) : Appelez spawn_subagent simultanément pour lancer deux réviseurs parallèles et attendez les deux via get_command_or_subagent_output :
  • Sous-agent 1 : model: "deepseek-v4.1-flash" (canal mcli)
  • Sous-agent 2 : model: "glm-5.3" (canal mcli)
• Surcharge Utilisateur : Si l'utilisateur spécifie d'autres modèles (par exemple, kimi-k3.1-pro, MiniMax-M3.1-Flash, deepseek-v4-pro, ou des slugs friday/* / catpaw-ide/*), transmettez les slugs model spécifiés par l'utilisateur à spawn_subagent.
• Clôture Incrémentale (resume_from) :
  • Découverte (Tour 1) : Lancez de nouveaux sous-agents avec seulement l'artefact minimal (Plan, git diff, code de test + sortie standard/erreur d'exécution) et les chemins de fichiers clés — ne transmettez jamais votre historique de conversation.
  • Clôture (Tour 2+, si des correctifs ou des tests supplémentaires étaient nécessaires) : Appelez spawn_subagent avec resume_from: "<subagent_id>" pour chaque réviseur, en transmettant uniquement les résultats actifs et le delta de correctif/test afin qu'ils vérifient la mise à jour sans relire les fichiers inchangés.

2. Limites de Rôle Centrales

1. L'Agent Principal Effectue d'Abord la Validation : Exécuter un test syntaxique/rapide avant de dispatcher les réviseurs est encouragé afin que les réviseurs ne perdent pas d'efforts sur une syntaxe cassée. Transmettez votre commande de test exacte et la sortie comme "Preuve de validation par l'agent principal".
2. Réviseurs Strictement en Lecture Seule : Demandez aux sous-agents réviseurs de seulement lire/grep les fichiers, de signaler les résultats ordonnés par sévérité avec des preuves file:line, et d'émettre - Validation request: <vérification exacte> lorsqu'un cas limite non testé nécessite une preuve d'exécution. Les réviseurs ne modifient jamais les fichiers et n'exécutent jamais de commandes.
3. Arbitrage par l'Agent Principal : Attendez que tous les réviseurs lancés aient terminé avant de modifier. Reproduisez indépendamment les bogues candidats, exécutez les Validation requests valides, et tranchez (accepté / rejeté) avec des preuves concrètes de code ou de mathématiques.

---

Mode A : Révision du Plan (Autonome)

1. Préparation : Énoncez l'objectif, les fichiers à toucher, les formes des tenseurs / flux de données et les hypothèses explicites (tout choix non énoncé affectant la sémantique d'entraînement, l'échelle de récompense ou l'équité de la ligne de base).
2. Invitation des Réviseurs :

   "Révision en lecture seule de ce plan de recherche. Ne modifiez pas les fichiers et n'exécutez pas de commandes. Contestez les hypothèses non énoncées, vérifiez les fuites de données/étiquettes, l'iniquité de la ligne de base et les goulots d'étranglement distribués/de déploiement. Indiquez Review coverage: FULL|PARTIAL - <fichiers inspectés> et terminez par Review verdict: APPROVED|FINDINGS. [Insérez le Plan et les Chemins de Fichiers Clés]"

Mode B : Révision du Code (Autonome — lorsque aucun test n'a encore été écrit)

1. Préparation : Rassemblez le résumé des exigences/plan et git diff.
2. Invitation des Réviseurs : Demandez-leur d'inspecter les fichiers modifiés et les appelants à un saut en lecture seule pour détecter les bogues de recherche silencieux :
   • Masquage et Alignement : Erreurs de décalage de masque de jeton prompt vs réponse SFT/RL, décalages de côté de padding, ou gestion EOS/troncature.
   • Formes de Tenseurs et Broadcasting : Broadcasting non intentionnel (par exemple, (B, 1) vs (B,)), erreurs de dimension de réduction (mean/sum sur séquence vs batch).
   • Hygiène de Gradient et d'État : detach()/no_grad() mal placé, direction de KL, portée de normalisation de l'avantage, ou état d'environnement d'agent non réinitialisé entre les déploiements.
   • Exigez Review coverage et Review verdict: APPROVED|FINDINGS.

Mode C : Révision du Test (Autonome — lors de l'ajout/d'audit de tests pour du code existant)

1. Préparation : Rassemblez le chemin du fichier de test, le chemin du module cible et la sortie standard/erreur réelle de l'exécution du test.
2. Invitation des Réviseurs :

   "Audit en lecture seule de ce test et de sa sortie d'exécution. Ne modifiez pas les fichiers et n'exécutez pas de commandes. A-t-il vraiment vérifié les invariants mathématiques/tenseurs fondamentaux et les cas limites, ou a-t-il simulé la logique réelle / affaibli les assertions pour réussir ? Émettez - Validation request: ... si un cas limite n'est pas testé. Indiquez Review coverage et terminez par Review verdict: APPROVED|FINDINGS."

Mode B+C : Révision Conjointe du Code et du Test (Lorsque l'Agent Principal a codé et auto-testé en une seule fois)

1. Préparation : Emmenez le résumé des exigences/plan, le git diff de l'implémentation + test, et la "Preuve de validation par l'agent principal" (commande de test exacte exécutée et sa sortie standard/erreur).
2. Invitation des Réviseurs :

   "Révision conjointe en lecture seule du diff d'implémentation et de l'auto-test de l'Agent Principal. Ne modifiez pas les fichiers et n'exécutez pas de commandes.

   1. Vérification du Code : Recherchez les bogues de recherche silencieux dans les fichiers modifiés et les appelants à un saut (masque de jeton décalé, alignement padding/EOS, broadcasting non intentionnel de tenseurs (B,1) vs (B,), mauvaise dimension de réduction, detach()/no_grad() mal placé, mathématiques KL/avantage, état de déploiement non réinitialisé).
   2. Audit de l'Auto-test : Vérifiez si le test de l'Agent Principal vérifie vraiment ces invariants et cas limites, ou s'il souffre d'un biais de confirmation (seulement tester les chemins heureux, simuler la logique centrale, ou assertions faibles). Émettez - Validation request: <vérification exacte> pour tout test de cas limite manquant. Indiquez Review coverage: FULL|PARTIAL - <fichiers inspectés> et terminez par Review verdict: APPROVED|FINDINGS."

3. Arbitrage et Clôture : Corrigez les bogues de code acceptés et satisfaites les Validation requests valides ; si des modifications non triviales ont été effectuées, utilisez resume_from sur les deux réviseurs pour vérifier le delta.

---

3. Registre Léger (docs/review-log.md)

Après chaque porte de révision terminée, ajoutez une entrée concise de 5 à 10 lignes en anglais à docs/review-log.md dans le projet actuel (créez le fichier s'il n'existe pas). Cela préserve les handles subagent_id à travers la compaction de contexte et maintient une piste d'audit expérimentale :

## [YYYY-MM-DD] <Titre Court de la Tâche> (<Mode A / B / C / B+C>)
- **Hypothèses / Périmètre** : <Résumé en 1 ligne des hypothèses de conception clés et des fichiers touchés>
- **Réviseurs** : `deepseek-v4.1-flash` (`id: <subagent_id>`), `glm-5.3` (`id: <subagent_id>`)
- **Arbitrage** :
  - `[ACCEPTED]` `<fichier:ligne>` — <Bogue/défaut concis et comment il a été corrigé>
  - `[REJECTED]` `<fichier:ligne>` — <Pourquoi le résultat du réviseur était un faux positif, avec preuve mathématique/de code>
- **Verdict et Preuve** : `APPROVED` (<Résultat de vérification du test/smoke en 1 ligne>)