name: create-tasks description: 'Decompose scope or spec into task backlog with phases, dependencies, criticality. Triggers: "criar tarefas", "backlog", "task list", "decomposicao". Skip for executing tasks (use execute-task) or technical plan (use plan).' argument-hint: "[descricao do escopo ou caminho para documento de referencia]" allowed-tools: - Read - Write - Glob - Grep - Edit - Agent

Skill: Criar Backlog de Tarefas¶

Crie um documento de backlog de tarefas tecnicas seguindo o padrao estruturado abaixo.

Pre-requisitos¶

Recomendado (fluxo SDD): plan.md e spec.md ja existentes em docs/specs/{feature}/. Com eles, o backlog se liga a fases tecnicas claras.

Alternativa standalone: descricao textual do escopo ou lista de features. Neste caso, salva em docs/tasks-{nome-escopo}.md.

Proximos passos¶

/analyze — validar consistencia entre spec, plan e tasks
/execute-task {id} — comecar execucao pela primeira tarefa critica
/review-task — acompanhar progresso conforme tarefas sao concluidas

Argumentos¶

$ARGUMENTS

Instrucoes¶

Analise o argumento fornecido. Ele pode ser: 1. Descricao do escopo: Uma descricao textual do que o MVP/projeto deve cobrir 2. Documento de referencia: Um arquivo existente com requisitos, casos de uso ou especificacoes 3. Lista de funcionalidades: Lista de features/modulos a serem organizados em tarefas

Deteccao de Origem (Spec vs Standalone)¶

ANTES de iniciar, determine se o argumento se origina de uma especificacao:

