• Defino o problema em termos observáveis: o que falhou, sob quais condições, qual o impacto esperado e qual comportamento foi observado.
• Crio um passo a passo de reprodução: ambiente, entradas, sequenciamento de ações e resultados esperados vs. reais.
• Formulo hipóteses de causas raízes com base nas evidências disponíveis (logs, traces, testes) e priorizo pela probabilidade e impacto.
• Defino critérios de validação: como vou confirmar que a correção resolve o problema sem introduzir regressões.

Guio a revisão com foco em evidências concretas, evitando conjecturas sem apoio. A clareza do que foi observado facilita decisões rápidas e seguras.

• Verificação de determinismo: identifique dependências de tempo, concorrência e estados mutáveis que podem gerar comportamento não reprodutível.
• Isolamento de efeitos colaterais: minimize mudanças simultâneas para localizar a origem com clareza (por exemplo, focando em uma função por vez).
• Observabilidade estruturada: padronize logs com contexto ( IDs de request, usuário, sessão) para facilitar a correção.
• Avaliação de integrações: revise contratos de API, validações de entrada/saída e cenários de erro para evitar falhas silenciosas.

Aplique a prática de dividir problemas complexos em hipóteses menores e valide cada uma com evidências diretas antes de prosseguir.

// Versão problemática (comuns armadilhas em code reviews)
async function fetchAll(ids: string[]): Promise<string[]> > {
  const results: string[] = [];
  ids.forEach(async (id) => {
    const r = await fetch(`/api/item/${id}`);
    results.push(await r.text());
  });
  return results;
}

// Correção: usar Promise.all para manter ordem e sincronizar
async function fetchAllFixed(ids: string[]): Promise<string[]> > {
  const promises = ids.map(async (id) => {
    const r = await fetch(`/api/item/${id}`);
    return r.text();
  });
  return Promise.all(promises);
}
      

Observação: a versão problemática pode retornar um array vazio ou com dados fora de ordem, pois o forEach com função assíncrona não espera as operações internas.

• Documente o problema com passos reproduzíveis, ambiente, versões e logs relevantes.
• Inclua evidências visuais: trechos de código, mensagens de erro, stack traces e resultados de testes.
• Seja objetivo: indique o impacto, a prioridade e proponha uma correção com justificativa clara.
• SoliciteClarificações quando necessário: pergunte sobre intenções de design, limites de entradas e comportamentos esperados.

Comentários devem ser construtivos, específicos e orientados a soluções, evitando julgamentos sobre o código ou a pessoa.

• Checklist de revisão: comportamento esperado, edge cases, performance, segurança, acessibilidade e contratos de API.
• Testes para regressão: adicione ou ajuste casos de teste que assegurem que a falha não volte a ocorrer.
• Determinismo em testes: evite dependências externas não controladas; utilize dados de teste estáveis e previsíveis.
• Padronização de padrões de código: revise naming, validação de entradas, tratamento de erros e segura gestão de resources.

A soma de revisões bem fundamentadas, testes consistentes e padrões claros reduz o tempo de entrega e aumenta a confiança na qualidade.