Junghyeon0710/design-review

Lisez .codex/docs/codex-runtime.md avant d'utiliser ce workflow. Suivez l'autorisation de l'utilisateur actuel et les permissions de l'hôte.

Arguments : [path-to-design-doc] [--review full|lean|solo]

Avant de continuer, exécutez cette commande de configuration depuis la racine du projet :

bash ".codex/hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,system_overrides

Résolvez en utilisant la commande ci-dessus – utilisez-la telle quelle ; --review remplace review_mode. --depth est l'ancien nom (pré-1.1) pour le même indicateur : traitez --depth <mode> exactement comme --review <mode>, et dites une fois qu'il a été renommé. Si les deux sont fournis, --review gagne et --depth est ignoré – dites-le. Pas de bloc → valeurs par défaut dans .codex/docs/config-resolution.md.

Revue de conception

Phase 0 : Analyse des arguments

Voir .codex/docs/director-gates.md pour le modèle de vérification complet. Les définitions de chaque porte se trouvent dans .codex/docs/director-gates/[gate-id].md – l'agent créé lit son propre fichier de porte ; ne le lisez pas dans la session parente.

Chaque appel request_user_input suit .codex/docs/automation-modes.md (collaboratif demande toujours · guidé majeur uniquement · autonome enregistre et continue ; les catégories automation_always_ask demandent toujours un avis).

workflow pour le GDD en cours de revue – utilisez la ligne system_overrides pour <system> si le bloc en liste une, sinon la valeur du projet. La portée de la validation suit le niveau :

