Investigação de bug

makuco-analisar · modo INVESTIGAÇÃO

Função

O modo INVESTIGAÇÃO é a porta de entrada de um bug em produção. Você descreve o que quebrou, e a skill chega a uma causa raiz defensável — do sintoma relatado até um bug em código lido num commit, com as explicações concorrentes derrubadas por evidência, e cada lacuna declarada em vez de disfarçada.

Muda o direcionamento, não o fluxo. Do laudo em diante é o mesmo SDD de uma feature nova: feature.md, PBIs validadas por INVEST, makuco-desenvolver implementa e makuco-code-review revisa. A diferença é que os requisitos saem de um bug provado, e não de um valor proposto.

Quando usar

• Use quando algo está quebrado e ninguém sabe por quê.
• Não use quando a causa já é conhecida: isso é SOLUÇÃO, ou EXPRESS quando o card já diz o que mudar.

Fluxo em passos

step-01-setup          → modo INVESTIGAÇÃO · classe do sintoma · mapa de capacidades
        ↓
step-02d-investigacao  → sintoma × objetivo · janela · ponte log→código · linha do tempo por causa ·
                         precedentes · matriz de hipóteses · falsificadores executados
        ↓
step-03b-refutacao     → subagente adversarial · sondagem fora do roteiro · gate de evidência → rca.md
        ↓
step-04-feature        → traduz o rca.md para o PRD, em linguagem de negócio
        ↓
step-05-pbis           → PBIs de correção, de verificação e de remediação de dados
        ↓
step-06-fechamento     → handoff para makuco-desenvolver

O gate de produto (step-03-gate) nunca roda neste modo. Quem libera a análise é o gate de evidência.

O que a investigação consegue ler

A classe do sintoma

A primeira pergunta é sobre a forma da falha, não sobre o domínio, e define de quais fontes a investigação precisa:

Mais de uma classe → a união das capacidades exigidas.

As sete capacidades

Cada capacidade é um papel, nunca um produto. A ferramenta que cumpre cada papel fica na configuração do projeto.

Como cada capacidade é resolvida

A resolução é feita pela skill makuco-observability-context, por capacidade, nesta ordem:

1. Configuração — .makuco/integrations/observability.yml. Presente, vence qualquer outra fonte.
2. Docs de codebase — a seção de observabilidade do integrations.md, escrita pelo makuco-project-research a partir das dependências declaradas do repo.
3. Ambiente — quais servidores MCP estão conectados nesta sessão e quais CLIs respondem no PATH. Servidor configurado mas inalcançável não conta como capacidade.
4. Pergunta a você — só para as capacidades que a classe do sintoma exige, uma pergunta por capacidade, e a resposta é gravada no observability.yml.
5. none — nada resolveu e você não soube dizer. Vira lacuna declarada, com teto de confiança.

A pergunta nomeia o papel, nunca uma lista de produtos:

Para investigar latência/5xx eu preciso ler o log da aplicação na janela do incidente. Onde esse log vive neste projeto?

[1] Tenho uma ferramenta configurada — digo qual e como acessar [2] Consigo exportar e colar um trecho aqui [3] Não tenho acesso a log neste projeto

Pergunta uma vez, pergunta tarde. A resposta fica gravada, então uma segunda investigação no mesmo projeto não pergunta nada. [2] (colar à mão) conta como capacidade, e [3] também é gravado. Credencial nunca é pedida nem gravada: token vem do ambiente ou do .env.

Antes de seguir, a skill resume o mapa numa linha:

Capacidades desta investigação: código ✓ · log ✓ (Datadog) · métrica ✓ · borda ✗ (sem acesso). O que não tiver, eu declaro como lacuna no laudo em vez de supor.

Ausência de log não é ausência de erro

Toda capacidade está em exatamente um de três estados, e o laudo distingue os três:

Nos dois primeiros estados o laudo nunca diz "não há erro no log" ou "a métrica estava estável". E uma consulta que voltou vazia só vale depois de ser refeita ao menos uma vez com termo ou janela mais largos.

A investigação

• Sintoma e objetivo, separados, antes de tudo. O que o sistema faz de errado, e o que a pessoa tentava fazer. Se o objetivo pode ser destravado hoje, isso vai para o topo do laudo, acima da causa.
• O relato é hipótese, não ponto de partida. Um relato que já aponta o commit, o endpoint ou a classe culpada é uma afirmação a conferir. E todo número que ele traz fica não verificado até ser cruzado com dado bruto.
• A janela é discutida, não herdada. A skill alarga a janela ao menos uma vez, de propósito, e registra o motivo.
• Ponte de mensagem para local, nesse sentido. A mensagem de erro exata vira a string literal no código e o arquivo:linha no commit fixado, confirmada no log com valores reais. O topo do stack trace é onde o erro foi detectado, não onde foi causado.
• Linha do tempo por causa, não por sintoma. A skill busca as falhas das dependências a montante na janela e numa janela de controle, e as strings literais dos catch/warn do caminho que acabou de ler.
• Precedente em duas fontes. Commits dos arquivos candidatos — na janela e sem filtro de data — e itens irmãos já fechados no tracker, buscados pela mensagem, pela entidade e pela capacidade de negócio.
• Matriz de hipóteses. Cada hipótese com evidência a favor, evidência contra e como falsificá-la. Hipótese sem falsificador não é operacional. A causa deste incidente fica separada de qualquer bug sistêmico achado no caminho.
• Contra-teste simétrico. Descartar uma hipótese exige o mesmo padrão que promovê-la: descrever a correção candidata e por que ela não fecharia o sintoma. Sem isso, o estado é não totalmente testada, nunca descartada.
• Falsificadores que só leem são executados nesta sessão, não propostos. Só o que exige escrita, mudança de estado, credencial ou autorização fica proposto — e nada com efeito colateral roda sem você pedir explicitamente.

