Skill de Révision

Ce skill couvre l'étape de Révision du workflow AI-DLC : approuver ou rejeter les Propositions, vérifier les Tâches complétées, et gérer la gouvernance globale du projet en tant qu'Agent Admin.

Vue d'ensemble

L'Agent Admin a accès complet à toutes les opérations Chorus. Vous êtes le rôle proxy humain — agissant au nom du propriétaire du projet pour assurer la qualité et gérer le cycle de vie AI-DLC.

Responsabilités clés :

• Révision des propositions — approuver ou rejeter les Propositions soumises par les PM Agents (voir skill_view("chorus:proposal"))
• Vérification des tâches — vérifier ou rouvrir les Tâches soumises par les Developer Agents (voir skill_view("chorus:develop"))
• Gouvernance du projet — créer des projets/idées, gérer les groupes, fermer/supprimer des entités

Outils

Exclusifs Admin :

PM + Admin (rejet/révocation de proposition) :

Tous les outils PM (chorus_pm_*, chorus_*_idea) et tous les outils Developer (chorus_*_task, chorus_report_work) sont également disponibles pour Admin.

Outils partagés (checkin, query, comment, search, notifications) : voir skill_view("chorus:chorus")

Stratégie de Révision

Lors de la révision de propositions, tâches ou du changement de code agrégé final d'une Idée, préférez exécuter un reviewer indépendant plutôt qu'une révision manuelle :

1. Essayez d'abord le reviewer. Exécutez chorus-proposal-reviewer (pour les propositions), chorus-task-reviewer (pour les tâches), ou chorus-code-reviewer (la passerelle de ship-time final sur le changement de code agrégé d'une Idée, après sa dernière tâche vérifiée — passez ideaUuid ; il poste son VERDICT sur l'idée) en tant qu'enfant read-only delegate_task (exemples ci-dessous). delegate_task bloque jusqu'à ce que le reviewer finisse, donc vous attendez toujours avant de procéder. Le verdict est le commentaire VERDICT qu'il poste sur l'entité, pas la valeur retournée de l'appel, donc lisez le commentaire (étape 2). Il poste un commentaire VERDICT avec des résultats détaillés.

2. Lisez le VERDICT. Après que le reviewer se termine, appelez chorus_get_comments et trouvez le commentaire VERDICT: de cette manche — celui posté après votre dispatch, pas une manche antérieure. Il y a exactement trois résultats possibles :

   • VERDICT: PASS — Aucun problème trouvé. Approuvez (propositions) ou marquez AC comme passé et vérifiez (tâches).
   • VERDICT: PASS WITH NOTES — Notes mineures non bloquantes. Toujours approuver/vérifier. Les notes sont informatives.
   • VERDICT: FAIL — BLOQUEURS trouvés. Rejetez (propositions) ou rouvrez (tâches). Pour une passerelle code-review FAIL, ne rouvrez pas les tâches vérifiées — à la place corrigez via le skill quick-dev (skill_view("chorus:quick-dev")) : chorus_create_tasks avec proposalUuid défini à la proposition approuvée courante pour que les tâches de correction s'y rattachent (voir B2.6). Corrigez les BLOQUEURS spécifiques listés dans le commentaire avant de resoumettez.

3. Aucun nouveau commentaire VERDICT ? Vérifiez ce que le reviewer a posté. Un commentaire rapportant que la limite de manches a été atteinte, ou tout autre refus explicite de réviser, est une escalade délibérée vers un humain : ARRÊTEZ — ne relancez pas, ne faites pas d'auto-révision, ne postez pas un VERDICT propre. S'il n'a rien posté du tout, relancez-le UNE FOIS, en lui demandant de rester dans son budget de tours et de réserver ses derniers tours pour le VERDICT, puis appliquez cette même vérification à ce que la nouvelle tentative poste. Un refus explicite de la nouvelle tentative signifie toujours ARRÊTEZ ; seul un second vrai silence vous laisse réviser l'élément vous-même en tant que pass read-only en utilisant les checklists ci-dessous et POSTER le VERDICT — l'absence n'est jamais un PASS.

4. Suivez les manches. Comptez les commentaires VERDICT existants avant de spawner. Après 3 manches de FAIL sur le même élément, arrêtez la boucle et escaladez vers révision humaine : postez un commentaire disant que la limite de manches a été atteinte et qu'une décision humaine est nécessaire, et ne postez aucun VERDICT. Personne — y compris vous lors d'un tour ultérieur — ne peut remplacer cette escalade par un VERDICT auto-révisé.

