JuliusBrussee/caveman-evidence-review

Revisão de evidências do Caveman

Atue como um operador somente leitura. Construa conclusões a partir dos dados atuais do Caveman, não com base em suposições do repositório. Nunca inicie, aprove, cancele ou reverta um experimento a partir desta skill.

Regras rígidas

1. Mantenha estes buckets separados:
   • custo medido do provedor com lista de preços completa;
   • headroom diário inferido;
   • economia verificada no ledger;
   • custo das evidências. Nunca os adicione ou renomeie.
2. Não busque payloads de prompt, completion, ferramenta ou artefato a menos que o usuário peça explicitamente uma revisão de payload. Metadados, spans, tempo, modelos, contagens de tokens, status e atribuição de otimizador são suficientes para a revisão padrão.
3. Escopo de cada leitura limitado ao projeto selecionado pelo contexto do Caveman. Nunca forneça um ID de organização.
4. Resultados vazios são evidência de ausência de sinal atual, não de custo zero ou risco zero.
5. Cite IDs de trace e janelas de tempo exatas usadas. Não atribua causa a partir de um agregado isolado.

Passo 1 — Carregar contexto

Prefira MCP:

caveman_context {}

CLI como fallback:

caveman cloud whoami
caveman cloud projects list

Pare se login ou seleção de projeto estiver ausente. Peça ao usuário para executar caveman login ou selecionar um projeto; nunca adivinhe.

Passo 2 — Estabelecer baseline

Use caveman_report para:

• overview
• costs
• score
• workflows
• verified_savings

Em seguida, use caveman_plan para headroom diário classificado. Se a pergunta for restrita, pule relatórios não relacionados. Leia o conjunto mais curto que possa respondê-la.

CLI como fallback:

caveman cloud costs
caveman cloud score
caveman cloud plan --json

Declare a janela do relatório e a base antes de interpretar a direção.

Passo 3 — Testar a explicação principal com traces

Use caveman_trace_search. Escolha uma janela limitada e filtros fechados: workflow, agente, modelo, provedor, código de erro, modo de execução, status de cache, ID de otimização, classe de status, limites de token/custo/latência, compressão ou veredito do monitor.

Agrupamentos úteis:

• workflow — encontre jobs que geram custo ou falhas;
• model — compare a mistura de modelos;
• session — isole comportamento de retry ou loop;
• sem agrupamento — identifique traces exatos.

Compare uma coorte suspeita com uma coorte de controle ou janela anterior limitada. Não infira causalidade a partir de um único trace caro.

CLI como fallback:

caveman cloud traces search \
  --workflow <slug> \
  --from <RFC3339> \
  --to <RFC3339> \
  --sort total_cost_usd \
  --dir desc \
  --limit 25

Passo 4 — Inspecionar traces representativos

Chame caveman_trace_get para um pequeno número de IDs de trace de alto sinal. Inspecione metadados de requisição e span, latência, status, contagens de tokens, estado do cache, otimizadores aplicados e rota do modelo. Mantenha a recuperação de payload desligada.

CLI como fallback:

caveman cloud traces show <trace-id> --spans

Passo 5 — Relatar

Use este formato:

## Revisão de evidências do Caveman

Escopo: <projeto> · <de> a <para>
Custo medido: <valor e base>
Economia verificada: <valor do ledger, mantido separado>
Headroom inferido: <faixa por dia, mantido separado>

Descobertas:
1. <descoberta> — <evidência agregada> — traces <ids>
2. <descoberta> — <evidência agregada> — traces <ids>

Não comprovado:
- <explicação plausível sem controle, trace ou avaliação>

Próxima verificação somente leitura:
- <uma consulta limitada>

Ação possível:
- <apenas proposta; use caveman-manage para revisão de ciclo de vida e portão de segurança>

Se dados estiverem faltando, nomeie o sinal ausente e pare na afirmação mais suportada. Nunca transforme um subtotal de catálogo em fatura ou resultado de experimento em economia verificada.