diagnose

name	diagnose
description	Aciona um loop disciplinado de RCA para bugs difíceis e regressões (reproduzir -> minimizar -> hipotetizar -> instrumentar -> corrigir -> teste de regressão).
reference	["https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnose"]
tools	["Read","Bash"]
activation_hints	["use diagnose","rodar RCA","analisar causa raiz","bug intermitente","regressao"]

Skill: Diagnose

Mission

Executar RCA com evidência objetiva e trilha auditável, evitando correções por suposição.

When to use

• Pedido explícito de RCA, diagnóstico, debug profundo ou regressão.
• Falha intermitente, multi-fator ou sem causa evidente.
• Regressão de performance com necessidade de baseline e comparação.

Inputs mínimos

• Sintoma observado e comportamento esperado.
• Contexto de reprodução (ambiente, comando, janela temporal).
• Artefatos disponíveis (logs, traces, payloads, screenshots, testes).
• Regras ativas do projeto (RN/RA/RG) quando houver impacto de negócio.

Execution protocol

1. Build feedback loop (obrigatório)

• Criar loop reproduzível antes de qualquer hipótese.
• Ordem preferida:

1. teste falhando no seam correto
2. repro script API/CLI determinístico
3. replay de artefato capturado
4. harness mínimo isolado
5. fuzz/property para falha rara
6. bisseção/diff entre estados
7. HITL script (último recurso)

• Se não houver loop viável, bloquear RCA e pedir insumo faltante ao humano.

1. Reproduce

• Executar loop e confirmar o mesmo modo de falha reportado.
• Registrar evidência concreta (erro, saída incorreta, latência, taxa de repro).

1. Hypothesize

• Formular 3-5 hipóteses falsificáveis e ranqueadas.
• Cada hipótese deve conter predição testável:
  • "Se X for causa, alterar Y produzirá Z".

1. Instrument

• Cada sonda deve mapear para uma hipótese.
• Variar um fator por vez.
• Preferir debugger/REPL e logs cirúrgicos.
• Prefixar logs temporários com tag única (ex.: [DEBUG-RCA-01]).
• Proibido: "log everything and grep".

1. Fix + regression test

• Quando seam for correto:

1. converter repro minimizado em teste falhando
2. confirmar falha
3. aplicar fix
4. confirmar teste passando
5. reexecutar cenário original

• Se seam não for correto, registrar como finding arquitetural.

1. Cleanup + closure

• Remover instrumentação temporária.
• Confirmar que repro original não ocorre.
• Confirmar regressão coberta por teste ou justificar gap.

Davi governance gates

• Decisões de alto impacto exigem aprovação humana.
• Conflito com RN/RA/RG aprovadas deve retornar aos refinadores.
• Mudança que amplia escopo encerra trilha RCA e volta ao gate de especificação.

Output obrigatório

• RCA status: confirmed | not confirmed | blocked
• Sintoma e reprodutibilidade
• Hipóteses ranqueadas e sondas executadas
• Causa raiz confirmada (ou motivo de bloqueio)
• Correção proposta/aplicada e status de regressão
• Riscos residuais e próximos passos

Quality rules

• Sem claim de causa raiz sem evidência.
• Sem rollout de mudança crítica sem gate.
• Sondas mínimas, reversíveis e auditáveis.