g-ki/agent-skills

Implementar Tarefa

Entregue um ticket de 1 ponto como um PR para revisão, contendo exatamente o que o ticket pede e nada mais.

Entrada

$ARGUMENTS

• Ticket, obrigatório: uma chave do rastreador (ex.: ENG-123) ou um ID local (ex.: T-04). Se ausente, liste os tickets prontos (status open, dependências mescladas) em ordem de caminho crítico primeiro e pergunte qual pegar. No modo não supervisionado, reporte blocked.
• --tasks <file>: o arquivo de tarefas local. Se não for fornecido, procure pelo *.tasks.md contendo o ticket na pasta RFC local do projeto, ignorada pelo git (ex.: .rfcs/), depois docs/rfcs/.
• --base <branch>: a branch da qual partir e que será alvo do PR. Padrão: main. Uma base diferente de main significa que o PR está empilhado em outro PR não mesclado.
• --branch <name>: o nome da branch a ser usado. Caso contrário, siga a regra de nomenclatura no passo 1.
• --feedback <pr>: não implemente; trate o feedback de revisão em um PR existente (veja a última seção).
• --unattended: você foi iniciado por um orquestrador e ninguém pode responder perguntas. Nunca pergunte; quando precisar perguntar, pare e explique no relatório. Faça seu trabalho em sua própria worktree.

Onde o ticket e os arquivos locais estão

• Rastreador primeiro. Se o ticket tiver uma chave de rastreador (como argumento ou no campo Tracker: do arquivo de tarefas), busque-o através da ferramenta de rastreador conectada (Linear, Jira, GitHub Issues, …). Quando publicado, o rastreador é a fonte da verdade para o conteúdo do ticket; se ele estiver cancelado ou concluído lá, pare e reporte.
• Arquivo de tarefas local caso contrário, e para campos que faltem no issue do rastreador (arquivos, fora de escopo). RFCs e arquivos de tarefas são documentos locais do desenvolvedor, não rastreados, portanto existem apenas na pasta principal do projeto, não em uma worktree. Se você estiver em uma worktree, encontre a pasta principal com git worktree list (a primeira entrada) e leia os arquivos lá pelo caminho absoluto. Trate a pasta principal como somente leitura: nunca edite, faça checkout ou execute comandos git nela.
• Nunca commite RFC, anotações ou arquivos de tarefas. Faça stage de arquivos por caminho explícito, não git add -A.

1. Escolha o ticket

• Leia o ticket (veja acima), incluindo seus critérios de aceitação e dependências. Se seu tipo for spike, pare: spikes produzem uma decisão, não um PR; aponte para /spike-task (não supervisionado: reporte blocked).
• Uma dependência é satisfeita quando seu PR é mesclado em main (verifique o estado do PR com gh, ou o status da dependência pr-merged/done), ou quando a branch base é a própria branch da dependência (empilhamento). Uma dependência do tipo spike é satisfeita apenas quando está done, significando que sua decisão foi aprovada e o backlog refinado. Se alguma dependência não estiver satisfeita, pare e diga qual.
• Certifique-se de que a árvore de trabalho está limpa, faça fetch e crie a branch a partir do origin/<base> mais recente.
• Nome da branch (a menos que --branch tenha sido fornecido): <username>/<project-slug>/<task-branch>.
  • username: o prefixo das branches existentes do usuário se seguirem este padrão, caso contrário, seu login do GitHub (gh api user --jq .login).
  • project-slug: do cabeçalho Project slug: do arquivo de tarefas, ou o nome da RFC em kebab case.
  • task-branch: a chave do rastreador mais um slug curto, ex.: eng-123-add-v2-flag (a chave permite que integrações do rastreador liguem o PR), ou t-04-add-v2-flag se não publicado.
• Se você estiver trabalhando diretamente com o usuário (não não supervisionado), defina o status do ticket para in progress no arquivo de tarefas e no rastreador se sua integração com GitHub não fizer isso.

2. Carregue apenas o que o ticket precisa

Leia o ticket, a seção do RFC da qual ele depende e os arquivos que nomeia. Em seguida, rastreie o fluxo real: chamadores, helpers existentes e os testes ao lado do código que você alterará. Leia o suficiente para entender o problema completamente, mas não carregue todo o RFC ou histórico da sessão; o ticket foi escrito para ser autossuficiente. Se não for, isso é uma lacuna a ser reportada, não uma suposição.

3. Escreva os testes primeiro

Transforme cada critério de aceitação em um teste, usando o framework de teste, localização e estilo existentes do repositório. Execute-os e confirme que eles falham pelo motivo correto. Um teste focado por critério é suficiente: sem novas utilidades de teste, fixtures ou helpers, a menos que um padrão existente os exija. Tickets puramente mecânicos (ex.: adicionar uma flag) podem não precisar de novos testes se o critério for verificado por testes existentes ou pelo verificador de tipos; diga isso no PR.

4. Implemente a menor alteração completa

"Completa" significa que todo critério de aceitação passa. "Menor" significa nada além disso. Isso segue a abordagem ponytail; se uma skill ponytail estiver instalada, carregue-a agora em seu nível padrão e deixe-a governar este passo.

