task-splitter

Task Splitter — execução correta mais barata

Objetivo: concluir a tarefa principal com o menor custo total que ainda atenda à qualidade. Duas alavancas: (1) rotear cada parte do trabalho para o nível mais barato capaz de realizá-la, (2) pagar o custo de contexto de inicialização de cada subagente uma única vez, agrupando trabalho do mesmo nível em um thread.

Leia references/routing-rubric.md antes de pontuar e references/batch-brief-template.md antes de escrever qualquer prompt de lote.

Regras rígidas

• Trabalho T0 nunca gera um agente. Etapas determinísticas (install, mkdir, mv, valor de config, execução de um gerador) são executadas inline no thread principal. Um subagente de inicialização a frio custa mais do que o comando.
• Nunca use subagent_type: "fork" para níveis baratos. Um fork sempre executa no modelo pai e ignora model. Use general-purpose (ou Explore para busca somente leitura) com um model e effort explícitos.
• Este skill autoriza explicitamente a definição de effort em toda chamada de Agente que fizer, usando a tabela de níveis. Sempre passe ambos model e effort.
• Verificação por scripts, não por modelos. Testes, lint, typecheck e build são executados pelo thread principal. Não gaste uma chamada de modelo revisando código que um script pode verificar.
• Escalone apenas a subtarefa com falha, um nível, uma vez. Após uma escalação, pare e pergunte ao usuário.
• Nunca agrupe duas subtarefas que editam o mesmo arquivo em lotes diferentes da mesma onda.

Tabela de níveis (padrões — calibre com o log de roteamento)

Nível	Pontuação	Executa como	Trabalho típico
T0	0	thread principal, shell inline	instalar deps, criar diretórios, renomear, definir valor de env/config
T1	1–3	model: haiku, effort: low	boilerplate seguindo padrão existente, edições de cópia, CRUD simples, docs, fixtures
T2	4–6	model: sonnet, effort: medium	código de funcionalidade normal, componentes, endpoints, testes seguindo padrões existentes
T3	7–8	model: sonnet, effort: high	lógica multiarquivo, gerenciamento de estado, integrações, bugs complexos, autenticação/pagamentos/segurança
T4	9–10	model: opus, effort: high	arquitetura, design transversal, modelo de dados, depuração difícil, desempenho/concorrência

Pesos de custo relativos para a prévia: haiku = 1, sonnet = 3, opus = 5; multiplicador de esforço low = 1, medium = 1.5, high = 2.5. T0 = ~0.

Fluxo de trabalho

Fase 0 — Capturar e persistir

1. Reafirme a tarefa principal em ≤10 linhas: objetivo, restrições, critérios de aceitação, stack, fora do escopo.
2. Derive um slug. Procure por um ledger existente em <projeto>/.claude/task-splitter/ (ls .claude/task-splitter/ 2>/dev/null). Se um corresponder a esta tarefa e tiver subtarefas inacabadas → retome a partir dele (pule para a primeira fase cujo trabalho não está concluído).
3. Caso contrário, crie <projeto>/.claude/task-splitter/<YYYY-MM-DD>-<slug>.md a partir de templates/split-ledger.md e preencha a seção Contexto. Atualize-o após cada fase. No modo de plano, se a escrita de arquivos fora do arquivo de plano não for permitida, coloque o conteúdo do ledger no arquivo de plano sob um cabeçalho ## Ledger e escreva o arquivo real como o primeiro passo T0 após a aprovação.

Fase 1 — Reconhecimento leve

Leia apenas o que a divisão precisa: manifesto (package.json, pyproject, etc.), pontos de entrada, os arquivos que a funcionalidade toca, utilitários existentes para reutilizar. Se uma busca ampla for necessária, use UM agente Explore com model: haiku, effort: low e peça apenas caminhos + descobertas de uma linha. Registre utilitários reutilizáveis e caminhos de arquivo exatos no ledger — eles se tornam os pacotes de contexto que impedem que agentes baratos explorem novamente.

Fase 2 — Dividir

Divida o trabalho em subtarefas atômicas. Cada subtarefa tem: id (S1, S2…), goal (uma frase), files (caminhos exatos, novos ou existentes), depends_on (ids), done_check (um comando como pnpm test foo ou um critério preciso), type (tag curta: install, scaffold, component, endpoint, test, migration, refactor, config, docs, debug, design…). Atômico = um agente pode concluí-la sem decisões que pertencem a outra subtarefa. Extraia decisões de design para sua própria subtarefa inicial (frequentemente T4) para que subtarefas posteriores sejam mecânicas e baratas.

Fase 3 — Pontuar e rotear