5. Fallback. Si le reviewer n'est pas disponible (par ex. le skill reviewer n'est pas enregistré, ou delegate_task échoue), révisez l'élément vous-même en utilisant les checklists de qualité dans les workflows ci-dessous.

Exécuter un reviewer avec delegate_task

Les trois reviewers sont des skills read-only du plugin Chorus Hermes : chorus:chorus-proposal-reviewer, chorus:chorus-task-reviewer, et chorus:chorus-code-reviewer. Chacun s'exécute en tant qu'enfant delegate_task :

• Marqueur. Le context DOIT commencer par [chorus-reviewer:<kind>] (kind = proposal | task | code), et le goal devrait aussi le contenir. Le plugin utilise le marqueur pour mettre l'enfant en mode read-only : les outils d'écriture Chorus autres que chorus_add_comment sont bloqués, tout comme write_file, patch, terminal, execute_code, et delegate_task.

• Contexte isolé. L'enfant ne sait rien de votre conversation. Mettez chaque UUID, le chemin du repo, la limite de manches, et les chemins de preuves dans context, avec l'instruction de skill_view son skill reviewer en premier. Un reviewer n'obtient pas de session Chorus.

• Bundle de preuves. Parce que le reviewer ne peut pas exécuter de commandes, VOUS construisez les preuves avant de déléguer une révision de tâche ou de code : écrivez le diff, le journal de commits, et la sortie test/build du projet dans des fichiers (par ex. sous /tmp/chorus-review/<uuid>/) avec terminal, et passez les chemins absolus. Le reviewer les lit avec read_file. Une révision de proposition ne nécessite pas de bundle (tout est dans Chorus), mais vous pouvez passer le chemin du repo pour des vérifications de convention.

• Blocage. delegate_task retourne quand le reviewer finit. Rien n'a besoin d'être suivi ou fermé. Puis lisez le commentaire VERDICT avec chorus_get_comments.

Reviewer de propositions (après chorus_pm_submit_proposal ; VERDICT sur la proposition) :

delegate_task(
  goal="[chorus-reviewer:proposal] Review Chorus proposal <proposal-uuid> and post one VERDICT comment.",
  context="[chorus-reviewer:proposal]\nFirst call skill_view(\"chorus:chorus-proposal-reviewer\") and follow it.\nProposal UUID: <proposal-uuid>\nProject UUID: <project-uuid>\nMax review rounds: 3 (read existing comments first to determine the round number)\nRepo: <abs repo path>",
)

Reviewer de tâches (après chorus_submit_for_verify ; VERDICT sur la tâche) :

# Bundle de preuves d'abord (parent, via terminal ; <base> = point de branchement, par ex. main)
mkdir -p /tmp/chorus-review/<task-uuid>
git diff <base>...HEAD > /tmp/chorus-review/<task-uuid>/diff.patch
git log --oneline <base>..HEAD > /tmp/chorus-review/<task-uuid>/log.txt
<project test/build command> > /tmp/chorus-review/<task-uuid>/tests.txt 2>&1

delegate_task(
  goal="[chorus-reviewer:task] Review Chorus task <task-uuid> and post one VERDICT comment.",
  context="[chorus-reviewer:task]\nFirst call skill_view(\"chorus:chorus-task-reviewer\") and follow it.\nTask UUID: <task-uuid>\nProject UUID: <project-uuid>\nMax review rounds: 3\nRepo: <abs repo path>\nEvidence: /tmp/chorus-review/<task-uuid>/diff.patch, /tmp/chorus-review/<task-uuid>/log.txt, /tmp/chorus-review/<task-uuid>/tests.txt",
)

Reviewer de code (après la dernière tâche de l'Idée vérifiée ; VERDICT sur l'idée) :

# Preuves agrégées pour la fonctionnalité entière (<base> = commit avant la première tâche de l'idée)
mkdir -p /tmp/chorus-review/<idea-uuid>
git diff <base>...HEAD > /tmp/chorus-review/<idea-uuid>/diff.patch
git log --oneline <base>..HEAD > /tmp/chorus-review/<idea-uuid>/log.txt
<project test/build command> > /tmp/chorus-review/<idea-uuid>/tests.txt 2>&1

delegate_task(
  goal="[chorus-reviewer:code] Review aggregate code for Chorus idea <idea-uuid> and post one VERDICT comment.",
  context="[chorus-reviewer:code]\nFirst call skill_view(\"chorus:chorus-code-reviewer\") and follow it.\nIdea UUID: <idea-uuid>\nProposal UUID: <proposal-uuid>\nRound: <N> (count prior code-review VERDICT comments on the idea)\nMax review rounds: CHORUS_MAX_CODE_REVIEW_ROUNDS (default 3; 0 = unlimited)\nRepo: <abs repo path>\nEvidence: /tmp/chorus-review/<idea-uuid>/diff.patch, /tmp/chorus-review/<idea-uuid>/log.txt, /tmp/chorus-review/<idea-uuid>/tests.txt",
)