Caso contrário, escolha a primeira opção que funcionar:

1. A necessidade já é atendida? Se o código existente já satisfaz os critérios, pare e proponha fechar o ticket.
2. Reutilize o que o código já tem: helpers, tipos, padrões.
3. Use a biblioteca padrão, depois recursos nativos da plataforma (restrições de banco de dados, inputs HTML embutidos, CSS antes de JS), depois dependências já instaladas.
4. Só então escreva novo código, o mínimo que funcionar.

Ao escrevê-lo:

• Sem estrutura especulativa. Sem interfaces com uma implementação, sem fábricas para um produto, sem configuração para valores que nunca mudam, sem andaimes "para depois". Prefira editar um arquivo existente a criar um novo.
• Combine com o código ao redor: nomenclatura, tratamento de erros, estrutura. O diff deve parecer que o código o escreveu.
• Comentários apenas onde o código não fala. Não narre o que o código faz, reafirme o ticket ou deixe código comentado ou saída de depuração. O único comentário que vale a pena adicionar é em uma simplificação deliberada: nomeie o limite e quando atualizá-lo, para que ninguém o "corrija" acidentalmente.
• Corrija bugs na raiz. Verifique cada chamador antes de alterar uma função compartilhada.
• Nunca minimize a segurança. Validação de entrada em limites de confiança, tratamento de erros que evite perda de dados, segurança e acessibilidade básicas são sempre feitos corretamente, mesmo que o ticket não os especifique.

5. Proteja o escopo

Se o ticket se revelar maior que 1 ponto (mais de cerca de um dia, uma segunda preocupação aparecer ou um critério não puder ser atendido sem tocar em áreas não relacionadas), pare. Não commite nada além do que está limpo, explique o que encontrou e proponha uma divisão como novos tickets para aprovação: escreva-os no arquivo de tarefas ao trabalhar com o usuário, ou no relatório quando não supervisionado. Problemas não relacionados que você notar vão para as notas do PR, não para o diff. Nunca enfraqueça ou reinterpreta um critério de aceitação para fazê-lo passar.

6. Verifique e abra o PR

1. Execute os testes, linter e verificador de tipos da maneira que o repositório faz. Se a alteração tiver comportamento em tempo de execução e você puder executar /verify, faça; caso contrário, exercite o comportamento com os comandos de execução ou verificação do próprio projeto.
2. Releia o diff completo você mesmo: cada linha alterada deve remeter a um critério de aceitação. Remova formatação não relacionada, renomeios e arquivos perdidos, e certifique-se de que nenhum RFC local ou arquivo de tarefas escapou.
3. Faça commit seguindo o estilo de commit do repositório, faça push e abra o PR pronto para revisão (não draft, para que a automação de revisão execute, a menos que o usuário tenha pedido um draft) contra a branch base, usando templates/pr.md. Coloque a chave do rastreador no título e link o issue do rastreador na descrição. Se a base não for main, diga em qual PR ele está empilhado e que esse precisa mesclar primeiro. Se você não puder abrir PRs daqui, faça push da branch e inclua o texto do PR em sua resposta.
4. Se você estiver trabalhando diretamente com o usuário, defina o status do ticket para pr-open (ou pr-draft) e preencha Branch / PR: no arquivo de tarefas, e mova o issue do rastreador para seu estado de revisão se sua integração com GitHub não fizer isso. Não supervisionado, deixe os status para o orquestrador.
5. Termine com o relatório abaixo. Com um usuário presente, uma versão de duas ou três linhas é suficiente.

Tratando feedback de PR (--feedback)

Você recebe um PR e uma lista de itens de revisão a tratar (links de comentários mais o que fazer).

1. Busque e faça checkout da branch do PR em sua worktree. Leia o ticket e os itens; leia o diff atual.
2. Trate cada item com a menor alteração que o resolva, sob as mesmas regras do passo 4. Fique dentro do escopo do ticket: se um item pedir algo além dele, não construa; reporte como acompanhamento.
3. Adicione novos commits em vez de alterar ou forçar push, para que os revisores vejam o que mudou desde sua revisão. Execute os testes e faça push.
4. Responda em cada thread de comentário tratada com uma linha dizendo o que mudou e o SHA curto do commit. Para itens que você foi instruído a responder sem alterar código, responda com o texto fornecido. Se você concluir que um item não deve ser alterado, não discuta na thread; deixe-o e explique em seu relatório.
5. Termine com o relatório, usando done se todos os itens foram tratados, blocked caso contrário.

Relatório

Termine sua mensagem final exatamente com este bloco, para que um orquestrador possa analisá-lo:

RESULT: done | blocked | needs-split | already-met
TICKET: <id local> / <chave do rastreador ou "unpublished">
PR: <url ou "none">
BRANCH: <branch ou "none">
SKIPPED: <limites deliberados ou itens não tratados, ou "none">
NOTES: <uma ou duas linhas: por que bloqueado, o que dividir, acompanhamentos, problemas não relacionados encontrados>