voltar ao catálogo

criar-investigacao

Conduz investigações técnicas de código e sistemas para identificar e priorizar problemas reais e potenciais com evidências concretas (trechos de código, logs, métricas). Produz um documento estruturado de investigação classificando achados por severidade (CRÍTICA, ALTA, MÉDIA, BAIXA), com análise de causa raiz, propostas de solução e riscos. Use quando o usuário pedir para investigar bugs recorrentes, problemas de performance, riscos de segurança, dívida técnica, qualidade de código ou preparação para escala em módulos existentes. Não use para implementar correções, escrever testes, fazer code review de PR, criar spikes de pesquisa de novas tecnologias ou redigir PRDs/Tech Specs.

Versão: v1.0.0Autor: Fabio de StefaniPlugin: criar-investigacaoTags: investigacao, tech-debt, diagnostico, severidade, documentacao
/plugin install criar-investigacao@nextfit-hub-ai

Criar Investigação Técnica

Restrições Inegociáveis

  • Não gere a investigação sem antes coletar respostas de clarificação via AskUserQuestion.
  • Não altere a estrutura do template em assets/investigacao-template.md.
  • A investigação identifica e prioriza problemas com evidências; não implementa correções nem modifica código-fonte da aplicação.
  • Classifique severidade por impacto real, nunca por complexidade da correção.

Procedimentos

Passo 1: Esclarecer (Obrigatório)

  1. Leia references/clarification-checklist.md e selecione os blocos pertinentes à solicitação do usuário.
  2. Formule perguntas agrupadas via AskUserQuestion, cobrindo no mínimo: escopo, tipo de problemas, contexto/motivação, severidade mínima e fora de escopo.
  3. Não prossiga ao Passo 2 enquanto houver perguntas não respondidas.

Passo 2: Analisar (Obrigatório)

  1. Leia o código-fonte dos módulos em escopo usando Read e Grep; nunca conclua sem inspeção direta.
  2. Quando aplicável, use WebSearch para localizar CVEs conhecidos, RFCs, padrões de referência e boas práticas; cite as fontes nos achados.
  3. Para cada problema identificado, colete evidência concreta (trecho de código com arquivo:linha, log ou métrica). Achados sem evidência são descartados.
  4. Conduza análise de causa raiz — explique por que o problema existe, não apenas o sintoma.
  5. Atribua severidade preliminar consultando references/severity-rubric.md.

Passo 3: Planejar (Obrigatório)

  1. Defina as categorias temáticas dos achados (ex.: Segurança, Performance, Estabilidade, Qualidade).
  2. Conte a distribuição de achados por severidade.
  3. Defina a abordagem de priorização (severidade × esforço × impacto no negócio) e identifique dependências entre correções.
  4. Exiba o plano resumido ao usuário antes de redigir o documento.

Passo 4: Redigir a Investigação (Obrigatório)

  1. Leia assets/investigacao-template.md e replique sua estrutura exatamente.
  2. Para cada achado, preencha todos os campos do bloco padrão: severidade, ponto da falha, impacto, descrição, evidência, análise de causa raiz, arquivos afetados, proposta de solução e riscos da correção.
  3. Agrupe os achados pelas categorias definidas no Passo 3.
  4. Preencha a tabela de priorização com prioridade (P0–P3), esforço estimado (S/M/L/XL), prazo sugerido e impacto no negócio.
  5. Liste dependências entre correções e o checklist de validação por categoria.
  6. Declare explicitamente o que ficou fora de escopo.

Passo 5: Criar Diretório e Salvar (Obrigatório)

  1. Derive o slug em kebab-case a partir do tema da investigação (ex.: "Performance do Login" → performance-login).
  2. Crie o diretório ./docs/tasks/investigacao-[slug]/ via Bash se ainda não existir.
  3. Salve o documento em ./docs/tasks/investigacao-[slug]/investigacao.md via Write.

Passo 6: Validar com o Checklist de Qualidade (Obrigatório)

  1. Leia references/quality-checklist.md.
  2. Verifique cada item obrigatório contra o documento gerado.
  3. Se algum item obrigatório falhar, retorne ao Passo correspondente e corrija antes de reportar.

Passo 7: Reportar Resultados

  1. Informe o caminho completo do arquivo gerado.
  2. Forneça um resumo bem breve com: total de achados, distribuição por severidade e os itens P0/P1 mais urgentes.
  3. Não anexe o conteúdo do documento na resposta — apenas o resumo e o caminho.

Helpers Bundled

  • assets/investigacao-template.md — read-only. Estrutura canônica do documento final. Replicar sem alterar a ordem das seções.
  • references/clarification-checklist.md — read-only. Base para as perguntas obrigatórias do Passo 1.
  • references/severity-rubric.md — read-only. Critério de classificação de severidade no Passo 2.
  • references/quality-checklist.md — read-only. Auditoria final no Passo 6.

Tratamento de Erros

  • Usuário não respondeu às perguntas de clarificação: repita o Passo 1 com perguntas mais específicas; não suponha respostas.
  • Sem acesso a arquivo/módulo em escopo: registre a limitação na seção "Fora de Escopo" e siga adiante com o restante.
  • Achado sem evidência concreta: descarte ou rebaixe para hipótese registrada em "Perguntas em aberto" — nunca o liste como achado factual.
  • Diretório ./docs/tasks/ inexistente: crie-o como parte do Passo 5; não trate como erro.
  • Conflito com investigação anterior de mesmo slug: confirme com o usuário se deve sobrescrever ou usar sufixo numérico (-v2).