g-ki/agent-skills

Tarefa de Spike

Responda a uma pergunta com profundidade suficiente para tomar uma decisão, dentro do limite de tempo do spike. A entrega é um registro de decisão, não código mesclado.

Entrada

$ARGUMENTS

• Ticket, obrigatório: uma chave do rastreador (ex.: ENG-130) ou um ID local (ex.: T-03) de um ticket com tipo spike. Se não for um spike, pare e aponte para /implement-task.
• --tasks <file>: o arquivo local de tarefas. Se não for fornecido, encontre o *.tasks.md contendo o ticket na pasta RFC local do projeto ignorada pelo git (ex.: .rfcs/), depois em docs/rfcs/.
• --branch <name>: nome do branch para um protótipo, se necessário. Caso contrário <usuário>/<slug-do-projeto>/spike-<branch-da-tarefa>, seguindo a mesma regra de nomenclatura de /implement-task.
• --unattended: iniciado por um orquestrador; ninguém pode responder perguntas. Nunca pergunte; quando você precisaria perguntar, pare e explique no relatório. Trabalhe em sua própria worktree.

Leia o ticket do rastreador se ele estiver publicado (o rastreador é a fonte da verdade para seu conteúdo), caso contrário, do arquivo de tarefas. Os arquivos RFC e de tarefas locais residem apenas na pasta principal do projeto: se você estiver em uma worktree, encontre-a com git worktree list (primeira entrada) e leia-os lá pelo caminho absoluto. Nunca edite arquivos ou execute comandos git na pasta principal, exceto para escrever o registro de decisão conforme descrito abaixo.

1. Enquadre a pergunta

Antes de reunir qualquer coisa, escreva:

• A pergunta, como uma frase que tenha uma resposta ("O Postgres LISTEN/NOTIFY consegue lidar com 2k eventos/s em nosso tamanho de instância?", não "investigar eventos").
• A decisão que ela desbloqueia e quais tickets dependem dela.
• As opções sendo decididas, incluindo "não fazer nada" ou a opção mais simples quando for plausível.
• Critérios de decisão, extraídos da seção DRIVE do RFC quando possível (restrições, valores, resultados essenciais), para que a evidência seja julgada com base no que a equipe já concordou ser importante.
• O limite de tempo do ticket (padrão: cerca de um dia de esforço). Concluído significa que a pergunta foi respondida ou o tempo limite foi gasto, o que ocorrer primeiro.

Se o ticket for muito vago para enquadrar uma pergunta, pare e relate bloqueado com as perguntas que precisam de respostas.

2. Reúna evidências, primeiro as mais baratas

Pare assim que as evidências resolverem a pergunta; não pesquise por completude.

1. O código-fonte: padrões existentes, restrições, tentativas anteriores, comentários e histórico ao redor da área (git log nos caminhos relevantes).
2. Fontes primárias: documentação oficial, changelogs, notas de versão, rastreadores de problemas das bibliotecas ou serviços envolvidos. Prefira estas a posts de blog. Se uma skill deep-research estiver disponível e a pergunta precisar de pesquisa externa ampla, use-a.
3. Meça: quando a leitura não for suficiente (desempenho, compatibilidade, "essa API realmente se comporta assim?"), construa o menor protótipo ou benchmark que responda à pergunta, no branch do spike, a partir do main mais recente. Ele existe para produzir evidências: sem testes além do que a medição precisa, sem polimento, e nunca é mesclado. Envie o branch para que a evidência seja reproduzível, mas não abra um PR.

Mantenha o controle de como você sabe cada coisa: medido (você executou), documentado (uma fonte primária diz isso) ou assumido (inferência). Cite links e caminhos de arquivos.

3. Decida o que recomendar

• Avalie cada opção em relação aos critérios de decisão, usando as evidências.
• Recomende uma opção, com um nível de confiança: alto (medido ou bem documentado), médio (documentado, mas não testado em nosso contexto), baixo (principalmente inferência).
• Quando a confiança for baixa, prefira a opção mais barata de reverter e diga qual sinal o faria mudar.
• Se o limite de tempo se esgotou antes que a pergunta fosse respondida, diga isso claramente: relate o que é conhecido e recomende o menor próximo passo (um spike de acompanhamento mais restrito ou um padrão reversível para prosseguir).

4. Proponha alterações no backlog

A decisão geralmente muda o plano. Proponha, não aplique:

• Tickets a adicionar, no mesmo formato do arquivo de tarefas (título, escopo, arquivos, critérios de aceitação, dependências), cada um com 1 story point.
• Tickets a alterar (escopo, critérios ou dependências) e tickets a remover, cada um com o motivo.
• Seções do RFC que precisam de atualização.

5. Escreva o registro e relate

1. Escreva o registro de decisão usando templates/decision.md para <nome-do-rfc>.<id-do-ticket>.decision.md ao lado do arquivo de tarefas na pasta principal do projeto (o único arquivo que você escreve lá). É um arquivo local e não rastreado, como o RFC.
2. Se o ticket estiver publicado, poste um resumo breve no problema do rastreador: a pergunta, a recomendação e a confiança, e a evidência principal em três a cinco linhas, claramente marcadas como proposto, pendente de aprovação.
3. Se você estiver trabalhando diretamente com o usuário, defina o status do ticket para decisão-proposta no arquivo de tarefas, oriente-o sobre a recomendação e peça-lhe que aprove, escolha outra opção ou estenda o spike. Em modo unattended, deixe os status para o orquestrador.
4. Termine com o relatório:

RESULTADO: decisão-proposta | inconclusivo | bloqueado
TICKET: <id local> / <chave do rastreador ou "não publicado">
REGISTRO: <caminho absoluto para o registro de decisão>
RECOMENDAÇÃO: <uma linha> (confiança: alta | média | baixa)
PROTÓTIPO: <branch ou "nenhum">
NOTAS: <alterações no backlog em uma linha: +N tickets, ~N alterados, -N removidos; ou por que bloqueado>