Imported from promovaweb/specsfy (
specialists/specsfy-specialist-debugging/SKILL.md). Install upstream withnpx skills add promovaweb/specsfy --skill specsfy-specialist-debugging. Copyright stays with the author.
Diagnóstico
Quando usar
- Acionar quando houver um comportamento observado divergente do esperado, com ou sem reprodução confiável ainda estabelecida.
- Acionar também para falha intermitente ("flaky"), regressão após deploy ou degradação de performance com sintoma concreto (timeout, erro, lentidão reportada).
- Não acionar para otimizar um sistema que já se comporta corretamente e sem
sintoma: isso é
$specsfy-specialist-observability, que parte de um SLO e não de uma falha. - Combinar com
$specsfy-specialist-observabilityquando o ambiente de produção não expuser sinal suficiente para instrumentar o boundary certo.
No Specsfy
-
Fonte de entrada por fase
- Em
specsfy-02-backlog, leia o item emspecs/backlog/e registre ali as decisões e sinais do especialista, além das dúvidas abertas. - Em
specsfy-03-specifyespecsfy-04-validate, use a spec aberta e devolva a conclusão à seção trabalhada pela fase. - Em
specsfy-05-tasks, ajude a sugerir e sincronizar especialistas e modos entre o cabeçalho, a seção 8 e as tarefas. Só essa fase escreve a seção 14. - Em
specsfy-06-implement, limite-se à tarefa indicada e ao passo carregado.
Nas fases com spec, leia a spec aberta indicada pela skill chamadora ou localizada por
specsfy status. Consulte a linha| Especialistas |, a subseção#### Especialistasem### 8. Plano técnicoe a seção pertinente à fase. Leia também.specsfy/STACK.mde.specsfy/RULES.mdpara reproduzir no ambiente real, não no suposto. - Em
-
Siga o modo indicado na spec ou na tarefa, no formato
Especialista: $specsfy-specialist-debugging. Sem indicação, confirme pelo "Quando usar" acima se existe sintoma observado antes de investigar. -
Devolva a conclusão e as dúvidas abertas no destino indicado no item 1, no próprio backlog, na spec ou na tarefa da fase.
-
Não mude o estado da spec nem marque gate: isso pertence a
$specsfy-03-specify,$specsfy-04-validate,$specsfy-05-taskse$specsfy-06-implement. -
Quando a fase trabalhar o plano técnico ou os testes na spec, registre a reprodução e a causa na seção 8 e o teste que falha sem a correção em
### 12. Plano de testes e rastreabilidade, conforme a seção em trabalho. Se a fase pedir apenas diagnóstico, devolva o achado como dúvida aberta.
Fluxo
- Capturar comportamento esperado, comportamento observado, ambiente exato e o momento/frequência da última ocorrência, sem isso a suposição é chute.
- Construir uma reprodução confiável ou, quando reprodução direta não for viável, um sinal observável e repetível (log, métrica, trace) que correlacione com a falha.
- Reduzir input, componentes envolvidos e janela de tempo até o menor caso que ainda reproduz a falha: cada elemento removido que não muda o resultado é uma variável eliminada da suposição.
- Formular suposições falsificáveis e ordená-las pela facilidade de teste e pela probabilidade dado o sintoma observado, não pela mais interessante.
- Instrumentar o boundary mais discriminante entre as suposições restantes: o ponto onde uma suposição prevê um valor e a outra prevê outro.
- Identificar causa, extensão do impacto (só esse caminho, ou a classe inteira de chamadas) e o mecanismo exato pelo qual ela produz o sintoma.
- Se autorizado a corrigir, aplicar a menor mudança que remove a causa e adicionar teste de regressão que falha sem a correção.
Padrões
- Não alterar mais de uma causa candidata por vez: mudar duas coisas ao mesmo tempo invalida a atribuição de causa quando o sintoma desaparece.
- Separar correlação temporal de causalidade: "começou depois do deploy X" é uma pista, não uma prova, até isolar o mecanismo.
- Preservar comprovação (logs, estado, dump) antes de reiniciar processo ou limpar estado: o ambiente que falhou pode ser irreproduzível depois.
- Comparar ambiente bom e ruim sistematicamente: mesma versão, config, dados, carga e ordem de operações, variando um fator por vez.
- Tratar flakiness como sintoma de concorrência, timing, estado compartilhado ou dependência externa até haver prova do contrário, nunca como "só rodar de novo".
- Remover instrumentação temporária, verbosa ou sensível (dado pessoal, segredo) antes de concluir o diagnóstico.
- Descrever a causa no nível do mecanismo ("a race entre X e Y permite leitura antes da escrita completar"), nunca só no nível do sintoma ("às vezes falha").
Antipadrões
- "Adicionar print e rodar de novo" sem suposição prévia: gera ruído, raramente reduz o espaço de busca e é frequentemente indistinguível de tentativa aleatória.
- Corrigir o primeiro ponto onde o erro aparece, sem verificar se ali é a
origem ou apenas onde o efeito se torna visível (o
NullPointerExceptionraramente surge onde é lançado). - Declarar "corrigido" porque a reprodução manual parou de falhar uma vez, sem reprodução automatizada e determinística, a ausência do sintoma pode ser apenas sorte ou mudança de timing.
- Ignorar teste flaky como "instável, não relacionado" sem investigar: flakiness é comprovação de bug real de concorrência ou estado compartilhado na maioria dos casos, não ruído a suprimir.
Validação
- A reprodução falha de forma determinística antes da correção e passa de forma determinística depois, no mesmo ambiente.
- O teste de regressão adicionado falha pelo motivo correto quando a correção é revertida (não por outro motivo incidental).
- Cenários adjacentes ao caminho corrigido foram verificados quanto a efeito colateral da mudança.
- Existe registro conciso de causa (mecanismo), comprovação que a comprova e prevenção (teste, invariante, alarme) adicionada.
- Não declarar a causa "resolvida" sem essa comprovação: atribuir causa por intuição sem reprodução ou teste de regressão é proibido.
Skills relacionadas
-
$specsfy-specialist-serverreúne logs, serviços e uso de disco em relatórios por host, com coleta somente leitura via Ansible. -
$specsfy-specialist-researchconfirma comportamento externo, errata ou compatibilidade quando a causa depende de documentação primária. -
$specsfy-specialist-observabilitypara instrumentar produção quando o sinal disponível não é suficiente para discriminar suposições e quando o sintoma for degradação sem erro funcional: o diagnóstico de causa raiz aqui pode entregar a esta skill a escolha de qual otimização vale o custo. -
$specsfy-specialist-code-reviewpara revisar a correção e o teste de regressão antes do merge. -
$specsfy-specialist-testingtransforma a causa confirmada em teste de regressão executável, com comando e saída registrados.
Leia references/standards.md para técnicas de reprodução e isolamento, causas comuns de flakiness, ferramentas por ambiente e fontes oficiais.
