workflow investigate-bug — a investigação

Rotina ativa desde 28/07: investigate-bug, local, dias úteis às 9h. Local por limitação de ferramenta (rotina de nuvem só pela UI) — e como ela processa uma fila em vez de vigiar, o dia em que a máquina está fechada a fila só espera. Mover pra nuvem tira a dependência da máquina estar ligada.

Um dos três. O par da scout-log, e o irmão do reach (mesma forma, outra tag). Aquela constata (o quê, quanto, desde quando) e registra no In-box; esta investiga: acha a causa raiz, atualiza o card e move pra Reach.

A separação é deliberada. Investigar exige ler código, formar hipótese, reproduzir e às vezes inspecionar estado ao vivo — isso não cabe numa varredura diária: ou estoura o orçamento, ou entrega diagnóstico raso, que é pior que nenhum porque parece pronto.

Clique no diagrama para a versão interativa (investigate-bug.html): tema claro/escuro, pan/zoom, busca, três views guiadas e export PNG/SVG.

A fonte é o JSON, não o desenho. Os dois arquivos são derivados de docs/agents/investigate-bug.architecture.json. Mudou o workflow? Edite o JSON e rode archify deliver + o extrator do SVG — nunca edite o .svg nem o .html à mão.

O grafo de agentes

O desenho acima é o fluxo; este é o grafo de agentes — quem é spawnado e com qual modelo.

O padrão é classify-and-act: a fase 1 classifica o risco e roteia; não existe barreira entre os bugs, então um bug pode fechar enquanto outro ainda investiga.

Fase	Agentes	Modelo
Fila	fila:to-scout	haiku / low
Investigar	investiga:<card> — 1 por bug, em pipeline	opus/xhigh ou sonnet/high
Fechar	fechar:relato	sonnet / medium

O roteamento é a decisão do desenho, e ela é tomada em código — não pelo modelo em runtime. Sobe pra Opus em fluxo crítico (criticidade), P0/P1 (priorize) ou estimate L/XL; o resto fica no piso Sonnet, porque investigar é julgamento e Haiku não entra nem no bug pequeno.

Note que não há juiz no fim: o relato consolida o lote, não decide nada. Quem decide o destino de cada card é o próprio agente que investigou, contra os dois requisitos (causa + sinal).

A fila: três critérios juntos

Ela pega issue com os três ao mesmo tempo, e cada um tem um motivo:

Critério	Por quê
tag Bug	é o que a separa do workflow reach, que pega a mesma fila sem a tag pra fazer PRD e sub-issues (via to-scout)
estado To scout	é o gate humano: a triagem cria no In-box, e alguém promove quando decide que vale investigar
sem projeto	issue dentro de projeto pertence a uma iniciativa planejada, que tem outro fluxo

Bug não precisa de PRD, precisa de causa. Melhoria não precisa de causa, precisa de recorte. Sem o filtro da tag, investigate-bug e to-scout competem pelo mesmo card e uma sobrescreve o trabalho da outra.

Os status são parte do sistema

To scout e Reach aparecem no desenho como caixas próprias, do tipo status Linear, porque são estado do sistema e não anotação posterior. To scout é do humano (é ele que promove do In-box); Reach é desta rotina, e só com causa + sinal. Transição de coluna é transição de estado — quem escreve na coluna de outro quebra a leitura de quem confia nela.

As três fases

#	Fase	Entrega
1	Fila	lista as issues elegíveis + as ignoradas com motivo (teto explícito por run, logado)
2	Investigar	um subagente por bug, em paralelo — cada um fecha causa ou declara inconclusivo
3	Fechar	relato do lote: quem foi pra Reach, quem ficou e o que falta

O modelo é escolhido por bug, em código

Investigar é sempre julgamento (ler código, formar hipótese, testar), então o piso é Sonnet — Haiku não entra nem no bug pequeno. Sobe pra Opus onde errar custa caro:

Condição	Modelo
fluxo crítico (criticidade) · P0/P1 · estimate L/XL	opus / xhigh
o resto	sonnet / high

É a matriz inteligência × volume da régua modelo-effort aplicada item a item, no código do workflow — não no julgamento do modelo em runtime.

O que ela exige pra mover pra Reach

Duas coisas, e as duas juntas:

1. Causa raiz com arquivo:linha — o porquê, não o onde dói. "O timeout é lido antes do override de env, então sempre vale 3000ms" é causa; "estoura em belvo.service.ts" é sintoma.
2. Sinal de reprodução — a Fase 1 do diagnosing-bugs: um pass/fail que fica vermelho neste bug e verde quando corrigirem. Sem ele, nem quem investigou sabe que achou, nem quem corrigir sabe que corrigiu.

Ela também mede o blast radius (via graphify) — quem mais depende do que vai mudar — porque é isso que decide se o fix é pequeno ou perigoso. E revisa priority/estimate agora que a causa é conhecida: é comum um P2 virar P1 quando se descobre que o erro silencioso corrompe dado.

Não fechou é resultado válido

Se não deu pra chegar na causa (não reproduz, falta acesso, precisa de estado ao vivo que só existe em sessão interativa), o card fica em To scout com o motivo escrito no comentário.

Investigação honestamente inconclusiva é informação; causa inventada é armadilha pro próximo. E card sem causa em Reach engana quem for planejar — por isso mover só acontece com os dois requisitos acima.

O que ela não faz

• Não conserta. A correção sugerida é direção, não patch. Quem implementa é o build, depois, com o plano do reach.
• Não cria issue. Achou um segundo problema no caminho? Comenta no card e menciona no retorno — quem cria issue é a skill triagem.
• Não decide o que merece investigação. Isso é o gate humano da promoção In-box → To scout.

Todo workflow tem DOIS desenhos — o do sistema (quais peças existem e quem é dona de quê) e o do grafo de agentes (quantas chamadas rodam, em que padrão, a que custo). É a regra da skill to-wiki, e um não substitui o outro. Para páginas que não são de workflow, diagrama continua sob demanda.