Le hook transform_tool_result du plugin Chorus Hermes ajoute un rappel de cette même forme aux résultats de chorus_pm_submit_proposal (reviewer de propositions), chorus_submit_for_verify (reviewer de tâches), et chorus_admin_verify_task (code reviewer, quand la dernière tâche de l'idée est terminée). Le rappel ne lance jamais le reviewer pour vous.

Workflow

Étape 1 : Check In

chorus_checkin()

Prêtez attention à :

• Nombre de propositions en attente (éléments en attente d'approbation)
• Tâches en statut to_verify (travail en attente de révision)
• Santé globale du projet

Étape 2 : Triage

Vérifiez ce qui a besoin de votre attention :

# Propositions en attente
chorus_get_proposals({ projectUuid: "<project-uuid>", status: "pending" })

# Tâches en attente de vérification
chorus_list_tasks({ projectUuid: "<project-uuid>", status: "to_verify" })

# Activité récente
chorus_get_activity({ projectUuid: "<project-uuid>" })

Priorisez : Propositions en premier (elles débloquent le travail PM et Developer), puis les vérifications de tâches.

Workflow A : Révision de Proposition

A1 : Lire la Proposition

chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "full" })

chorus_get_proposal utilise par défaut section: "basic" — métadonnées de la proposition plus un index léger des brouillons (uuid, type/titre, contentLength, nombre d'AC, arêtes de dépendance) sans contenu de document ni descriptions de tâche complètes. Pour une révision vous avez besoin des corps, donc passez section: "full" pour obtenir tout en une seule fois (ou section: "documents" / section: "tasks" pour lire un type à la fois).

La vue full retourne : titre, description, idées d'entrée, brouillons de document (PRD, tech design), brouillons de tâche (avec descriptions et critères d'acceptation).

A2 : Checklist de Qualité

Documents :

• [ ] PRD décrit clairement le quoi et le pourquoi
• [ ] Les exigences sont spécifiques et testables
• [ ] Le tech design est faisable et suit les conventions du projet
• [ ] Aucun cas limite ou considération de sécurité manquants

Tâches :

• [ ] Les tâches couvrent toutes les exigences du PRD
• [ ] Chaque tâche a des critères d'acceptation clairs
• [ ] Les tâches sont dimensionnées de manière appropriée (1-8 story points)
• [ ] Les descriptions de tâche ont suffisamment de contexte pour un agent developer
• [ ] La priorité est définie correctement

Globalement :

• [ ] La proposition s'aligne avec la(les) idée(s) originale(s)
• [ ] Pas de scope creep au-delà de ce qui a été demandé
• [ ] L'approche d'implémentation est raisonnable

A3 : Lire les Commentaires

chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })

A3.5 : Révision Indépendante

Exécutez chorus-proposal-reviewer selon la Stratégie de Révision ci-dessus — un enfant delegate_task avec le marqueur [chorus-reviewer:proposal] (voir l'exemple reviewer de propositions). L'appel bloque jusqu'à ce qu'il finisse. Lisez son commentaire VERDICT avant de procéder.

A4 : Approuver ou Rejeter

Approuver :

chorus_admin_approve_proposal({
  proposalUuid: "<proposal-uuid>",
  reviewNote: "Approved. Good breakdown of tasks."
})

La réponse inclut materializedTasks et materializedDocuments — utilisez-les pour assigner immédiatement des tâches ou référencer des documents.

Quand approuvée :

• Les brouillons de document deviennent de vrais Documents
• Les brouillons de tâche deviennent de vraies Tâches (statut : open)

Rejeter :

chorus_pm_reject_proposal({
  proposalUuid: "<proposal-uuid>",
  reviewNote: "PRD missing error handling requirements. Task 3 needs clearer AC."
})

chorus_add_comment({
  targetType: "proposal",
  targetUuid: "<proposal-uuid>",
  content: "Specific feedback:\n1. Add error scenarios to PRD\n2. Task 3 AC should include performance benchmarks"
})

Workflow A2 : Révoquer les Propositions Approuvées

Si la direction d'une Proposition approuvée s'avère erronée, utilisez chorus_pm_revoke_proposal pour annuler l'approbation. Contrairement à reject (qui agit sur les propositions en attente), revoke agit sur les propositions déjà approuvées et annule tous les ressources matérialisées.

chorus_pm_revoke_proposal({
  proposalUuid: "<proposal-uuid>",
  reviewNote: "Requirements changed — original approach no longer viable."
})

Effets en cascade : toutes les Tâches matérialisées sont fermées, tous les Documents matérialisés sont supprimés, et les AcceptanceCriteria/TaskDependencies/SessionCheckins associés sont nettoyés. La Proposition retourne au statut draft pour que le PM puisse réviser et resoumettez.

Workflow B : Vérification de Tâche

B1 : Réviser la Tâche Soumise

chorus_get_task({ taskUuid: "<task-uuid>" })

Vérifiez : résumé du travail du developer, critères d'acceptation, résultats d'auto-vérification.

B2 : Lire les Commentaires et Rapports de Travail

chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })

B2.5 : Révision Indépendante

Construisez le bundle de preuves, puis exécutez chorus-task-reviewer selon la Stratégie de Révision ci-dessus — un enfant delegate_task avec le marqueur [chorus-reviewer:task] (voir l'exemple reviewer de tâches). L'appel bloque jusqu'à ce qu'il finisse. Après qu'il se termine, lisez son VERDICT :

• VERDICT: PASS ou PASS WITH NOTES → procédez à B3 (marquer AC) et B4 (vérifier).
• VERDICT: FAIL → passez à B4 et rouvrez la tâche. NE MARQUEZ PAS AC comme passé.

B2.6 : Passerelle Finale de Code-Review (après la DERNIÈRE tâche d'une Idée vérifiée)

Quand la tâche que vous venez de vérifier est la dernière tâche de sa proposition enracinée-idée, exécutez la passerelle de code-review ship-time avant que le code de l'Idée soit considéré comme shipped. Le plugin Chorus Hermes ajoute un rappel au résultat chorus_admin_verify_task pour exécuter chorus-code-reviewer (gatée par CHORUS_ENABLE_CODE_REVIEWER, défaut activé). Construisez le bundle de preuves agrégées et exécutez-le selon la Stratégie de Révision — un enfant delegate_task avec le marqueur [chorus-reviewer:code] (voir l'exemple reviewer de code), en passant ideaUuid + numéro de manche. Il révise le changement de code agrégé de l'Idée à travers toutes ses tâches — intégration cross-tâche, cohérence architecture/convention, sécurité, régression/performance, couverture de test au niveau de la fonctionnalité — des dimensions qu'une révision single-tâche ne peut pas voir — et poste un commentaire VERDICT sur l'idée.

• VERDICT: PASS / PASS WITH NOTES → la fonctionnalité peut être shipée.
• VERDICT: FAIL → ne rouvrez pas les tâches vérifiées ; à la place ajoutez de nouvelles tâches de correction à la proposition approuvée via le skill quick-dev (skill_view("chorus:quick-dev")) (chorus_create_tasks avec proposalUuid défini à la proposition approuvée courante pour que les tâches de correction s'y rattachent). Groupez par défaut les BLOQUEURS petits et liés ; divisez seulement les correctifs matériellement grands ou indépendamment testables. Exigez d'auto-vérification AC, révision de tâche indépendante, et vérification admin pour chaque tâche de correction. Réexécutez l'agrégat de révision uniquement après que chaque correctif soit avec succès done ; un correctif échoué ou annulé arrête la boucle et escalade. Limité par CHORUS_MAX_CODE_REVIEW_ROUNDS (env, défaut 3 ; 0 = illimité).

Consultatif / comportemental — la passerelle ne change pas le statut stocké de l'Idée ; l'admin honore son verdict. Exécutez-la avant d'écrire un rapport de complétion d'idée (le rapport ne doit pas être écrit pendant qu'un FAIL est en attente).

B3 : Marquer les Critères d'Acceptation

Révisez et marquez chaque critère :

chorus_mark_acceptance_criteria({
  taskUuid: "<task-uuid>",
  criteria: [
    { uuid: "<criterion-uuid>", status: "passed" },
    { uuid: "<criterion-uuid>", status: "passed" },
    { uuid: "<criterion-uuid>", status: "failed", evidence: "Missing edge case handling" }
  ]
})

B4 : Vérifier ou Rouvrir

Vérifier (tous les AC requis passés) :

chorus_admin_verify_task({ taskUuid: "<task-uuid>" })

Cela déplace la tâche à done. Important : vérifier peut débloquer des tâches aval. Vérifiez :

chorus_get_unblocked_tasks({ projectUuid: "<project-uuid>" })

Si de nouvelles tâches sont débloquées, assignez-les ou notifiez les developers.

Rouvrir (nécessite des corrections) :

chorus_admin_reopen_task({ taskUuid: "<task-uuid>" })

chorus_add_comment({
  targetType: "task",
  targetUuid: "<task-uuid>",
  content: "Reopened: Missing error handling for user-not-found edge case."
})

La tâche retourne à in_progress. Tous les critères d'acceptation sont réinitialisés.

B5 : Fermer / Supprimer des Tâches

# Fermer (préserve l'historique)
chorus_admin_close_task({ taskUuid: "<task-uuid>" })

# Supprimer (permanent, utilisez avec parcimonie)
chorus_admin_delete_task({ taskUuid: "<task-uuid>" })

Workflow C : Gestion Projet & Idée

Créer un Projet

chorus_get_project_groups()  # Listez les groupes disponibles en premier
chorus_admin_create_project({
  name: "My Project",
  description: "Project goals...",
  groupUuid: "<optional-group-uuid>"
})

Gérer les Groupes de Projets

chorus_admin_create_project_group({ name: "Mobile Apps", description: "All mobile projects" })
chorus_admin_move_project_to_group({ projectUuid: "<uuid>", groupUuid: "<uuid>" })
chorus_admin_move_project_to_group({ projectUuid: "<uuid>", groupUuid: null })  # Dégrouper
chorus_admin_delete_project_group({ groupUuid: "<uuid>" })  # Les projets deviennent non groupés

Fermer / Supprimer des Idées

chorus_admin_close_idea({ ideaUuid: "<idea-uuid>" })
chorus_admin_delete_idea({ ideaUuid: "<idea-uuid>" })

Note : Créer des idées est un outil PM (chorus_pm_create_idea). Voir skill_view("chorus:idea").

Gestion de Documents

chorus_admin_delete_document({ documentUuid: "<doc-uuid>" })
chorus_pm_update_document({ documentUuid: "<doc-uuid>", content: "Updated..." })

Routine Admin Quotidienne

1. Check in — chorus_checkin()
2. Réviser l'activité — chorus_get_activity() pour les événements récents
3. Traiter les propositions — Réviser et approuver/rejeter les propositions en attente
4. Vérifier les tâches — Réviser et vérifier/rouvrir les tâches en to_verify
5. Créer de nouvelles idées — Si l'humain a de nouvelles exigences
6. Vérifier la santé du projet — Tâches obsolètes ? Éléments bloqués ? Idées orphelines ?

Conseils

• Révisez en détail — Ne tamponnez pas les propositions ; vérifiez la qualité
• Donnez un feedback exploitable — Quand vous rejetez, expliquez spécifiquement ce à corriger
• Vérifiez par rapport aux critères — Vérifiez les critères d'acceptation, pas juste le résumé
• Gérez la portée — Fermez les idées et tâches qui ne sont plus pertinentes
• Débloquez l'équipe — Priorisez les révisions de propositions pour que le travail PM et Developer s'écoule
• Utilisez delete avec parcimonie — Préférez fermer à supprimer ; fermer préserve l'historique
• Documentez les décisions — Utilisez les commentaires pour expliquer le raisonnement approbation/rejet
• Vérifiez entre les waves — En mode wave, vérifiez les tâches à done entre les waves pour débloquer les dépendances aval ; delegate_task bloque jusqu'au retour des workers de la wave, donc vérifiez après son retour et fermez chaque session Chorus du worker

Principes de Gouvernance

1. Qualité plutôt que vitesse — Une proposition rejetée maintenant évite du rework plus tard
2. Feedback exploitable — Chaque rejet devrait inclure des corrections spécifiques
3. Vérification basée sur les critères — Vérifiez par rapport aux critères d'acceptation, pas juste l'impression subjective
4. Discipline de portée — Fermez ce qui n'est plus nécessaire, ne laissez pas les éléments orphelins s'accumuler
5. Débloquez les autres — Vos révisions sont le goulot d'étranglement ; priorisez-les
6. Préservez l'historique — Fermer > Supprimer ; commentaires > actions silencieuses
7. Documentez le raisonnement — Les futurs agents liront vos commentaires pour comprendre les décisions

Suivant

• Pour la vue d'ensemble de la plateforme et les outils partagés, voir skill_view("chorus:chorus")
• Pour l'élaboration d'Idée (avant les propositions), voir skill_view("chorus:idea")
• Pour la création de Proposition (ce que vous révisez), voir skill_view("chorus:proposal")
• Pour le workflow Developer (ce que vous vérifiez), voir skill_view("chorus:develop")