trace

Skill Trace

Use esta skill para perguntas ambíguas, causais e com forte dependência de evidências, onde o objetivo é explicar por que um resultado observado aconteceu, e não pular diretamente para a correção ou reescrita de código.

Esta é a camada de orquestração sobre o agente tracer integrado. O objetivo é fazer com que o rastreamento pareça uma faixa OMC reutilizável: reafirme a observação, gere explicações concorrentes, colete evidências em paralelo, classifique as explicações e proponha a próxima sonda que reduziria a incerteza mais rapidamente.

Casos de entrada adequados

Use /oh-my-claudecode:trace quando o problema for:

• ambíguo
• causal
• com forte dependência de evidências
• melhor respondido explorando explicações concorrentes em paralelo

Exemplos:

• bugs de tempo de execução e regressões
• comportamento de desempenho / latência / recursos
• análise de arquitetura / pré-mortem / pós-mortem
• rastreamento de resultados científicos ou experimentais
• explicação de comportamento de configuração / roteamento / orquestração
• “dado esta saída, rastreie as causas prováveis”

Contrato principal de rastreamento

Sempre preserve estas distinções:

1. Observação — o que foi realmente observado
2. Hipóteses — explicações concorrentes
3. Evidências a favor — o que suporta cada explicação
4. Evidências contra / Lacunas — o que contradiz ou ainda está faltando
5. Melhor explicação atual — a explicação principal no momento
6. Incógnita crítica — o fato faltante que mantém as principais explicações separadas
7. Sonda discriminante — o próximo passo de maior valor para reduzir a incerteza

Não colapse em:

• um loop genérico de correção de código
• um resumo genérico de depurador
• um despejo bruto da saída do worker
• certeza falsa quando as evidências estão incompletas

Hierarquia de força da evidência

Trate a evidência como classificada, não plana.

Do mais forte ao mais fraco:

1. Reproduções controladas / experimentos diretos / artefatos unicamente discriminantes
2. Artefatos de fonte primária com proveniência restrita (eventos de rastreamento, logs, métricas, saídas de benchmark, configurações, histórico do git, comportamento arquivo:linha)
3. Fontes independentes múltiplas convergindo para a mesma explicação
4. Inferência de código ou comportamento de fonte única
5. Pistas circunstanciais fracas (tempo, nomes, ordem de pilha, semelhança com bugs anteriores)
6. Intuição / analogia / especulação

Reclassifique explicitamente para baixo hipóteses que dependem principalmente de níveis inferiores quando existirem evidências contraditórias mais fortes.

Regras de falsificação / refutação forte

Cada execução séria de /trace deve tentar falsificar sua própria explicação favorita.

Para cada hipótese principal:

• colete evidências a favor dela
• colete evidências contra ela
• declare qual previsão distintiva ela faz
• declare qual observação seria difícil de conciliar com ela
• identifique a sonda mais barata que a discriminaria da próxima melhor alternativa

Reclassifique uma hipótese para baixo quando:

• evidências diretas a contradizem
• ela sobrevive apenas adicionando novas suposições não verificadas
• ela não faz previsão distintiva em comparação com as rivais
• uma alternativa mais forte explica os mesmos fatos com menos suposições
• seu suporte é principalmente circunstancial enquanto a rival tem níveis de evidência mais fortes

Forma de orquestração no modo de equipe

Use o modo de equipe integrado do Claude para /trace.

O líder deve:

1. Reafirmar o resultado observado ou a pergunta “por que” com precisão
2. Extrair o alvo do rastreamento
3. Gerar múltiplas hipóteses candidatas deliberadamente diferentes
4. Criar 3 faixas de tracer por padrão no modo de equipe
5. Atribuir um worker tracer por faixa
6. Instruir cada worker tracer a coletar evidências a favor e contra sua faixa
7. Executar uma rodada de réplica entre a hipótese principal e a alternativa mais forte restante
8. Detectar se as faixas principais realmente diferem ou convergem para a mesma causa raiz
9. Mesclar as descobertas em uma síntese classificada com uma incógnita crítica explícita e uma sonda discriminante

Importante: os workers devem buscar explicações deliberadamente diferentes, não a mesma explicação em paralelo.

Faixas de hipótese padrão para v1

A menos que o prompt sugira fortemente uma partição melhor, use estas 3 faixas padrão:

1. Causa de caminho de código / implementação
2. Causa de configuração / ambiente / orquestração
3. Causa de incompatibilidade de medição / artefato / suposição — cobre defeitos de método de verificação, não apenas defeitos de sistema. Exemplos: a consulta de verificação reutiliza uma única chave dimensional em entidades, locatários, fluxos ou grupos distintos; a forma do filtro de comparação não corresponde ao grão do esquema; ou o nome do catálogo ou coluna foi considerado portátil entre tempos de execução sem enumeração. Isso inclui incompatibilidades de premissa/chave entre múltiplas entidades.

Para a faixa 3, discrepâncias entre entidades precisam de uma auditoria de premissa antes da escalada: enumere as dimensões da entidade e verifique se um resultado de zero linhas ou incompatibilidade veio da aplicação de uma chave em múltiplas entidades, em vez de um defeito do sistema; o resultado pode ser um defeito de metodologia de verificação.

Esses padrões são intencionalmente amplos para que o primeiro corte funcione em rastreamento de bugs, desempenho, arquitetura e experimentos.

Lentes de verificação cruzada obrigatórias

Após a passagem inicial de evidências, teste as líderes com estas lentes quando relevante:

• Lente de sistemas — filas, retentativas, contrapressão, loops de feedback, dependências a montante/jusante, falhas de limite, efeitos de coordenação
• Lente de pré-mortem — suponha que a melhor explicação atual está incompleta ou errada; qual modo de falha envergonharia o rastreamento mais tarde?
• Lente científica — controles, fatores de confusão, viés de medição, variáveis alternativas, previsões falseáveis

Estas lentes não são preenchimento. Use-as quando puderem revelar uma explicação perdida, dependência oculta ou inferência fraca.

Contrato do worker

Cada worker deve ser um proprietário de faixa tracer, não um executor genérico.

Cada worker deve:

• possuir exatamente uma faixa de hipótese
• reafirmar sua hipótese de faixa explicitamente
• coletar evidências a favor da faixa
• coletar evidências contra a faixa
• classificar a força da evidência por trás de seu caso
• apontar evidências faltantes, previsões falhadas e incerteza restante
• nomear a incógnita crítica para a faixa
• recomendar a melhor sonda discriminante específica da faixa
• evitar colapsar em implementação, a menos que explicitamente instruído a fazê-lo

Fontes de evidência úteis incluem:

• código relevante, testes, configurações, documentação, logs, saídas e artefatos de benchmark
• artefatos de rastreamento existentes via trace_timeline
• evidências de rastreamento agregadas existentes via trace_summary

Estrutura de retorno recomendada do worker:

1. Faixa
2. Hipótese
3. Evidências a favor
4. Evidências contra / Lacunas
5. Força da evidência
6. Incógnita crítica
7. Melhor sonda discriminante
8. Confiança

Contrato de síntese do líder

A resposta final de /trace deve sintetizar, não apenas concatenar.

Retorne:

1. Resultado observado
2. Hipóteses classificadas
3. Resumo de evidências por hipótese
4. Evidências contra / Evidências faltantes
5. Rodada de réplica
6. Notas de convergência / separação
7. Explicação mais provável
8. Incógnita crítica
9. Sonda discriminante recomendada
10. Faixas de rastreamento adicionais (opcional, apenas se a incerteza permanecer alta)

Preserve uma lista classificada reduzida, mesmo que uma explicação seja atualmente dominante.

Rodada de réplica e detecção de convergência

Antes de fechar o rastreamento:

• deixe a faixa não líder mais forte apresentar sua melhor réplica ao líder atual
• force o líder a responder à réplica com evidências, não com afirmação
• se a réplica enfraquecer materialmente o líder, reclassifique a tabela
• se duas hipóteses “diferentes” se reduzirem ao mesmo mecanismo subjacente, mescle-as e diga explicitamente
• se duas hipóteses ainda implicarem em sondas diferentes, mantenha-as separadas, mesmo que pareçam semelhantes

Não afirme convergência apenas porque vários workers usam linguagem semelhante. Convergência requer:

• o mesmo mecanismo causal raiz, ou
• fluxos de evidência independentes apontando para a mesma explicação

Orientação explícita de reclassificação para baixo

O líder deve dizer explicitamente por que uma hipótese desceu:

• contradita por evidências mais fortes
• falta a observação que previu
• requer suposições ad hoc extras
• explica menos fatos do que o líder
• perdeu a rodada de réplica
• convergiu em uma explicação pai mais forte

Isso é importante porque o /trace deve ensinar ao leitor por que uma explicação supera outra, não apenas apresentar uma tabela final.

Esqueleto de prompt sugerido para o líder

Use um prompt de orquestração orientado à equipe nestas linhas:

1. “Reafirme a observação exatamente.”
2. “Gere 3 hipóteses deliberadamente diferentes.”
3. “Crie uma faixa de tracer por hipótese usando o modo de equipe integrado do Claude.”
4. “Para cada faixa, colete evidências a favor e contra, classifique a força da evidência e nomeie a incógnita crítica mais a melhor sonda discriminante.”
5. “Aplique as lentes de sistemas, pré-mortem e científica aos líderes se útil.”
6. “Execute uma rodada de réplica entre as duas principais explicações.”
7. “Retorne uma tabela de explicações classificadas, notas de convergência, a incógnita crítica e a melhor sonda discriminante única.”

Padrão de qualidade da saída

Uma boa saída de /trace é:

• apoiada por evidências
• concisa, mas rigorosa
• cética em relação à certeza prematura
• explícita sobre evidências faltantes
• prática sobre a próxima ação
• explícita sobre por que explicações mais fracas foram reclassificadas para baixo

Exemplo de forma final de síntese

Resultado observado

[O que aconteceu]

Hipóteses classificadas

Classificação	Hipótese	Confiança	Força da evidência	Por que lidera
1	...	Alta / Média / Baixa	Forte / Moderada / Fraca	...

Resumo de evidências por hipótese

• Hipótese 1: ...
• Hipótese 2: ...
• Hipótese 3: ...

Evidências contra / Evidências faltantes

• Hipótese 1: ...
• Hipótese 2: ...
• Hipótese 3: ...

Rodada de réplica

• Melhor réplica ao líder: ...
• Por que o líder se manteve / falhou: ...

Notas de convergência / separação

• ...

Explicação mais provável

[Melhor explicação atual]

Incógnita crítica

[Fato faltante único que mantém a incerteza aberta]

Sonda discriminante recomendada

[Próxima sonda única]

Faixas de rastreamento adicionais

[Apenas se a incerteza permanecer alta]