2JIHAN/show-me-your-eta

turn-eta — diga quando este turno será concluído e aprenda com o tempo realmente gasto

Antes de iniciar o trabalho, escreva as etapas como uma lista numerada e informe quando será concluído. Cronometre cada etapa conforme ela é executada. Ao final do turno, feche a resposta com o horário real de término. A próxima estimativa lerá esse registro.

Quando executar

Em todo turno que contém trabalho real — editar um arquivo, executar um comando, pesquisar a base de código.

• Turno com trabalho → chame plan antes de começar e abra sua resposta com o que ele imprime, na ordem em que imprime: primeiro a linha **ETA …** sozinha, depois as etapas numeradas. O horário de término é o que o leitor busca; as etapas abaixo são a lógica por trás dele. Chame step <id> conforme cada etapa é concluída, e done <id> quando o trabalho do turno terminar.
• O último parágrafo também é um horário, e qual horário depende de ainda haver algo em execução.
  • Tudo terminou antes de você escrever a resposta → o bloco inteiro que done imprime: a linha de término do done. A essa altura o ETA já expirou; reimprimi-lo entrega ao leitor um palpite que o relógio já desmentiu, enquanto os tempos por etapa mostram onde houve erro.
  • Algo ainda está em execução (job em background, tarefa delegada) → a previsão: **ETA 17:45**. Recalcule ao escrever, nunca cole o número que plan imprimiu antes.
• Turno apenas de conversa (responder pergunta, decidir o que construir) → não faça nada. É ruído.
• Uma correção de uma linha também não merece a cerimônia. Use quando houver mais de uma etapa.

Comandos

Node puro, sem instalação. Execute a partir de onde o skill estiver instalado.

# antes do trabalho — nomeie as etapas e obtenha um ETA
node <skill>/scripts/eta.js plan \
  "reproduzir a falha" "corrigir o parser de data" "atualizar os fixtures" "executar a suíte novamente" \
  --provider anthropic --model claude-opus-5 --size M

# **ETA 17:45** (14 min)
#
# 1. reproduzir a falha
# 2. corrigir o parser de data
# 3. atualizar os fixtures
# 4. executar a suíte novamente
#
# 4 etapas, ~14 min (3.5 min/etapa do anthropic/claude-opus-5 M, 6 turnos)
#
# (as últimas 6 estimativas ficaram 3 min mais longas)
# turn id: 48i35qek

# cada vez que uma etapa é concluída — medida, e o restante é reprojetado com base no ritmo medido
node <skill>/scripts/eta.js step 48i35qek
# 2/4 corrigir o parser de data — 8m 06s
#
# **ETA 17:49** (4 min depois)

# quando o trabalho do turno terminar
node <skill>/scripts/eta.js done 48i35qek
# **FINALIZADO 17:48** (estimado 14 min / real 17 min)

# o que o log diz agora
node <skill>/scripts/eta.js stats

Nomeie as etapas, não apenas as conte. plan recusa um número simples. Uma contagem que ninguém pode verificar não é um plano — etapas nomeadas permitem que quem lê diga "pule 3" antes de você começar. Coloque essa lista numerada no topo da sua resposta e depois execute o trabalho.

Você deve passar seus próprios --provider e --model. Um shell não consegue ver qual modelo está dirigindo. Use os identificadores que você conhece — --provider anthropic --model claude-opus-5, --provider openai --model gpt-5-codex, --provider google --model gemini-3-pro. Qualquer coisa ausente cai em unknown/unknown, que ainda funciona, mas agrupa todos os modelos juntos.

--size é S (correção pequena), M (normal, padrão) ou L (grande bloco). Aproximado é suficiente; só evita que turnos pequenos arrastem a média dos grandes.

O id do turno é obrigatório. plan imprime um; carregue-o em cada step e no done final — step 48i35qek, done 48i35qek. Outro agente trabalhando no mesmo projeto escreve no mesmo log, então uma chamada sem id costumava encerrar o turno que estivesse aberto — mesmo que de outra pessoa. step e done agora recusam sem ele. Um turno sem interação por quatro horas é considerado abandonado.

Onde o log fica

<raiz do projeto>/.eta/<provider>/<model>/log.tsv

Dentro do projeto, para que um agente cujas permissões parem no diretório de trabalho ainda possa ler seu próprio histórico. A raiz do projeto é o .git mais próximo subindo, senão o diretório atual. Provider e model são pastas, para que o ritmo de um modelo nunca se torne silenciosamente o de outro.

Adicione .eta/ ao .gitignore. É uma medição da sua máquina nos seus turnos; não significa nada para mais ninguém e muda a cada turno.

Defina TURN_ETA_DIR para outro diretório .eta e compartilhe o histórico entre projetos. Ele só é consultado quando o log local é muito superficial para dizer algo.

Como a estimativa melhora

done registra a estimativa, o real e os tempos por etapa. plan lê esses dados e usa a mediana dos minutos por etapa, caminhando do escopo mais restrito para o mais amplo e parando no primeiro nível com pelo menos 3 turnos concluídos:

1. este provider + modelo + mesmo tamanho
2. este provider + modelo
3. este provider, qualquer modelo
4. tudo no .eta deste projeto
5. o log compartilhado em TURN_ETA_DIR, mesma ordem
6. caso contrário, 4 minutos por etapa

Mediana em vez de média, para que um turno que demorou muito não arraste todas as estimativas futuras. Apenas os últimos 20 turnos por nível contam. plan imprime qual nível usou, para que o número nunca seja um mistério.

Durante o turno, step combina esse histórico com o ritmo real que este turno está executando, ponderado pela fração concluída: na etapa 1 de 4, o histórico ainda carrega três quartos; na etapa 3, este turno carrega três quartos. Um primeiro passo lento move o horário de término sem sequestrá-lo.