Junghyeon0710/revisão-de-design

Leia .codex/docs/codex-runtime.md antes de usar este fluxo de trabalho. Siga a autorização do utilizador atual e as permissões do host.

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

Antes de prosseguir, execute este comando de configuração a partir da raiz do projeto:

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

Resolva usando o comando acima — use como está; --review substitui review_mode. --depth é o nome pré-1.1 para o mesmo sinalizador: trate --depth <modo> exatamente como --review <modo>, e diga uma vez que foi renomeado. Dados ambos, --review ganha e --depth é ignorado — diga isso. Sem bloco → padrões em .codex/docs/config-resolution.md.

Revisão de Design

Fase 0: Analisar Argumentos

Consulte .codex/docs/director-gates.md para o padrão de verificação completo. As definições de gate individuais residem em .codex/docs/director-gates/[gate-id].md — o agente gerado lê o seu próprio ficheiro de gate; não o leia na sessão pai.

Cada chamada request_user_input segue .codex/docs/automation-modes.md (colaborativo pergunta sempre · guiado apenas principal · autónomo regista e prossegue; as categorias automation_always_ask sempre solicitam).

workflow para o GDD em revisão — use a linha system_overrides para <system> se o bloco listar uma, senão o valor do projeto. O âmbito de validação segue o nível:

• full — todas as 8 secções validadas; qualquer secção em falta bloqueia a aprovação.
• standard — as 5 secções obrigatórias (Visão Geral, Regras Detalhadas, Casos Limite, Dependências, Critérios de Aceitação) bloqueiam se faltarem; Fórmulas bloqueia apenas quando o sistema define regras numéricas (taxas, curvas, limites, custos — a categoria é uma dica, não o teste); Fantasia do Jogador e Alavancas de Ajuste são consultivas (avisar, nunca bloquear) a menos que workflow_overrides as exijam.
• minimal — nenhum GDD é esperado; se existir um, valide as 5 secções padrão consultivamente.

O modo resolvido controla o quão aprofundada é esta revisão:

• full: Revisão completa — todas as fases + delegação a agente especialista (Fase 3b)
• lean: Todas as fases, sem agentes especialistas — análise mais rápida, numa única sessão
• solo: Fases 1-4 apenas, sem delegação, sem prompt de próximo passo na Fase 5 — use quando chamado de dentro de outra skill

---

Fase 1: Carregar Documentos

Verificação de frescura primeiro — uma re-revisão de um documento inalterado custa o preço total e reproduz o mesmo veredito. Execute:

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"

O registo está na verificação porque esta revisão o consulta para factos entre documentos — um GDD inalterado revisto contra um registo alterado pode chegar a conclusões diferentes, por isso a omissão só é segura quando cada linha lê UNCHANGED (um registo que nunca existiu não aparece no resultado e não bloqueia a omissão). O ficheiro desta skill está incluído porque uma skill alterada revista de forma diferente. A verificação também compara todos os outros ficheiros que o registo carimba — os GDDs relacionados, ficheiros de conceito ou brief e narrativa que revisões anteriores leram — e imprime GONE: para um que já não existe.

Depois, leia a entrada mais recente na linha Review mode:. Essa revisão cobre esta execução apenas quando o seu modo é igual ou mais profundo do que o modo resolvido agora (full > lean > solo) e o seu fluxo de trabalho é igual ou mais profundo (full > standard > minimal). Uma entrada sem a linha foi escrita antes de ela existir e não cobre nada.

• Tudo UNCHANGED e a entrada mais recente do registo contém um veredito — apresente-o: "Este documento é byte-idêntico à sua última revisão em [data] (revisão [modo], veredito: [veredito])." Se esse veredito foi APROVADO e essa revisão cobre esta execução, ofereça via request_user_input: [A] Usar o veredito anterior (Recomendado) / [B] Re-revisar de qualquer forma — guided prossegue com [A] e regista-o; autonomous regista via log_decision e usa o veredito anterior. Se foi APROVADO mas a revisão agora solicitada é mais profunda do que a registada, diga isso — "Essa foi uma revisão [modo] com fluxo de trabalho [nível]; esta execução solicita [modo] a [nível]." — e ofereça [A] Re-revisar a [modo] (Recomendado) / [B] Usar o veredito [modo] anterior; guided e autonomous re-revisam (autonomous regista via log_decision). Se foi PRECISA DE REVISÃO ou PRECISA DE REVISÃO MAIOR, diga isso claramente: o documento não mudou desde que falhou na revisão — as conclusões anteriores mantêm-se; rever o documento é o próximo passo, não re-revisá-lo. Ofereça para mostrar as conclusões anteriores a partir do registo.
• O documento alvo e o ficheiro desta skill UNCHANGED, e apenas o registo ou outro ficheiro de documento entre ficheiros carimbado CHANGED, NEW ou GONE — o veredito anterior mantém-se exceto para factos entre documentos: re-verifique os valores do documento contra os ficheiros alterados e re-emita o veredito; aumente para uma re-revisão completa se surgir um conflito ou se essa revisão não cobrir esta execução.
• Documento alvo ou ficheiro desta skill CHANGED ou NEW, ou RECEIPT: NONE — prossiga com a revisão completa abaixo. Não ofereça uma re-revisão parcial/delta que salte a leitura ou re-análise de secções inalteradas. Uma re-revisão com âmbito numa secção perde defeitos que uma revisão completa encontra, e economiza pouco ou nada. "Inalterado desde a última revisão" apenas significa byte-idêntico ao que foi revisto então — não diz nada sobre se essa passagem anterior foi ela própria completa, e a atenção estreita-se para a alteração sinalizada mesmo sob uma instrução para verificar tudo de qualquer forma.

