Revisão de Pesquisa (Revisões Modulares & Combinadas)

O que Revisão de Pesquisa (Revisões Modulares & Combinadas) faz?

Plano, Código e Teste podem ser executados de forma independente ou combinada:

• Se você apenas planejou, execute o Modo A (Revisão de Plano).
• Se você escreveu código e imediatamente escreveu/executou testes (fluxo natural), execute o Modo B+C Combinado (Revisão Conjunta de Código e Teste) em uma única rodada de revisão paralela — não perca tempo criando duas rodadas de revisão separadas consecutivas.
• Se você escreveu apenas código sem testes, ou apenas escreveu/executou testes para código existente, execute o Modo B ou Modo C de forma independente.

1. Despacho de Subagente Revisor (spawn_subagent)

• Revisores Padrão (channel=mcli): Chame spawn_subagent concorrentemente para lançar dois revisores paralelos e aguarde ambos via get_command_or_subagent_output:
  • Subagente 1: model: "deepseek-v4.1-flash" (canal mcli)
  • Subagente 2: model: "glm-5.3" (canal mcli)
• Substituição pelo Usuário: Se o usuário especificar outros modelos (ex.: kimi-k3.1-pro, MiniMax-M3.1-Flash, deepseek-v4-pro, ou slugs friday/* / catpaw-ide/*), passe as slugs de model especificadas pelo usuário para spawn_subagent.
• Fechamento Incremental (resume_from) :
  • Descoberta (Rodada 1): Crie subagentes novos com apenas o artefato mínimo (Plano, git diff, código de teste + stdout/stderr de execução) e caminhos de arquivo chave — nunca passe seu histórico de conversa.
  • Fechamento (Rodada 2+, se correções ou testes extras foram necessários): Chame spawn_subagent com resume_from: "<subagent_id>" para cada revisor, passando apenas os achados ativos e o delta de correção/teste para que verifiquem a atualização sem reler arquivos não alterados.

2. Limites de Papéis Principais

1. O Agente Principal Executa Validação Primeiro: É recomendável executar um teste rápido de sintaxe/smoke antes de despachar revisores, para que estes não desperdicem esforço em sintaxe quebrada. Passe seu comando de teste exato e saída como Evidência de validação do agente principal.
2. Revisores Estritamente Somente Leitura: Instrua os subagentes revisores a apenas ler/fazer grep em arquivos, relatar achados ordenados por severidade com evidências de arquivo:linha e emitir - Solicitação de validação: <verificação exata> quando um caso de borda não testado precisar de prova em tempo de execução. Os revisores nunca editam arquivos ou executam comandos.
3. Adjudicação pelo Agente Principal: Aguarde que todos os revisores lançados terminem antes de editar. Reproduza bugs candidatos de forma independente, execute Solicitações de validação válidas e adjudique (aceito / rejeitado) com evidências concretas de código ou matemática.

---

Modo A: Revisão de Plano (Independente)

1. Prepare: Declare o objetivo, arquivos a serem modificados, formas de tensor / fluxo de dados e premissas explícitas (qualquer escolha não declarada que afete semântica de treinamento, escala de recompensa ou justiça de linha de base).
2. Instrua os Revisores:

   "Revisão somente leitura deste plano de pesquisa. Não edite arquivos nem execute comandos. Desafie premissas não declaradas, verifique vazamento de dados/rótulos, injustiça de linha de base e gargalos distribuídos/rollout. Declare Cobertura da revisão: TOTAL|PARCIAL - <arquivos inspecionados> e termine com Veredito da revisão: APROVADO|ACHADOS. [Insira o Plano e Caminhos de Arquivo Chave]"

Modo B: Revisão de Código (Independente — quando ainda não foi escrito teste)

1. Prepare: Colete o resumo de requisitos/plano e o git diff.
2. Instrua os Revisores: Instrua-os a inspecionar arquivos alterados e chamadores de um salto somente leitura em busca de bugs silenciosos de pesquisa:
   • Mascaramento e Alinhamento: Erros de deslocamento de máscara de token de prompt vs. resposta em SFT/RL, incompatibilidades de lado de preenchimento, ou manipulação de EOS/truncamento.
   • Formas de Tensor e Broadcasting: Broadcasting não intencional (ex.: (B, 1) vs (B,)), erros de dimensão de redução (mean/sum sobre sequência vs. lote).
   • Higiene de Gradiente e Estado: detach()/no_grad() mal colocado, direção de KL, escopo de normalização de vantagem, ou estado de ambiente do agente não redefinido entre rollouts.
   • Exija Cobertura da revisão e Veredito da revisão: APROVADO|ACHADOS.

Modo C: Revisão de Teste (Independente — ao adicionar/auditar testes para código existente)

1. Prepare: Colete o caminho do arquivo de teste, o caminho do módulo alvo e o stdout/stderr real da execução do teste.
2. Instrua os Revisores:

   "Auditoria somente leitura deste teste e sua saída de execução. Não edite arquivos nem execute comandos. Ele realmente verificou os invariantes matemáticos/de tensor principais e casos de borda, ou ele zombou (mockou) da lógica real / enfraqueceu asserções para passar? Emita - Solicitação de validação: ... se um caso de borda não for testado. Declare Cobertura da revisão e termine com Veredito da revisão: APROVADO|ACHADOS."

Modo B+C: Revisão Conjunta de Código e Teste (Quando o Agente Principal codificou e testou a si mesmo de uma só vez)

1. Prepare: Empacote o resumo de requisitos/plano, o git diff de implementação + teste e a Evidência de validação do agente principal (comando de teste exato executado e seu stdout/stderr).
2. Instrua os Revisores:

   "Revisão conjunta somente leitura do diff de implementação e do auto-teste do Agente Principal. Não edite arquivos nem execute comandos.

   1. Verificação de Código: Procure por bugs silenciosos de pesquisa em arquivos alterados e chamadores de um salto (deslocamento de máscara de token, alinhamento de preenchimento/EOS, broadcasting não intencional de tensor (B,1) vs (B,), dim de redução errada, detach()/no_grad() mal colocado, matemática de KL/vantagem, estado de rollout não redefinido).
   2. Auditoria de Auto-Teste: Verifique se o teste do Agente Principal realmente verifica esses invariantes e casos de borda, ou se sofre de viés de confirmação (testando apenas caminhos felizes, zombando da lógica principal, ou asserções fracas). Emita - Solicitação de validação: <verificação exata> para qualquer caso de teste de borda ausente. Declare Cobertura da revisão: TOTAL|PARCIAL - <arquivos inspecionados> e termine com Veredito da revisão: APROVADO|ACHADOS."

3. Adjudique e Feche: Corrija bugs de código aceitos e atenda às Solicitações de validação válidas; se alterações não triviais foram feitas, use resume_from em ambos os revisores para verificar o delta.

---

3. Registro Leve (docs/review-log.md)

Após cada gate de revisão ser concluído, anexe uma entrada concisa de 5 a 10 linhas em inglês a docs/review-log.md no projeto atual (crie o arquivo se ausente). Isso preserva handles subagent_id entre compactações de contexto e mantém uma trilha de auditoria experimental:

## [YYYY-MM-DD] <Título Curto da Tarefa> (<Modo A / B / C / B+C>)
- **Premissas / Escopo**: <resumo de 1 linha das principais premissas de design e arquivos tocados>
- **Revisores**: `deepseek-v4.1-flash` (`id: <subagent_id>`), `glm-5.3` (`id: <subagent_id>`)
- **Adjudicação**:
  - `[ACEITO]` `<arquivo:linha>` — <resumo conciso do bug/defeito e como foi corrigido>
  - `[REJEITADO]` `<arquivo:linha>` — <por que o achado do revisor foi um falso positivo, com evidência de matemática/código>
- **Veredito e Prova**: `APROVADO` (<resultado de verificação de teste/smoke em 1 linha>)