Diagnostica causa-raiz de sintoma (teste falhando, erro inesperado, comportamento divergente) por método científico. Produz diagnóstico, não fix. Stack-agnóstico.
How this skill is triggered — by the user, by Claude, or both
Slash command
/pragmatic-dev-toolkit:debugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Esta skill enforca **"não corrigir sem isolar a causa"**. Recebe um sintoma e produz um diagnóstico — não escreve código, não cria commit, não aplica instrumentação. Saída é texto na conversa: sintoma observado, reprodução, hipóteses testadas, causa-raiz com evidência, escopo de impacto, caminhos de correção possíveis. O operador decide o caminho depois.
Esta skill enforca "não corrigir sem isolar a causa". Recebe um sintoma e produz um diagnóstico — não escreve código, não cria commit, não aplica instrumentação. Saída é texto na conversa: sintoma observado, reprodução, hipóteses testadas, causa-raiz com evidência, escopo de impacto, caminhos de correção possíveis. O operador decide o caminho depois.
Sintoma operacionalizável. Exemplos:
/debug test_export_csv falhou com TimeoutError no CI/debug webhook /payment retorna 500 desde o deploy de ontem/debug datas saem com fuso errado em produçãoSintoma vazio ou vago ("não está funcionando", "está bugado") → pedir precisão antes de prosseguir (passo 1).
test_command — reproduzir teste falhando ou rodar a suíte que exerce o cenário.ubiquitous_language — consultar se o sintoma toca invariantes documentadas (RNxx ou equivalentes).decisions_dir — consultar se o sintoma envolve invariantes pós-erro (rollback, retry com efeito colateral, divergência de estado).design_notes — consultar se o sintoma envolve integração externa.Entrada genérica → coletar precisão antes de hipotetizar. Mecânica: uma única chamada AskUserQuestion agrupando os 3 gaps enum-áveis (regra de unificação em CLAUDE.md → "AskUserQuestion mechanics"); gaps de descrição livre ficam em prosa subsequente apenas se o argumento original do /debug não os cobriu.
Chamada unificada (3 questions, sem Recommended — sem default estatisticamente estável neste passo):
Onde (enum): dev local / CI / staging / prod.Reprod (enum): Sempre / Às vezes / Uma vez só.Mudou (enum): Sim / Não / Não sei.Resposta Sim em Mudou → perguntar em prosa direta na conversa (sem nova AskUserQuestion) "quando começou a falhar?" antes dos gaps de descrição abaixo.
Após a chamada, prosa direta para os gaps de descrição que o argumento original do /debug não cobriu:
Sem sintoma operacionalizável depois das respostas, não avançar.
test_command resolvido restringindo ao alvo (filtro por nome em pytest, cargo, jest, go test).Evitar pular para hipótese antes de ver o sintoma com os próprios olhos quando reprodução é viável.
Estreitar a área suspeita antes de hipotetizar:
git log -- <arquivos suspeitos> recente: o sintoma começou após qual commit?git blame nas linhas relacionadas ao erro.decisions_dir) se o sintoma envolve invariantes pós-erro.design_notes se envolve integração externa com peculiaridades documentadas.ubiquitous_language para checar se o comportamento fere uma RNxx.Instrumentação de progresso (ADR-010). Cada hipótese é instrumentada via Task com content="Hipótese: <descrição>"; lifecycle conforme ADR-010 §Mecânica. Status semântico (confirmada/refutada/inconclusiva) vai no ledger-prosa, não na Task. Diagnóstico fechando com 1 hipótese → skip silente da instrumentação.
Para cada hipótese plausível:
Limite: parar após duas hipóteses consecutivas refutadas sem ganho de evidência (mesmo erro, mesmo escopo, nenhuma pista nova) e reportar status no passo 5 (ramo "nenhuma hipótese fechou").
Manter ledger das hipóteses em prosa (frase + status + evidência) para o passo 5 — Tasks tracking-only, prosa carrega raciocínio causal. ≥2 hipóteses examinadas → ledger entra como campo Hipóteses testadas.
Hipótese confirmada com evidência → formular diagnóstico nos campos abaixo:
H<n> (<status>): <hipótese>. <evidência confirmadora/refutadora>. Status canonical: confirmada / refutada / inconclusiva. Omitir o campo quando apenas 1 hipótese foi testada e confirmada — Causa-raiz sozinha basta./triage <intent> se for mudança maior. Investigação revelar caminho único razoável → declarar "caminho único razoável" com motivo. Operador decide.Nenhuma hipótese fechou no passo 4 → Hipóteses testadas carrega ledger completo (refutadas + inconclusivas); Causa-raiz é substituída por palpite atual com nível de confiança baixa explicitado; relato preserva observações para /triage (se for o caminho) ter base. Evidência incompleta é resultado válido; chute disfarçado de causa-raiz, não.
Apresentar diagnóstico do passo 5 em formato curto e sugerir próximo passo em uma frase:
Revert — investigação isolou sintoma a commit específico e revert é seguro (ex.: "revert de <hash> no branch atual").
Patch local — mudança cirúrgica que cabe sem alinhamento prévio (ex.: "ajustar <arquivo>:<linha> — uma linha; commitar diretamente").
/triage — fix é mudança maior (multi-arquivo, toca invariante/integração, exige plano). Emitir bloco-comando pronto com a invocação já preenchida (substituir o placeholder pela frase derivada da causa-raiz + caminho de correção do passo 5), para o operador copiar/colar. Exemplo do bloco emitido:
/triage corrigir AssertionError em test_export_csv.py:42 — fixture stale
Diagnóstico completo (incluindo Hipóteses testadas quando presente) entra como insumo do ## Contexto do plano produzido pelo /triage.
/new-adr e /triage.npx claudepluginhub fppfurtado/pragmatic-dev-toolkit --plugin pragmatic-dev-toolkitGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.