investigate
por garrytanA skill investigate orienta depuração sistemática e análise de causa raiz para comportamentos quebrados, instáveis ou inesperados. Use-a em code review, triagem de incidentes, correção de bugs e casos de "ontem funcionava" quando você precisa de evidências antes de alterar o código. Ela segue um fluxo de quatro fases: investigate, analyze, hypothesize, implement.
Esta skill tem pontuação 82/100, o que a coloca como uma boa candidata para o diretório: cobre com clareza um fluxo comum de depuração e análise de causa raiz e traz orientação suficiente para reduzir a incerteza, embora ainda faltem alguns materiais de apoio no repositório que facilitariam a adoção.
- Deixa explícitos os gatilhos para depuração e cenários de causa raiz, incluindo orientação proativa para usar a skill em erros, stack traces e casos de "ontem estava funcionando".
- O fluxo operacional é nomeado e delimitado em quatro fases—investigate, analyze, hypothesize, implement—com uma regra rígida contra aplicar correções antes de identificar a causa raiz.
- Usa hooks e allowed-tools, o que indica comportamento real de execução em vez de uma simples descrição conceitual.
- O repositório não tem comando de instalação, arquivos de suporte, referências nem readme, então o usuário precisa depender principalmente de SKILL.md para entender configuração e escopo.
- O frontmatter inclui marcadores de placeholder, o que sugere que algumas partes ainda podem estar em refinamento, embora o conteúdo principal do fluxo já seja robusto.
Visão geral do skill investigate
O que o skill investigate faz
O skill investigate é voltado para depuração sistemática e análise de causa raiz quando algo está quebrado, instável ou se comportando de forma diferente do esperado. Ele foi pensado para quem precisa de mais do que um ajuste rápido: se você quer entender por que um erro acontece, o que mudou e qual correção é segura, o investigate ajuda a estruturar esse trabalho.
Quem deve usar
Use o skill investigate para code review, triagem de incidentes, correção de bugs e situações do tipo “funcionava ontem”. Ele é uma ótima opção quando você precisa que o agente pare de chutar, reúna evidências e avance dos sintomas para uma causa confirmada antes de mexer no código.
Por que ele se destaca
O grande diferencial é a regra de “sem correção sem causa raiz”. Isso torna o skill investigate mais disciplinado do que um prompt genérico de debug: ele empurra o fluxo para investigação, análise, hipótese e implementação, em vez de pular direto para edições. Ele também dá suporte a acionamento proativo, o que é útil em fluxos com agentes em que o skill deve entrar em ação assim que erros ou stack traces aparecem.
Como usar o skill investigate
Instale e invoque o skill
Instale o skill investigate com:
npx skills add garrytan/gstack --skill investigate
Use-o quando seu prompt descrever claramente um estado de falha, como um stack trace, erro 500, regressão ou saída inesperada. Para melhores resultados, informe o sintoma, onde ele aparece e como deveria ser o comportamento “certo”.
Dê a entrada inicial certa
Um bom prompt de uso do investigate inclui:
- a mensagem de erro exata ou um trecho do log
- o comando, endpoint ou ação do usuário que dispara o problema
- o que mudou recentemente
- o que você já verificou
- o impacto e a urgência
Exemplo: “Investigue por que npm test agora falha no CI depois do último merge. Compare main vs. HEAD, examine mudanças recentes no middleware de auth e não proponha alterações de código até confirmar a causa raiz.”
Leia primeiro os arquivos certos
Comece com SKILL.md e depois inspecione SKILL.md.tmpl para comportamento baseado em template ou lógica de roteamento. Como este repositório não tem pastas separadas rules/, resources/ ou scripts/, o principal valor está no próprio arquivo do skill e em qualquer referência inline que ele faça. Para investigate em Code Review, preste atenção especial à linguagem de gatilho e aos limites das operações seguras antes de editar.
Dicas de workflow que melhoram o resultado
Trate o investigate como um fluxo de decisão, não como um bate-papo aberto. Peça ao agente para:
- identificar o modo de falha,
- coletar evidências de suporte,
- formular uma ou duas hipóteses testáveis,
- verificar a causa mais provável,
- implementar a menor correção segura.
Se você pular o passo 1, o skill ainda pode gerar análise, mas ela será menos útil para code review ou resposta a incidentes.
FAQ do skill investigate
O investigate serve só para bugs?
Não. O skill investigate também é útil para regressões, falhas de deploy, integrações quebradas e mudanças de comportamento pouco claras. Se a tarefa for “descobrir por que isso está acontecendo”, o investigate geralmente é o ponto de partida certo.
Em que ele difere de um prompt normal?
Um prompt normal pode pedir uma correção imediatamente. O skill investigate é mais estruturado: ele força primeiro o raciocínio de causa raiz, o que reduz edições frágeis e torna a mudança final mais fácil de defender em code review.
O investigate é bom para iniciantes?
Sim, desde que a pessoa consiga fornecer um sintoma e um pouco de contexto. Iniciantes normalmente se beneficiam do skill porque ele reduz o chute, mas ainda precisam compartilhar evidências concretas, como logs, passos para reproduzir ou um comando com falha.
Quando não devo usá-lo?
Não use o investigate quando você já souber exatamente a mudança que quer, ou quando estiver fazendo uma edição de conteúdo simples sem nenhuma falha para diagnosticar. Nesses casos, um prompt de tarefa mais direto é mais rápido.
Como melhorar o skill investigate
Traga evidências, não só uma reclamação
O maior salto de qualidade vem de entradas mais precisas. Em vez de “o app está quebrado”, informe a requisição que falha, o texto do erro, o caminho do arquivo, o ambiente e o último estado em que tudo funcionava. O skill investigate funciona melhor quando consegue ancorar cada hipótese em evidências observáveis.
Restrinja o espaço de busca
Se o problema estiver em Code Review, identifique o subsistema mais provável e a janela da mudança. Por exemplo: “Foque em auth, apenas nas mudanças dos dois últimos commits, e verifique se o bug é reproduzível em staging.” Isso evita que o investigate se espalhe demais e aumenta a chance de chegar rápido à causa raiz.
Itere depois da primeira passada
Se a primeira resposta for inconclusiva, peça uma investigação mais precisa em vez de uma reescrita mais ampla. Bons próximos passos são: “Liste as três hipóteses principais com níveis de confiança”, “Mostre quais evidências refutariam cada uma”, ou “Rastreie a falha da entrada até a saída e pare antes de codificar.”