• full – les 8 sections sont validées ; toute section manquante bloque l'approbation.
• standard – les 5 sections obligatoires (Aperçu, Règles détaillées, Cas limites, Dépendances, Critères d'acceptation) bloquent si manquantes ; la section Formules ne bloque que lorsque le système définit des règles numériques (taux, courbes, seuils, coûts – la catégorie est un indice, pas le test) ; Fantaisie du joueur et Boutons de réglage sont consultatifs (avertir, ne jamais bloquer) sauf si workflow_overrides les exige.
• minimal – aucun GDD n'est attendu ; s'il en existe un, validez les 5 sections standard à titre consultatif.

Le mode résolu contrôle le degré de détail de cette revue :

• full : Revue complète – toutes les phases + délégation à des agents spécialistes (Phase 3b)
• lean : Toutes les phases, sans agents spécialistes – analyse plus rapide en session unique
• solo : Phases 1 à 4 uniquement, pas de délégation, pas d'invite de phase 5 – à utiliser lorsqu'elle est appelée depuis une autre compétence

---

Phase 1 : Chargement des documents

Vérification de fraîcheur d'abord – une re-revue d'un document inchangé coûte le prix plein et reproduit le même verdict. Exécutez :

Bash: bash .codex/scripts/review-receipts.sh check "design/gdd/reviews/[doc-name]-review-log.md" "[target-doc-path]" "design/registry/entities.yaml" ".agents/skills/design-review/SKILL.md"

Le registre est dans la vérification car cette revue le consulte pour des faits interdépendants – un GDD inchangé examiné par rapport à un registre modifié peut aboutir à des conclusions différentes, donc le saut n'est sûr que lorsque chaque ligne indique INCHANGÉ (un registre qui n'a jamais existé n'apparaît pas dans la sortie et ne bloque pas le saut). Le fichier de cette compétence y est car une compétence modifiée entraîne une revue différente. La vérification compare également chaque autre fichier que le journal horodate – les GDD associés, les fichiers de concept ou de résumé et de narration lus lors des revues précédentes – et imprime MANQUANT: pour celui qui n'existe plus.

Lisez ensuite la ligne Mode de revue : de l'entrée la plus récente. Cette revue couvre cette exécution uniquement si son mode est identique ou plus profond que le mode résolu maintenant (full > lean > solo) et si son workflow est identique ou plus profond (full > standard > minimal). Une entrée sans la ligne a été écrite avant qu'elle n'existe et ne couvre rien.

• Tout INCHANGÉ et la dernière entrée du journal porte un verdict – affichez-le : "Ce document est octet-identique à sa dernière revue du [date] ([mode] review, verdict : [verdict])." Si ce verdict était APPROUVÉ et que cette revue couvre cette exécution, proposez via request_user_input : [A] Utiliser le verdict précédent (Recommandé) / [B] Re-revuer quand même – guided procède avec [A] et le note ; autonomous enregistre via log_decision et utilise le verdict précédent. Si c'était APPROUVÉ mais que la revue demandée maintenant est plus profonde que celle enregistrée, dites-le – "C'était une revue [mode] au niveau de workflow [tier] ; cette exécution demande [mode] à [tier]." – et proposez [A] Re-revuer à [mode] (Recommandé) / [B] Utiliser le verdict [mode] précédent ; guided et autonomous re-revoient (autonomous enregistre via log_decision). Si c'était NÉCESSITE DES RÉVISIONS ou RÉVISIONS MAJEURES NÉCESSAIRES, dites-le clairement : le document n'a pas changé depuis qu'il a échoué à la revue – les conclusions précédentes tiennent ; la révision du document est la prochaine étape, pas une re-revue. Proposez d'afficher les conclusions précédentes à partir du journal.
• Le document cible et le fichier de cette compétence INCHANGÉ, et seul le registre ou un autre fichier inter-document horodaté a MODIFIÉ, NOUVEAU ou MANQUANT – le verdict précédent tient à l'exception des faits inter-documents : re-vérifiez les valeurs du document par rapport aux fichiers modifiés et réémettez le verdict ; passez à une re-revue complète en cas de conflit ou si cette revue ne couvre pas cette exécution.
• Document cible ou fichier de cette compétence MODIFIÉ ou NOUVEAU, ou REÇU : AUCUN – procédez à la revue complète ci-dessous. Ne proposez pas de re-revue partielle/différentielle qui saute la lecture ou la réanalyse des sections inchangées. Une re-revue par section néglige des défauts qu'une revue complète trouve, et économise peu ou rien. "Inchangé depuis la dernière revue" signifie seulement octet-identique à ce qui a été examiné alors – cela ne dit rien sur le fait que ce passage précédent était lui-même complet, et l'attention se concentre sur le changement signalé même sous une instruction de tout analyser de toute façon.

Lisez le document de conception cible en entier. Cette étape nécessite l'intégralité du GDD : lisez-le par plages en fonction de ses titres (trouvés avec l'outil Grep : motif ^#, mode contenu), car une lecture de fichier entier de plus de 40 Ko est refusée. Lisez AGENTS.md pour comprendre le contexte et les normes du projet.

Pour les faits inter-documents, préférez le registre aux GDD frères. Si design/registry/entities.yaml existe et liste des entrées pour ce système, faites un grep dessus – ce sont les faits établis que ce GDD ne doit pas contredire, et ils remplacent la lecture des GDD frères pour les redécouvrir :

Grep motif="source: design/gdd/[system].md" chemin="design/registry/entities.yaml" mode_sortie="content" -A 6
Grep motif="design/gdd/[system].md" chemin="design/registry/entities.yaml" mode_sortie="content" -B 8

Le premier trouve les entrées que ce système possède – le contexte -A 6 inclut leur bloc referenced_by:. Le second trouve les entrées qui référencent ce système – referenced_by: est une séquence de blocs (la clé et ses chemins sont sur des lignes séparées), donc faites correspondre le chemin avec le contexte -B 8 pour voir l'entrée propriétaire, pas une ligne unique referenced_by.*name (qui ne correspond jamais à la forme de bloc).

Si design/registry/entities.yaml n'existe pas, ou ne liste aucune entrée pour ce système – le fichier est livré comme un stub vide, c'est donc la valeur par défaut jusqu'à ce que $design-system l'ait rempli – repliez-vous sur la lecture des GDD associés que le document cible nomme dans sa section Dépendances. Limitez la lecture à ceux-ci, pas à tout ce qui est "implicite". Ne lisez pas tous les fichiers de design/gdd/ par glob.

Validation du graphe de dépendances : Pour chaque système listé dans la section Dépendances, utilisez Glob pour vérifier si son fichier GDD existe dans design/gdd/. Signalez tout fichier qui n'existe pas encore – ce sont des références cassées que les auteurs en aval rencontreront.

Alignement lore/narratif : Si design/gdd/game-concept.md (ou, à rigor: minimal, le résumé d'une page design/game-brief.md) ou tout fichier dans design/narrative/ existe, lisez-le. Notez tout choix mécanique dans ce GDD qui contredit les règles du monde établies, le ton ou les piliers de conception. Passez ce contexte à game-designer dans la Phase 3b.

Vérification de la revue précédente : Vérifiez si design/gdd/reviews/[doc-name]-review-log.md existe. Si c'est le cas, lisez l'entrée la plus récente – notez le verdict donné et les éléments bloquants listés. Cette session est une re-revue ; suivez si les éléments précédents ont été traités.

---

Phase 2 : Vérification de complétude

Étape 2a – collectez la présence des sections de manière déterministe (sans lecture du document) :

Bash: bash .codex/scripts/gdd-structure-check.sh [target-doc-path]

Il imprime une liste PRÉSENT : et, le cas échéant, une liste ABSENT : et une liste ESPACE RÉSERVÉ : (sections présentes ne contenant que [À concevoir] : pas encore écrites, traitez-les donc comme manquantes pour la liste de contrôle). Il rapporte uniquement la présence et ne porte pas de jugement OBLIGATOIRE/CONSULTATIF – c'est le travail de l'Étape 2b. Il accepte déjà ## Conception détaillée comme satisfaisant l'exigence de Règles détaillées, donc ne le signalez pas comme manquant.

Étape 2b – appliquez le niveau. À l'aide des listes de l'Étape 2a, évaluez par rapport à la liste de contrôle du standard des documents de conception ci-dessous. Marquez chaque section comme OBLIGATOIRE ou CONSULTATIF selon le niveau de workflow résolu (Phase 0). Une section OBLIGATOIRE manquante bloque l'approbation ; une section CONSULTATIVE manquante est signalée comme une recommandation mais ne bloque pas.

Une section rapportée PRÉSENTE peut encore échouer à la revue s'il s'agit d'un titre vide – lisez rapidement toute section dont dépend réellement le verdict.

• A une section Aperçu (résumé d'un paragraphe) – OBLIGATOIRE à tous les niveaux
• A une section Fantaisie du joueur (ressenti visé) – OBLIGATOIRE à full ; CONSULTATIF à standard
• A une section Règles détaillées (mécaniques sans ambiguïté) – OBLIGATOIRE à full/standard. Le modèle GDD intitule cette section ## Conception détaillée (elle comporte des sous-titres Règles de base / États / Interactions) ; acceptez l'un ou l'autre titre comme satisfaisant cette exigence – ne signalez pas "Règles détaillées" comme manquant lorsqu'une section ## Conception détaillée est présente.
• A une section Formules (tous les calculs mathématiques définis avec des variables) – OBLIGATOIRE à full ; à standard OBLIGATOIRE chaque fois que le système définit des règles numériques (taux, courbes, seuils, coûts, dégâts, poids de butin), sinon CONSULTATIF. La Catégorie du système est un indice, pas le test – ne validez pas cela sur un seul token de catégorie
• A une section Cas limites (situations inhabituelles traitées) – OBLIGATOIRE à full/standard
• A une section Dépendances (autres systèmes listés) – OBLIGATOIRE à full/standard
• A une section Boutons de réglage (valeurs configurables identifiées) – OBLIGATOIRE à full ; CONSULTATIF à standard sauf si workflow_overrides.tuning_knobs
• A une section Critères d'acceptation (conditions de succès testables) – OBLIGATOIRE à full/standard

---

Phase 3 : Cohérence et faisabilité

Cohérence interne :

• Les formules produisent-elles des valeurs qui correspondent au comportement décrit ?
• Les cas limites contredisent-ils les règles principales ?
• Les dépendances sont-elles bidirectionnelles (l'autre système connaît-il celui-ci) ?

Faisabilité :

• Les règles sont-elles suffisamment précises pour qu'un programmeur puisse les implémenter sans deviner ?
• Y a-t-il des sections "floues" où les détails manquent ?
• Les implications de performance sont-elles prises en compte ?
• Chaque critère d'acceptation est-il testable indépendamment ? Signalez chacun qui ne l'est pas, en le citant – "semble équilibré", "fonctionne correctement", "performant bien" ne sont pas des critères – avec une reformulation mesurable. En mode full, qa-lead les vérifie également (Phase 3b) ; en mode lean et solo, aucun spécialiste ne s'exécute, donc cette vérification de la revue principale est la seule.

Cohérence inter-systèmes :

• Cela entre-t-il en conflit avec une mécanique existante ?
• Cela crée-t-il des interactions non intentionnelles avec d'autres systèmes ?
• Cela est-il cohérent avec le ton et les piliers établis du jeu ?

Valeurs du registre, partout où le GDD les énonce. Une valeur reformulée dans un tableau, une entrée de catalogue ou une note de variante contredit le registre aussi sûrement qu'une dans Règles détaillées, et la lecture par section rend ces corps faciles à survoler. Listez les noms d'entrées du registre (grep -E '^ - name:' design/registry/entities.yaml), puis recherchez le document cible entier une fois pour tous ceux-ci plus les clés numériques qu'ils portent, sans tenir compte de la casse, en écrivant chaque _ comme [_ ] pour que goblin_scout corresponde également à "Goblin scouts" :

grep -n -i -E 'goblin[_ ]scout|iron[_ ]sword|health|value[_ ]gold' [target-doc-path]

Vérifiez chaque ligne qu'il imprime par rapport au registre, quelle que soit la section dans laquelle elle se trouve. Une ligne qui donne à une entrée une valeur différente, même pour une pièce, une variante, un niveau ou une exception, contredit le GDD propriétaire : listez-la sous Requis avant implémentation avec son numéro de ligne, la valeur de ce document et celle du registre. Sans entrées de registre, exécutez la même recherche pour les entités et les valeurs que les GDD associés définissent.

---

Phase 3b : Revue spécialisée contradictoire (mode full uniquement)

Ignorer cette phase en mode lean ou solo.

Cette phase est OBLIGATOIRE en mode full. Ne l'ignorez pas.

Avant de créer des agents, imprimez cet avis :

"Revue complète : création d'agents spécialistes en parallèle. Cela prend généralement 8 à 15 minutes. Utilisez --review lean pour une analyse plus rapide en session unique."

Étape 1 – Identifiez tous les domaines touchés par le GDD

En utilisant le GDD déjà chargé dans la Phase 1 – ne le relisez pas – identifiez chaque domaine présent. Un GDD peut toucher plusieurs domaines simultanément – soyez minutieux. Signaux courants :

Si le GDD contient...	Créez ces agents
Coûts, prix, butins, récompenses, économie	economy-designer
Statistiques de combat, dégâts, santé, DPS	game-designer, systems-designer
Comportement IA, pathfinding, ciblage	ai-programmer
Disposition des niveaux, apparitions, structure de vagues	level-designer
Progression du joueur, XP, déblocages	economy-designer, game-designer
UI, HUD, menus, affichages côté joueur	ux-designer, ui-programmer
Dialogues, quêtes, histoire, lore	narrative-director
Animation, ressenti, timing, "juice"	gameplay-programmer
Multijoueur, synchronisation, réplication	network-programmer
Signaux audio, déclencheurs musicaux	audio-director
Performance, appels de rendu, mémoire	performance-analyst
Modèles ou API spécifiques au moteur	Spécialiste du moteur principal (<engine>-specialist depuis engine.name – Godot→godot-specialist, Unity→unity-specialist, Unreal→unreal-specialist ; repli sur la ligne Primitif de ## Spécialistes du moteur dans

…

[Tronqué pour la traduction]