Tudo é gravado no sessao.md à medida que se sustenta, e uma sessão interrompida retoma dali.

O estágio adversarial

Assim que a cadeia fecha — antes de escrever uma linha do laudo — a skill despacha um subagente, com contexto limpo, para tentar derrubar a tese. Ele recebe só as conclusões (a causa, o commit, a cadeia com as citações), nunca o raciocínio que levou até elas.

O veredito sai por eixo, gravado em refutacao.md:

Enquanto ele trabalha, a skill faz uma sondagem fora do roteiro — uma configuração que ninguém pediu, um endpoint irmão, o caminho em lote ao lado do caminho unitário — e registra o que achou, inclusive "nada". Depois, confere contra a evidência cada eixo que caiu.

"Sem conclusão acionável" não é um desfecho. Quando a tese é reescrita, o laudo registra o que se acreditava antes e o que mudou.

O gate de evidência

É o gate que substitui o de produto neste modo. Cada item é fechado ou declarado como lacuna — nunca fechado preenchendo um campo:

• sintoma e objetivo separados; objetivo destravável no topo
• todo arquivo:linha fixado num commit
• ponte log→código construída, ou a ausência declarada com o teto aplicado
• linha do tempo consultada por causa e pelas strings do próprio caminho
• precedente buscado nas duas fontes disponíveis, com as consultas registradas
• matriz presente; nada descartado sem correção candidata concreta
• todo falsificador de leitura executado nesta sessão, com o resultado
• estágio adversarial rodado, veredito lido do refutacao.md, eixos caídos conferidos
• sondagem fora do roteiro registrada, inclusive o resultado nulo
• confiança por achado, com a regra que a produziu — sem nota composta
• toda capacidade none presente como lacuna com o seu teto
• requisitos e critérios de aceite escritos como especificação, sem nada implementado

A confiança nunca é uma média: vale o teto mais baixo entre as capacidades de que o achado depende. E um requisito nunca afirma como fato uma premissa de confiança Média — ele diz "verificar X; se confirmado, corrigir Y".

O laudo — rca.md

Escrito pelo makuco-copy-writer, em PT-BR, com o commit fixado no cabeçalho e a confiança na causa raiz (Alta, Média, Baixa ou Inconclusivo):

Capacidades e lacunas e Estágio adversarial são obrigatórias mesmo quando o resultado é "tudo disponível" ou "nada caiu". Credencial, token ou segredo nunca é transcrito, nem quando ele é o achado.

Da causa à correção

O PRD traduz, não reabre

No step-04, o rca.md já passou pelo gate: tudo nele está decidido. O feature.md traduz o laudo para o registro de negócio, como em qualquer outro modo — sem arquivo:linha, sem commit, sem status HTTP — e aponta para o rca.md nas Referências. Um requisito que o laudo deixou condicional continua condicional no escopo.

Três tipos de PBI

No step-05, a quebra parte dos requisitos e critérios que o laudo já produziu. Uma PBI por bug, não por requisito.

O teste de regressão é critério de aceite da PBI que corrige, e cobre a classe do bug, não a reprodução única. A PBI nunca repete a causa: mecanismo, arquivo:linha e commit ficam no rca.md, que ela referencia.

No desenvolvimento e no review

• O makuco-desenvolver lê o rca.md como contexto técnico, reabre as linhas citadas no HEAD e pergunta quando o código divergiu do commit do laudo. Não re-investiga a partir do sintoma.
• O makuco-code-review roda os passes de sempre e acrescenta uma pergunta no pass 1: a mudança fecha o mecanismo que o laudo descreve, e um teste cobre a classe do bug? Uma correção que faz o sintoma sumir sem tocar no mecanismo citado é achado.

Artefatos gerados

.makuco/docs/modules/module_NNN_nome/feature_NNN_nome/
├── rca.md          # o laudo — via makuco-copy-writer (stage=rca)
├── refutacao.md    # o veredito adversarial — escrito pelo subagente
├── feature.md      # o PRD, em linguagem de negócio
├── decisions.md
├── pbis.md
├── sessao.md       # classe do sintoma, mapa de capacidades, lacunas, matriz, falsificadores
├── status.yml      # ganha o ponteiro rca_artifact
└── pbis/pbi-NNN-slug/pbi.md

Configuração

• .makuco/integrations/observability.yml — criado comentado pelo makuco init e preenchido à medida que as capacidades são resolvidas. Formato e exemplos em Configurações → Observabilidade.
• .makuco/integrations/azure-devops.yml — habilita o tracker quando é o Azure DevOps que guarda os relatos e os itens irmãos.

Gatilhos

investigar bug, achar a causa raiz, RCA, por que quebrou em produção, analisar erro/5xx/timeout/ lentidão, descobrir o que causou esse bug.