Pontue cada subtarefa com a rubrica de 5 dimensões em references/routing-rubric.md (ambiguidade, profundidade de raciocínio, raio de explosão, contexto necessário, novidade; 0–2 cada), aplique as regras de substituição, então mapeie pontuação → nível. Em seguida, verifique ~/.claude/task-splitter/routing-log.md (se existir): se um type foi escalado em ≥2 de suas últimas 3 execuções em um nível, inicie-o um nível acima; se passou na primeira tentativa ≥3 vezes seguidas um nível abaixo do que você escolheu, considere reduzir um nível.

Fase 4 — Agrupar em lotes

1. Construa ondas de dependência: onda 1 = subtarefas sem deps não atendidas; onda N = aquelas cujas deps estão todas em ondas anteriores.
2. Dentro de cada onda, agrupe por (model, effort), depois por área de código (mesma pasta / módulo de funcionalidade) para que um agente carregue arquivos relacionados uma vez.
3. Limites por lote: ≤6 subtarefas ou uma área coerente; nenhum arquivo editado por dois lotes na mesma onda (mova a subtarefa conflitante para o mesmo lote ou para a próxima onda).
4. Mescle lotes pequenos: uma subtarefa T1 solitária junta-se a outro lote T1 na mesma onda, se existir; uma subtarefa T1 solitária que é quase mecânica pode ser feita inline.
5. Subtarefas T0 são agrupadas em uma única etapa inline no início de sua onda.

Fase 5 — Prévia de custo (portão de aprovação)

Escreva no arquivo de plano (ou mostre ao usuário, fora do modo de plano):

| Onda | Lote | Modelo / esforço | Subtarefas | Custo est. |
|------|-------|----------------|----------|-----------|
| 1    | inline| main / shell   | S1, S2   | ~0        |
| 1    | B1    | haiku / low    | S3, S4   | 2         |
| 1    | B2    | sonnet / medium| S5       | 4.5       |
| 2    | B3    | opus / high    | S6       | 12.5      |
Total ≈ 19 unidades  (linha de base tudo-opus/high ≈ 75 unidades → ~75% mais barato)

Custo est. = número de subtarefas × peso do modelo × multiplicador de esforço. Inclua a linha de base tudo-opus/high para que a economia seja visível. No modo de plano, termine com ExitPlanMode; não execute antes da aprovação.

Fase 6 — Executar

Para cada onda, em ordem:

1. Execute a etapa inline T0 da onda.
2. Lance todos os lotes da onda em UMA mensagem (chamadas de Agente paralelas): Agent(subagent_type: "general-purpose", model: <modelo do nível>, effort: <esforço do nível>, description: "<onda>/<lote>: <curto>", prompt: <breve>). Construa cada briefing a partir de references/batch-brief-template.md. O preâmbulo compartilhado deve ser byte-idêntico em todos os lotes (amigável ao cache de prompt) — coloque o conteúdo variável depois dele.
3. Aguarde cada lote da onda relatar antes de iniciar a próxima onda. Nunca escreva ou adivinhe o resultado de um agente pendente.
4. Atualize o ledger com o status de cada lote e os arquivos relatados.

Fase 7 — Verificar e escalar

1. Após cada onda, o thread principal executa os comandos done_check das subtarefas mais as verificações globais baratas do projeto (typecheck / lint / testes afetados).
2. Uma subtarefa com falha é executada novamente sozinha (ou com outras falhas do mesmo novo nível) em um nível acima, com a saída com falha e o relatório do agente anterior anexados.
3. Máximo de uma escalação por subtarefa. Se ainda falhar, pare e pergunte ao usuário com um breve diagnóstico. Falhas T4 vão diretamente para o usuário.

Fase 8 — Registrar e aprender

1. Marque o ledger como completo: nível final por subtarefa, passou/escalou, arquivos alterados.
2. Acrescente uma linha por subtarefa em ~/.claude/task-splitter/routing-log.md (crie a pasta/arquivo se estiver faltando; nunca dentro do repositório git do skill): YYYY-MM-DD | <projeto> | <type> | <nível inicial> | <nível final> | first-pass|escalated|failed
3. Relate ao usuário em ≤10 linhas: o que foi feito, unidades de custo final vs linha de base, quaisquer escalações, algo deixado em aberto.

Convenções de saída

• Mantenha o thread principal enxuto: agentes retornam relatórios curtos, não conteúdos de arquivo.
• Forneça ao usuário tabelas, não prosa, para a divisão e a prévia de custo.
• Se toda a tarefa pontuar ≤3 no total, ou tiver ≤2 subtarefas, informe isso e apenas faça diretamente — dividi-la custaria mais do que economiza.