multi-evaluator

Loop de melhoria de design com múltiplos avaliadores

Rodadas de revisão independente até o produto estar pronto para pessoas: cada jornada pontua 9 ou melhor de cada revisor, nenhum reparo de alta severidade está em aberto, os revisores concordam dentro de um ponto, e isso se mantém por duas rodadas consecutivas. Um 10 unânime é um sinal para verificar novamente o briefing, não o objetivo. As pontuações de IA são um forte sinal, não uma prova: quando o loop diz pronto, pessoas reais de primeira viagem testam, e onde elas discordam da IA, as pessoas vencem.

Tudo é executado através de uma ferramenta de linha de comando, scripts/eval_loop.py (ao lado deste arquivo), para que uma pessoa, este agente ou qualquer outro agente obtenha os mesmos resultados. Cada comando aceita --dir <pasta de revisão>, e status --json sempre informa onde o loop está e o que fazer em seguida. Requer Python 3.9 ou posterior, Node.js 18 ou posterior e Google Chrome ou Chromium. Nada mais para instalar.

Abaixo, LOOP significa python3 <pasta desta habilidade>/scripts/eval_loop.py.

Antes de começar (toda habilidade mStack)

• Se ~/.mstack/config.json lista multi-evaluator em "disabled", ou a pessoa disse para não usá-lo para esta tarefa, trabalhe da maneira usual.
• Se ~/.mstack/learned/multi-evaluator.md existe, leia-o: ele contém as melhorias aceitas por esta pessoa, e elas prevalecem sobre este arquivo.
• Quando o loop terminar (ou parar), registre em particular como foi: python3 <pasta da habilidade mStack>/scripts/mstack.py log multi-evaluator --outcome reached|partial|not-reached --needed-user "..." --stalled "..." (a habilidade mStack fica ao lado desta).

1. Jornadas e critérios primeiro

Antes de qualquer revisão, combine com a pessoa o que uma pessoa real deve ser capaz de fazer, do início ao fim.

1. LOOP init --dir design-review --name "<produto>" --start "<comando que o inicia, com {port}>" --cwd <sua pasta> (ou --url <endereço> para algo já em execução, como um site de homologação).
2. Preencha design-review/mstack-eval.json com a pessoa. Veja references/config.md para cada campo:
   • about e persona: o que é o produto e quem o julga. Mantenha a direção de design e quaisquer restrições fora de about e em rules: elas são mostradas aos revisores como "não pontuadas", para que o briefing nunca entregue a resposta que você espera ouvir.
   • journeys: 3 a 6 tarefas reais, cada uma do início ao fim ("Adicionar um livro e vê-lo na lista").
   • views: as telas fixas capturadas a cada rodada (desktop, celular, tema escuro). Tema claro primeiro.
   • criteria: o piso é limpo, rápido, confiável, familiar, calmo, funciona em todos os lugares. stages adicionam mais critérios à medida que o produto amadurece (tempo de valor, recuperação de erros, texto, experiência do agente, acessibilidade medida, velocidade, teste de cinco segundos, tom emocional, consistência, segurança de dados, encanto). Ative um estágio com "active": true ou "from_round": <n> quando as pontuações mostrarem que o piso foi atingido.
   • reviewers: pelo menos dois, de diferentes fabricantes de IA. O padrão é Claude (executado por você, o agente) e Codex (executado pela ferramenta com codex exec).
   • control: a verificação de ruído (recomendado). A primeira captura congela as telas dessa rodada em control/; cada revisor as pontua a cada rodada como jornada control, e o relatório mostra o quanto essa pontuação mudou. Uma mudança menor que esse movimento é ruído, não progresso.
3. Mostre à pessoa as jornadas e os critérios e obtenha um sim antes da rodada 1.

2. Cada rodada

LOOP start-round --dir design-review          # abre rounds/r<N>/, captura os critérios desta rodada
                                              # escreva rounds/r<N>/changes.md: o que mudou, um item por vez
LOOP capture --dir design-review              # as mesmas telas, capturadas da mesma forma, a cada rodada
LOOP brief --dir design-review                # briefings de pontuação cega em rounds/r<N>/briefs/, mais briefs de comparação a partir da rodada 2
LOOP review --dir design-review               # executa revisores de linha de comando (Codex) em paralelo; execute em segundo plano

Ao mesmo tempo, execute você mesmo cada revisor cujo kind é agent, em contexto novo:

• Claude Code: inicie um subagente (ferramenta Agente, propósito geral) cujo prompt seja o texto completo de rounds/r<N>/briefs/claude.md. Não adicione suas próprias opiniões, a resposta esperada ou pontuações anteriores.
• Qualquer outro agente: abra uma nova sessão ou thread com o briefing como a única instrução.
• Um revisor de kind: "chat" (opcional, opt-in: Grok, ChatGPT ou Gemini no próprio navegador logado da pessoa, sem chave de API): somente com o sim da pessoa sobre o que pode ser compartilhado, abra um novo chat privado, cole rounds/r<N>/briefs/<id>.md, faça upload das telas fixas desta rodada se o produto não for público, salve a resposta, feche a aba, então verdict. Ele vê capturas de tela, não o produto ao vivo, então é um desempatador: nunca conta para "pronto para pessoas" e nunca pode ser o único revisor.

Quando ele responder, salve seu JSON (a ferramenta verifica e recusa uma resposta que não se encaixa no formato):

LOOP verdict --dir design-review --reviewer claude reply.json      # ou pipe a resposta com -

Cego primeiro, comparação depois. O briefing de pontuação mostra apenas esta rodada: sem capturas de tela anteriores, sem pontuações anteriores, sem direção de design, para que a pontuação signifique a mesma coisa na rodada 1 e na rodada 9. A partir da rodada 2, há também rounds/r<N>/briefs/<revisor>-compare.md. Dê ao mesmo revisor após seu veredito ser salvo (a mesma sessão é suficiente; não é mais cega), e salve a resposta separadamente da pontuação:

LOOP verdict --dir design-review --reviewer claude --compare compare-reply.json
LOOP report --dir design-review                                     # escreve design-review/report.html

A comparação nunca altera uma pontuação; o relatório a mostra em "O que mudou".

Em seguida, mostre à pessoa o relatório e as capturas de tela do tema claro (rounds/r<N>/shots/). Envie a ela uma notificação se seu agente puder (no Claude Code, PushNotification) quando o relatório de uma rodada estiver pronto ou o loop precisar de uma decisão; o comando notify da configuração também pode enviar uma (veja references/config.md).

3. Corrigir, depois repetir

1. Comece pela lista Faça estes a seguir do relatório (correções em uma jornada que todos os revisores sinalizaram primeiro, depois alta severidade, depois a maior lacuna "se corrigido"). Onde a tabela de jornadas disser que os revisores discordam em 2 ou mais, examine você mesmo essa jornada antes de agir em qualquer uma das pontuações.
2. Faça as correções no produto, execute seus próprios testes e escreva o changes.md da próxima rodada.
3. LOOP start-round, e repita até que LOOP status diga pronto para pessoas (a regra de parada acima, mantida por duas rodadas). Se uma rodada passar, não mude nada grande e execute mais uma para que se mantenha. Após max_rounds (padrão 6) sem atingi-lo, status diz para parar e conversar com a pessoa: as jornadas ou critérios podem estar pedindo algo que o produto não deve fazer.
4. Então pessoas reais: cinco usuários de primeira viagem tentam as jornadas sem ajuda. Registre seu tempo, tropeços e palavras em rounds/r<N>/people.md (um item cada; o relatório os mostra). Onde eles discordarem dos revisores de IA, as pessoas vencem: transforme o que encontraram em jornadas ou critérios para a próxima rodada.

Regras

• Os revisores nunca veem os vereditos uns dos outros, rodadas anteriores, pontuações anteriores ou o relatório enquanto pontuam; o briefing informa isso. A comparação com a rodada anterior é uma passagem separada, após o veredito.
• As mesmas visualizações, capturadas da mesma forma, a cada rodada, para que antes e depois comparem de forma equivalente.
• Nunca deixe um revisor enviar pagamentos reais, mensagens ou dados pessoais. Use dados de demonstração e uma cópia nova.
• Revisores em sandbox (Codex) não podem iniciar o Chrome: review inicia um Chrome headless compartilhado e o briefing diz a eles para colocar MSTACK_CDP_PORT=<port> na frente do comando do driver.
• Se a resposta de um revisor não se encaixar, leia rounds/r<N>/work/<revisor>/raw-reply.txt, então execute novamente. A ferramenta recusa um 10 que ainda propõe correções e um "se corrigido" abaixo da pontuação.
• Mantenha a pasta de revisão no repositório do produto (ou ao lado dele) para que cada rodada seja mantida.

Arquivos

• scripts/eval_loop.py: a ferramenta de linha de comando (init, status, start-round, capture, brief, serve, review, verdict, validate, report, notify).
• scripts/drive.mjs: o driver de jornada, um Chrome headless real; os revisores o usam diretamente.
• scripts/report.py: o construtor de relatórios. scripts/readiness.py: a regra de parada e a verificação de ruído.
• templates/mstack-eval.json: a configuração inicial.
• references/config.md: todos os campos de configuração. references/verdict-format.md: o formato da resposta. references/method.md: por que o loop funciona desta forma e como os critérios crescem.