Verifique se o argumento referencia um arquivo em docs/specs/ (ex: docs/specs/foo/spec.md)
Verifique se o argumento menciona o nome de uma spec existente — liste docs/specs/*/spec.md com Glob
Se o contexto da conversa indica que uma spec foi criada/usada recentemente, considere-a como origem

Se originado de uma spec (docs/specs/{spec-name}/spec.md): - Salvar em: docs/specs/{spec-name}/tasks.md - Usar o conteudo da spec como documento de referencia principal

Se chamado de forma isolada (sem spec associada): - Manter o comportamento padrao: docs/tasks-{nome-escopo}.md

Consumir gaps abertos do checklist (origem SDD)¶

Se a origem e uma spec, ANTES de decompor leia docs/specs/{name}/checklists/*.md e colete os items ainda abertos marcados [Gap] ou [Conflict] (e {humano} pendentes que impliquem trabalho). Cada um vira uma tarefa de resolucao de requisito no backlog — tipicamente numa FASE inicial de fundacao/requisitos — com Ref: checklists/{dominio}.md CHK0NN.

Razao: o checklist roda depois do clarify no pipeline, entao os gaps que ele revela nao tem outra fase natural para serem fechados a nao ser esta. Sem este consumo, o gap morre no checklist (write-only) e a feature e implementada sobre um requisito que ninguem fechou. Fecha o loop checklist -> backlog sem reordenar o pipeline.

Fluxo de Criacao¶

1. ANALISE       Entender escopo, requisitos e documentacao existente
     |
2. ESTRUTURA     Definir fases, dependencias e caminho critico
     |
3. DECOMPOSICAO  Quebrar em tarefas e subtarefas tecnicas
     |
4. PRIORIZACAO   Classificar criticidade e ordenar execucao
     |
5. GERACAO       Produzir documento no formato padrao
     |
6. VALIDACAO     Verificar completude e consistencia

Padrao do Documento¶

Estrutura Obrigatoria¶

O documento DEVE conter todas as secoes abaixo, nesta ordem:

Cabecalho com titulo, escopo e legendas
Fases numeradas sequencialmente (FASE 1, FASE 2, ...)
Tarefas dentro de cada fase (numeracao hierarquica: 1.1, 1.2, ...)
Subtarefas como checkboxes (numeracao: 1.1.1, 1.1.2, ...)
Matriz de Dependencias (diagrama ASCII ou Mermaid)
Resumo Quantitativo (tabela com totais por fase)
Cobertura (o que esta incluido e excluido do escopo)

Template Completo¶

Ver templates/tasks.md (mesmo diretorio desta skill). Estrutura:

Cabecalho com escopo + legendas de status e criticidade
Fases numeradas (FASE 1, FASE 2, ...)
Tarefas com numeracao hierarquica (1.1, 1.2, ...) e tag [C]/[A]/[M]
Subtarefas como checkboxes numerados (1.1.1, 1.1.2, ...)
Matriz de Dependencias (Mermaid flowchart)
Resumo Quantitativo, Escopo Coberto, Escopo Excluido

Regras de Decomposicao¶

Nomenclatura¶

Nivel	Formato	Exemplo
Fase	`FASE {N} - {Nome}`	`FASE 1 - Fundacao e Infraestrutura`
Tarefa	`{N}.{M} {Nome} [{Criticidade}]`	`1.1 Setup do Projeto [A]`
Subtarefa	`{N}.{M}.{K} {Descricao}`	`1.1.1 Criar solution com estrutura hexagonal`

Granularidade¶

Nivel	Criterio	Tamanho Ideal
Fase	Agrupamento logico por dominio ou camada	3-8 tarefas
Tarefa	Entregavel coeso e independente	3-15 subtarefas
Subtarefa	Acao atomica executavel em 1-4 horas	1 checkbox

Principios¶

Cada subtarefa deve ser atomica: uma acao clara e verificavel
Cada tarefa deve ser coesa: subtarefas relacionadas ao mesmo entregavel
Cada fase deve ser sequenciavel: dependencias claras entre fases
Criticidade herda para baixo: subtarefas herdam criticidade da tarefa pai
Referencia a documentacao: vincular tarefas a UCs, ADRs ou specs quando existirem
Testes sao subtarefas: toda tarefa de implementacao deve ter subtarefa de teste

Classificacao de Criticidade¶

Nivel	Criterio	Quando Usar
`[C]` Critico	Impacto financeiro, regulatorio ou de seguranca	Operacoes monetarias, compliance, SLAs
`[A]` Alto	Funcionalidade core sem a qual o sistema nao opera	APIs principais, integracao, persistencia
`[M]` Medio	Necessario mas pode ser adiado sem impacto imediato	Dashboards, relatorios, cache, observabilidade

Organizacao de Fases¶

Fases devem seguir ordem logica de construcao. Os exemplos abaixo sao ilustrativos — adaptar a estrutura as camadas reais do projeto:

Exemplo para projeto com backend + persistencia + frontend:

FASE 1 - Fundacao (infra, setup, CI/CD, migrations iniciais)
FASE 2 - Dominio (entidades, regras, contratos)
FASE 3 - Backend (persistencia, servicos, handlers/endpoints)
FASE 4 - Integracao (mensageria, storage, clientes externos)
FASE 5 - Frontend (tipos, chamadas API, componentes, paginas)
FASE 6 - Testes e Qualidade (unit, integracao, lint, review)
FASE 7 - Observabilidade (logs, metricas, dashboards, alertas)

Exemplo para biblioteca/CLI:

FASE 1 - Fundacao (estrutura do projeto, build, CI)
FASE 2 - Dominio (tipos, interfaces publicas)
FASE 3 - Implementacao (funcionalidades core)
FASE 4 - Testes (unit, contract, property-based)
FASE 5 - Documentacao e release

Para projetos multi-modulo: Use Agent para ler documentacao de multiplos modulos/servicos em paralelo ao analisar o escopo. Isso economiza tempo ao gerar tarefas que cruzam fronteiras.

Matriz de Dependencias¶

Use formato Mermaid ou ASCII para expressar dependencias:

flowchart TD
    F1[Fase 1 - Fundacao]
    F2[Fase 2 - Dominio]
    F3[Fase 3 - Feature A]
    F4[Fase 4 - Feature B]
    F5[Fase 5 - Observabilidade]

    F1 --> F2
    F2 --> F3
    F2 --> F4
    F3 --> F5
    F4 --> F5

Sincronizacao com Codigo¶

tasks.md e fonte de verdade declarada, mas em execucoes longas o codigo e o documento drifam — historicamente 11 ondas consecutivas tiveram FASE marcada [ ] enquanto o codigo ja existia, com testes, no repositorio. Sub-FASEs criadas via Decisao nunca voltaram ao tasks.md. O custo: /review-task re-processa tarefas concluidas e o agente perde tempo re-investigando estado ja resolvido.

Protocolo de sincronizacao¶

A sincronizacao acontece em TRES pontos do ciclo de vida da tarefa, cada um com responsabilidade clara:

1. Antes de executar (Etapa 2 do /execute-task)

Para cada subtarefa [ ] da tarefa-alvo, fazer grep -l (ou Glob) por arquivos canonicos antes de comecar:

# Exemplo: subtarefa "1.1.3 Implementar UserRepository" — checar antes
test -f src/repositories/UserRepository.ts \
  && grep -q "class UserRepository" src/repositories/UserRepository.ts \
  && echo "JA EXISTE — marcar [x] com nota 'validado empiricamente onda-NNN'"

Se ja existe, marcar [x] ANTES de prosseguir, com nota inline:

- [x] 1.1.3 Implementar UserRepository <!-- validado empiricamente onda-042 -->

2. Decisao cria sub-FASE (sub-tarefas emergentes)

Quando uma Decisao tomada durante execucao cria trabalho novo (ex: "emergiu sub-FASE 6.4 para Helper de payload"), o agente DEVE inserir o novo bloco no tasks.md no MESMO commit que registra a Decisao. Nao deixar como "vou anotar depois" — essa intencao morre na proxima onda.

Formato sugerido (insercao na fase apropriada):

### N.M.K-bis {Nome da Sub-FASE Emergente} `[criticidade]`

Ref: dec-NNN (sub-FASE emergiu durante execucao de N.M.K)

- [ ] N.M.K-bis.1 {subtarefa nova}
- [ ] N.M.K-bis.2 {subtarefa nova}

3. Hook pos-onda (orquestrador)

Apos cada onda, o orquestrador compara git diff --name-only HEAD~1..HEAD contra checkboxes do tasks.md afetados. Se ha arquivos modificados que correspondem a checkboxes ainda [ ], emite aviso na trilha de decisao (nao bloqueia). Ver agente-00c-orchestrator.md §Loop principal.

Paridade de tipos compartilhados¶

Quando uma FASE replica tipos em outro pacote (ex: Zod local em web/ vs packages/shared-types/), incluir subtarefa obrigatoria:

- [ ] N.M.K Replicar tipo Foo em web/src/types/foo.ts
- [ ] N.M.K+1 Verificar paridade EXATA com packages/shared-types/src/foo.ts
- [ ] N.M.K+2 Teste smoke: comparar z.enum().options entre os dois pacotes

Razao: a execucao-fonte teve drift snake_case vs camelCase descoberta 40 ondas depois porque os testes parseavam mocks (nao payload real), mascarando a divergencia. Paridade exigida explicitamente no backlog forca verificacao antes do drift se acumular.

Checklist de Qualidade¶

Antes de finalizar o documento, verifique:

Todas as fases tem pelo menos 1 tarefa
Todas as tarefas tem pelo menos 3 subtarefas
Todas as tarefas tem tag de criticidade [C], [A] ou [M]
Subtarefas de teste existem para tarefas de implementacao
Numeracao hierarquica esta consistente (sem saltos)
Matriz de dependencias reflete ordem real de execucao
Resumo quantitativo bate com contagem real
Escopo coberto e excluido estao documentados
Referencias a documentacao existente estao corretas

Saida Esperada¶

Detecte a origem — verifique se o argumento vem de uma spec em docs/specs/
Analise o escopo fornecido nos argumentos
Leia documentacao existente no projeto (UCs, ADRs, specs, DER) para extrair requisitos
Proponha a estrutura de fases ao usuario antes de detalhar
Gere o documento completo no formato padrao
Salve o arquivo no caminho correto:
Se originado de spec: docs/specs/{spec-name}/tasks.md
Se standalone: docs/tasks-{nome-escopo}.md
Ou caminho sugerido pelo usuario (override manual sempre prevalece)

Pergunte ao usuario se necessario:¶

Se ha documentacao de referencia para consultar
Escopo que deve ser incluido/excluido
Preferencia de granularidade (mais ou menos subtarefas)

Configuracao¶

config.json (mesmo diretorio desta skill) pode customizar: - criticality_levels — tags customizadas alem de [C]/[A]/[M] - output_paths.spec_derived e output_paths.standalone — onde salvar - phase_prefix — default "FASE", pode ser "PHASE", "STAGE", etc. - subtask_granularity_hours — janela esperada de esforco por subtarefa

Se config.json ausente, usar defaults documentados no template.

Scripts auxiliares¶

scripts/next-task-id.sh — calcula proximo ID hierarquico dentro de uma fase ou tarefa em um tasks.md existente (util para append deterministico):

bash skills/create-tasks/scripts/next-task-id.sh 1 tasks.md     # → 1.3
bash skills/create-tasks/scripts/next-task-id.sh 1.2 tasks.md   # → 1.2.4

scripts/validate-tasks-template.sh — gate deterministico de fidelidade ao template. Verifica se um tasks.md gerado conforma a templates/tasks.md: prefixo de fase (phase_prefix), checkboxes - [ ], tag de criticidade nas tarefas, legendas, Matriz de Dependencias, Resumo Quantitativo, Escopo Coberto/Excluido. Emite FINDING|<severity>|<code>|<msg> (critical quebra downstream; warning e drift de metadados) e um RESULT. Exit 0 conformante, 1 drift, 2 uso/arquivo:
```
bash skills/create-tasks/scripts/validate-tasks-template.sh \
  docs/specs/foo/tasks.md --config skills/create-tasks/config.json
```
Os orquestradores agente-00c/feature-00c o rodam como pre-gate apos a etapa create-tasks (antes do validate-docs-rendered): critical vira Decisao + tentativa de Edit re-normalizando ao template; warning vira Decisao informativa.

Gotchas¶

Deteccao de origem e OBRIGATORIA antes de escolher o path de salvamento¶

Se a chamada veio de uma spec em docs/specs/{name}/, o tasks.md vai em docs/specs/{name}/tasks.md, NAO em docs/tasks-*.md. Criar o arquivo fora do diretorio da spec quebra a composicao SDD — as skills downstream (analyze, execute-task) nao encontram o backlog.

Toda tarefa de implementacao precisa de subtarefa de teste¶

Decomposicao sem teste e incompleta. Se a tarefa e "Implementar endpoint X", deve haver uma subtarefa "Escrever testes de integracao para endpoint X". A skill checa isso — nao relaxe.

Criticidade `[C]/[A]/[M]` em TODAS as tarefas¶

Tarefa sem criticidade nao permite priorizacao pelo /review-task. [C] nao e "critico em geral" — e "impacto financeiro/regulatorio/SLA direto". [A] e funcionalidade core sem a qual o sistema nao opera. [M] e o resto.

Granularidade: subtarefa = 1-4 horas de trabalho atomico¶

Subtarefa gigante (multi-dia) e tarefa disfarcada. Se aparece "1.2.1 Implementar autenticacao OAuth2 completa", decomponha mais: setup do provider, handlers de callback, validacao de token, logout, cada um vira subtarefa separada.

Referenciar documentacao existente (UCs, ADRs, specs) em Ref:¶

Tarefa orfa sem Ref: dificulta entender contexto quando alguem executa semanas depois. Se existe UC-XXX, ADR-YYY ou spec que origina a tarefa, referencie explicitamente.

Matriz de dependencias deve refletir ordem REAL de execucao¶

Diagrama Mermaid desenhado "como deveria ser" mas que contradiz a ordem das fases (ex: Fase 5 depende de Fase 7) indica que a estrutura esta errada. Revisite a ordenacao antes de publicar.

Nao confundir "escopo excluido" com "fora do MVP"¶

Escopo excluido = explicitamente NAO faz parte deste backlog (documentar porque). Fora do MVP = pode fazer parte no futuro mas fora desta rodada. Sao colunas diferentes do relatorio final.

Gerar o backlog inline "esquecendo" o template e um drift silencioso¶

Quando o backlog e produzido inline (sub agente que registra a skill mas gera o conteudo de cabeca), e facil omitir o skeleton: checkboxes - [ ], o prefixo FASE, as legendas, a Matriz de Dependencias, o Resumo Quantitativo e as secoes Escopo Coberto/Excluido. O gate validate-docs-rendered NAO pega isso — ele so checa render (Mermaid, links, frontmatter). Quem pega e o gate deterministico validate-tasks-template.sh (ver Scripts auxiliares). Rode-o sempre que gerar um tasks.md fora do fluxo interativo da skill; sem ele o backlog malformado segue para execute-task/review-task e quebra a contagem de metricas (subtarefas sem checkbox contam 0).