JuliusBrussee/caveman-discover

Você está rotulando os workflows de LLM deste repositório para o Caveman Cloud. Um workflow é uma tarefa que o código executa — "responder um ticket de suporte", "gerar o resumo noturno", "executar a suíte de avaliação" — não uma tecnologia. Cada requisição ao gateway pode carregar um rótulo de workflow; tráfego não rotulado cai todo em um único bucket unlabeled-workflow. Seu trabalho: encontrar os workflows, nomeá-los bem, conectar os rótulos e verificar se nada quebrou.

Isso altera código, portanto passa pela revisão normal do usuário: proponha a tabela primeiro, aplique após o usuário concordar. Executar novamente em um repositório já rotulado não deve alterar nada (idempotente).

Esta skill é invocada pelo operador. Uma observação de Cave Plan unlabeled-traffic é apenas para revisão e não cria arquivo de consultoria, proposta ou Draft PR. Não presuma que a telemetria selecionou um ponto de chamada ou autorizou uma edição. Faça o inventário do repositório de forma independente, apresente a tabela de rotulagem e aguarde a aprovação do usuário antes de alterar código.

Passo 1 — Inventariar os workflows

Percorra o repositório a partir dos pontos de entrada, não das importações:

• Manipuladores HTTP/RPC que chamam um LLM (diretamente ou através de camadas)
• Jobs agendados: definições cron, consumidores de fila, workers, GitHub Actions que invocam código LLM
• Comandos CLI e scripts (scripts/, bin/, scripts do package.json)
• Suítes de eval / teste que consomem tokens reais
• Agentes ou chains distintos dentro de um framework (cada grafo LangGraph, cada equipe, cada definição de agente é geralmente seu próprio workflow)

Um workflow = uma tarefa que um humano nomearia. Dez pontos de chamada dentro do mesmo manipulador de requisição são um workflow; um helper llm.ts compartilhado usado por três jobs é três workflows (rotule nos chamadores, nunca no helper compartilhado).

Passo 2 — Nomeá-los

Gramática do slug (o gateway exige isso): minúsculas [a-z0-9_-], de 1 a 96 caracteres. Nomeie a tarefa, não a tecnologia:

• Bom: support-reply, nightly-digest, pr-review, eval-suite, onboarding-email
• Ruim: openai-calls (tecnologia), main (não diz nada), SupportReply (inválido), johns-test-3 (não envelhece bem)

Nomes são praticamente permanentes — renomear depois quebra o histórico de gastos. Quando o propósito de uma tarefa não estiver claro no código, derive o slug do nome do arquivo e marque-o como review na tabela, em vez de inventar um propósito.

Passo 3 — Propor, depois aplicar

Apresente esta tabela e peça para prosseguir:

| workflow | job | onde | como é rotulado |
|---|---|---|---|
| support-reply | responde tickets recebidos | src/bot/reply.ts:41 | defaultHeaders no cliente de reply |
| nightly-digest | job de resumo às 02:00 | jobs/digest.ts:12 | cabeçalho no cliente de digest |
| eval-suite (review) | scripts/eval.ts:8 — propósito inferido do nome do arquivo | scripts/eval.ts:8 | env override na invocação |

Em seguida, conecte cada rótulo com o mecanismo mais leve disponível naquele ponto de chamada:

• @caveman-ai/sdk / caveman_cloud SDK: opção workflow por trace, ou defaultWorkflow no cliente que um serviço de job único constrói.
• SDKs de provedores nativos (OpenAI/Anthropic/LangChain/LiteLLM/Vercel): adicione "x-cave-workflow": "<slug>" ao mesmo bloco defaultHeaders / default_headers / extra_headers que já carrega x-cave-api-key. Cliente compartilhado usado por vários jobs → passe o cabeçalho por chamada (todos os SDKs acima aceitam sobrescrita de cabeçalho por requisição), ou dê a cada job seu próprio cliente leve.
• Agentes de codificação encapsulados (caveman wrap): flag --workflow <slug> ou env CAVE_WORKFLOW=<slug> no ponto de invocação (linha cron, passo de CI).
• HTTP puro: adicione o cabeçalho x-cave-workflow à requisição.

Rotule os chamadores, mantenha o diff mínimo, siga o estilo do repositório. Se um ponto de chamada não é roteado pelo gateway Caveman, não o rotule — liste-o como "não conectado" no relatório (rótulos só viajam no tráfego do gateway; a conexão é trabalho da skill caveman-setup).

Passo 4 — Verificar

Execute o que o repositório já usa para exercitar um caminho rotulado (um teste, um script de desenvolvimento, um curl). Então confirme: a requisição ainda tem sucesso (o gateway rejeita um rótulo inválido com 400 cave_invalid_request_header — corrija o slug se for o caso). O gasto rotulado aparece no dashboard em /activity?tab=workflows assim que cada workflow for executado; jobs em um cron só aparecem quando o cron disparar, e vale a pena mencionar isso no relatório em vez de fingir que estão ativos.

Passo 5 — Relatório

## Workflows rotulados

| workflow | job | onde |
|---|---|---|
| support-reply | responde tickets recebidos | src/bot/reply.ts:41 |
| nightly-digest | job de resumo às 02:00 | jobs/digest.ts:12 |

Verificado: <o caminho rotulado que você realmente exercitou e o que observou>
Destino: <DASHBOARD>/activity?tab=workflows — cada linha aparece assim que o respectivo workflow for executado. Qualquer coisa ainda não rotulada aparece como `unlabeled-workflow`.
Não conectados (sem roteamento do gateway, portanto sem rótulo): <listar ou "nenhum">
Marcados como review: <slugs cujo propósito foi inferido dos nomes de arquivo, ou "nenhum">

Se você não encontrou nenhum ponto de entrada de LLM: diga exatamente isso e aponte para a skill de configuração (<docs origin>/docs/agent-setup.md) em vez de fabricar uma tabela.