Leia o documento de design alvo na íntegra. Este passo precisa do GDD completo: leia-o em intervalos pelos seus cabeçalhos (encontrados com a ferramenta Grep: padrão ^#, modo de conteúdo), já que uma Leitura de ficheiro inteiro superior a 40 KB é recusada. Leia AGENTS.md para compreender o contexto e os padrões do projeto.

Para factos entre documentos, prefira o registo em vez de GDDs irmãos. Se design/registry/entities.yaml existir e listar entradas para este sistema, faça grep — estes são os factos estabelecidos que este GDD não deve contradizer, e eles substituem a leitura de GDDs irmãos para redescobri-los:

Grep pattern="source: design/gdd/[system].md" path="design/registry/entities.yaml" output_mode="content" -A 6
Grep pattern="design/gdd/[system].md" path="design/registry/entities.yaml" output_mode="content" -B 8

O primeiro encontra entradas que este sistema possui — o contexto -A 6 inclui o seu bloco referenced_by:. O segundo encontra entradas que referenciam este sistema — referenced_by: é uma sequência de bloco (a chave e os seus caminhos estão em linhas separadas), por isso corresponda ao caminho com contexto -B 8 para ver a entrada proprietária, não uma linha única referenced_by.*name (que nunca corresponde à forma de bloco).

Se design/registry/entities.yaml não existir, ou não listar nenhuma entrada para este sistema — o ficheiro é enviado como um stub vazio, por isso este é o padrão até $design-system o ter preenchido — recorra à leitura dos GDDs relacionados que o documento alvo nomeia na sua secção de Dependências. Limite a leitura a esses, não a tudo "implícito". Não faça glob reading de todo o design/gdd/.

Validação do grafo de dependências: Para cada sistema listado na secção Dependências, use Glob para verificar se o seu ficheiro GDD existe em design/gdd/. Sinalize qualquer um que ainda não exista — estas são referências quebradas que autores a jusante enfrentarão.

Alinhamento de lore/narrativa: Se design/gdd/game-concept.md (ou, com rigor: minimal, o brief de uma página design/game-brief.md) ou qualquer ficheiro em design/narrative/ existir, leia-o. Note quaisquer escolhas mecânicas neste GDD que contradigam regras de mundo, tom ou pilares de design estabelecidos. Passe este contexto para game-designer na Fase 3b.

Verificação de revisão anterior: Verifique se design/gdd/reviews/[doc-name]-review-log.md existe. Se existir, leia a entrada mais recente — note qual veredito foi dado e quais itens bloqueadores foram listados. Esta sessão é uma re-revisão; acompanhe se os itens anteriores foram resolvidos.

---

Fase 2: Verificação de Completude

Passo 2a — reunir a presença de secções deterministicamente (sem leitura do documento):

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

Imprime uma lista PRESENT: e, quando aplicável, uma lista ABSENT: e uma lista PLACEHOLDER: (secções presentes contendo apenas [Por conceber]: ainda não escritas, por isso trate-as como em falta para a lista de verificação). Relata presença apenas e não faz julgamento OBRIGATÓRIO/CONSULTIVO — essa é a tarefa do Passo 2b. Já aceita ## Detailed Design como satisfazendo o requisito de Detailed Rules, por isso não sinalize isso como em falta.

Passo 2b — aplicar o nível. Usando as listas do Passo 2a, avalie contra a lista de verificação do Padrão de Documento de Design abaixo. Marque cada secção como OBRIGATÓRIA ou CONSULTIVA de acordo com o nível de fluxo de trabalho resolvido (Fase 0). Uma secção OBRIGATÓRIA em falta bloqueia a aprovação; uma secção CONSULTIVA em falta é apresentada como uma recomendação mas não bloqueia.

Uma secção reportada como PRESENTE pode ainda assim falhar na revisão se for um cabeçalho vazio — leia pontualmente qualquer secção da qual o veredito realmente depende.

• Tem secção Visão Geral (resumo de um parágrafo) — OBRIGATÓRIA em todos os níveis
• Tem secção Fantasia do Jogador (sensação pretendida) — OBRIGATÓRIA em full; CONSULTIVA em standard
• Tem secção Regras Detalhadas (mecânicas inequívocas) — OBRIGATÓRIA em full/standard. O modelo GDD intitula esta secção ## Detailed Design (contém sub-cabeçalhos Core Rules / States / Interactions); aceite qualquer cabeçalho como satisfazendo este requisito — não sinalize "Regras Detalhadas" como em falta quando uma secção ## Detailed Design está presente.
• Tem secção Fórmulas (toda a matemática definida com variáveis) — OBRIGATÓRIA em full; em standard OBRIGATÓRIA sempre que o sistema define regras numéricas (taxas, curvas, limites, custos, dano, pesos de drop), senão CONSULTIVA. A Categoria do sistema é uma dica, não o teste — não resolva isto apenas com um token de categoria
• Tem secção Casos Limite (situações invulgares tratadas) — OBRIGATÓRIA em full/standard
• Tem secção Dependências (outros sistemas listados) — OBRIGATÓRIA em full/standard
• Tem secção Alavancas de Ajuste (valores configuráveis identificados) — OBRIGATÓRIA em full; CONSULTIVA em standard a menos que workflow_overrides.tuning_knobs
• Tem secção Critérios de Aceitação (condições de sucesso testáveis) — OBRIGATÓRIA em full/standard

---

Fase 3: Consistência e Implementabilidade

Consistência interna:

• As fórmulas produzem valores que correspondem ao comportamento descrito?
• Os casos limite contradizem as regras principais?
• As dependências são bidirecionais (o outro sistema sabe sobre este)?

Implementabilidade:

• As regras são precisas o suficiente para um programador implementar sem adivinhar?
• Existem secções "vagas" onde faltam detalhes?
• As implicações de desempenho são consideradas?
• Cada critério de aceitação é independentemente testável? Sinalize cada um que não é, citando-o — "parece equilibrado", "funciona corretamente", "tem bom desempenho" não são critérios — com uma reformulação mensurável. Em modo full o qa-lead também os verifica (Fase 3b); em lean e solo nenhum especialista executa, por isso esta verificação da revisão principal é a única.

Consistência entre sistemas:

• Isto entra em conflito com alguma mecânica existente?
• Isto cria interações não intencionais com outros sistemas?
• Isto é consistente com o tom e pilares estabelecidos do jogo?

Valores do registo, onde quer que o GDD os indique. Um valor reafirmado numa tabela, uma entrada de catálogo ou uma nota de variante contradiz o registo tão seguramente quanto um em Regras Detalhadas, e a leitura por secção torna esses corpos fáceis de examinar. Liste os nomes das entradas do registo (grep -E '^ - name:' design/registry/entities.yaml), depois pesquise todo o documento alvo uma vez por todos eles mais as chaves numéricas que carregam, sem distinção de maiúsculas/minúsculas, escrevendo cada _ como [_ ] para que goblin_scout também corresponda a "Goblin scouts":

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

Verifique cada linha que imprime contra o registo, independentemente da secção em que se encontra. Uma linha que dá a uma entrada um valor diferente, mesmo que para uma sala, variante, nível ou exceção, contradiz o GDD proprietário: liste-a sob Requerido Antes da Implementação com o seu número de linha, o valor deste documento e o do registo. Sem entradas de registo, execute a mesma pesquisa para as entidades e valores que os GDDs relacionados definem.

---

Fase 3b: Revisão Adversarial por Especialista (apenas modo full)

Salte esta fase no modo lean ou solo.

Esta fase é OBRIGATÓRIA no modo full. Não a salte.

Antes de gerar qualquer agente, imprima este aviso:

"Revisão completa: gerando agentes especialistas em paralelo. Isto normalmente demora 8–15 minutos. Use --review lean para uma análise mais rápida numa única sessão."

Passo 1 — Identifique todos os domínios que o GDD toca

Usando o GDD já carregado na Fase 1 — não o releia — identifique todos os domínios presentes. Um GDD pode tocar múltiplos domínios simultaneamente — seja minucioso. Sinais comuns:

Se o GDD contém...	Gere estes agentes
Custos, preços, drops, recompensas, economia	economy-designer
Estatísticas de combate, dano, saúde, DPS	game-designer, systems-designer
Comportamento de IA, pathfinding, targeting	ai-programmer
Layout de nível, spawning, estrutura de vagas	level-designer
Progressão do jogador, XP, desbloqueios	economy-designer, game-designer
UI, HUD, menus, ecrãs virados para o jogador	ux-designer, ui-programmer
Diálogo, missões, história, lore	narrative-director
Animação, sensação, timing, juice	gameplay-programmer
Multijogador, sincronização, replicação	network-programmer
Sinais de áudio, gatilhos musicais	audio-director
Desempenho, draw calls, memória	performance-analyst
Padrões ou APIs específicos do motor	Especialista do motor principal (<engine>-specialist de engine.name — Godot→godot-specialist, Unity→unity-specialist, Unreal→unreal-specialist; recorra à linha Primary de ## Engine Specialists em

...