yasukei/agent-skills

Criação de issues no GitHub

Skill para escrever issues no GitHub seguindo um formato definido pelo usuário. O objetivo é criar issues que, ao serem lidas, possam ser imediatamente executadas e tenham critérios claros para serem consideradas concluídas. Especialmente os Critérios de Aceitação (Acceptance criteria) serão usados posteriormente como condições de conclusão durante a implementação (issue-to-pr) e revisão (pr-review), portanto devem ser escritos de forma verificável.

1. Verificar primeiro os templates do repositório

Se o repositório possui templates, eles têm prioridade sobre os templates deste skill. Locais a verificar:

• .github/ISSUE_TEMPLATE/ contendo *.md e *.yml / *.yaml (config.yml é um arquivo de configuração, não um template)
• .github/ISSUE_TEMPLATE.md, ISSUE_TEMPLATE.md na raiz, docs/ISSUE_TEMPLATE.md
• Se nenhum dos anteriores existir, verificar o repositório comum da organização <owner>/.github nos mesmos locais

Se houver um clone local, examine os arquivos diretamente. Caso contrário, use gh api repos/<owner>/<repo>/contents/.github/ISSUE_TEMPLATE para obtê-los.

Quando um template for encontrado:

• Escolha o que corresponde ao tipo de issue que está criando (tarefa / bug), com base no nome do arquivo, name, about e labels.
• Mantenha a estrutura de cabeçalhos do template; não misture os cabeçalhos deste skill. Apenas informações importantes que não tenham um local específico podem ser adicionadas brevemente ao final.
• Se for um formulário YAML (issue form), o GitHub salva o conteúdo enviado como um corpo onde cada attributes.label vira um cabeçalho ### <label>. Monte o corpo da mesma forma e preencha todos os campos required: true.
• Reflita o title (prefixo), labels e assignees definidos no frontmatter / definição do formulário.

Se não houver um template para o tipo desejado (por exemplo, existe template de bug mas não de tarefa), use o template deste skill apenas para aquele tipo.

2. Determinar o tipo

• Tarefa: nova funcionalidade, melhoria, refatoração, documentação, CI, pesquisa, etc. (algo a ser feito). → Template de tarefa
• Bug: correção de algo que não está funcionando conforme o esperado. → Template de bug

Em caso de dúvida, decida com base em "o comportamento atual viola a especificação?". Se sim, é bug.

3. Template de tarefa

## Goal

<O que será alcançado em 1-2 frases. Inclua uma breve justificativa do porquê é necessário>

## Scope

- <O que será feito. Se houver vários blocos, agrupe com **subtítulos em negrito**>

## Out of scope

- <O que não será feito. Esclareça áreas adjacentes que poderiam ser confundidas>

## Acceptance criteria

- <Condições verificáveis de conclusão. Testes, CI, resultados de comandos, etc., em formato observável>

## Depends on

- #<número>

Part of #<número da issue pai>.

Dicas de escrita:

• Goal deve incluir não apenas "o quê", mas também "por quê" em uma frase. Isso permite que leitores futuros entendam a prioridade e a lógica da decisão.
• Scope deve ter granularidade que não deixe o implementador em dúvida: inclua nomes de tipos, comandos, arquivos, etc. Itens trazidos de revisões anteriores devem ser separados com subtítulos que indiquem isso.
• Out of scope evita expansão do escopo ao deixar claro o que não será incluído. Se realmente não houver nada, escreva - None e mantenha a seção (para que fique claro que não foi esquecida).
• Acceptance criteria devem ser escritos de forma que um terceiro possa verificar: em vez de "a funcionalidade X foi implementada", escreva "o teste para X existe e passa" ou "o CI executa Y e tem sucesso".
• Depends on lista issues que precisam ser concluídas antes, usando - #número (o GitHub exibe com o título). Se não houver, escreva - None.
• Se a issue for uma subtarefa de uma issue pai, adicione Part of #<número>. ao final.
• Apenas adicione uma seção ## Notes após os Critérios de Aceitação se houver materiais de referência, links ou decisões pendentes. Não force a criação.

4. Template de bug

## Summary

<O que está acontecendo, em 1-2 frases>

## Steps to reproduce

1. <Passo>
2. <Passo>

## Expected behavior

<O que deveria acontecer>

## Actual behavior

<O que realmente acontece. Cole mensagens de erro ou logs em blocos de código>

## Environment

- Version / commit: <versão ou hash do commit>
- <SO / navegador / Node, etc., conforme relevante>

## Acceptance criteria

- Seguindo os passos acima, o comportamento esperado é alcançado
- Um teste de regressão que reproduza este bug foi adicionado e passa

## Notes

<Suspeita da causa, issues/PRs relacionados, workarounds, etc. Se não houver, omita esta seção>

Dicas de escrita:

• Escreva apenas passos, ambiente e logs que você obteve do usuário ou verificou pessoalmente. Para itens desconhecidos, não invente: escreva Unknown ou pergunte ao usuário. Passos de reprodução inventados podem desviar a investigação.
• Separe suspeitas da causa (fato) do comportamento real (Actual behavior) colocando-as em Notes. Misturar sintomas com hipóteses torna a issue difícil de ler se a hipótese estiver errada.
• Se a direção da correção já estiver definida, coloque-a também em Notes.

5. Título, labels e metadados

• O título deve seguir o formato <área>: <descrição> (exemplo: core: data types, tree IR, and UI–runtime protocol). A área deve corresponder a labels existentes no repositório, como area:*. Para bugs, descreva o sintoma, não a correção (exemplo: runtime: TON timer does not fire after coldReset).
• Escolha labels entre as existentes usando gh label list. Além das labels de área, adicione bug se existir e for um bug. Não crie labels inexistentes.
• Se o milestone ou a issue pai forem conhecidos, configure-os.
• O idioma do título e do corpo deve seguir o das issues e PRs existentes no repositório (verifique com gh issue list --state all --limit 10 e gh pr list --state all --limit 10). Se não houver issues ou PRs existentes, escreva em japonês.
• Os nomes das seções (Goal, Scope, Summary, Steps to reproduce, etc.) devem permanecer em inglês mesmo que o corpo seja em outro idioma. No entanto, se estiver usando um template do repositório, use os cabeçalhos desse template.

6. Criar a issue

Escreva o corpo em um arquivo temporário e passe-o com --body-file (para evitar que o shell distorça o conteúdo).

gh issue create --repo <owner>/<repo> \
  --title "<title>" --body-file /tmp/issue-body.md \
  --label "<label>" --milestone "<milestone>"

• Se o usuário pediu explicitamente para "criar", crie diretamente. Se pediu apenas um rascunho, ou se grande parte do conteúdo foi inferido, mostre o corpo para o usuário confirmar antes de criar.
• Se houver uma issue pai, além de escrever Part of #N. no corpo, vincule-a como sub-issue do GitHub (use gh api com POST /repos/<owner>/<repo>/issues/<número pai>/sub_issues, passando o id da issue filha, não o número). Se a API não estiver disponível, apenas a descrição no corpo é suficiente.
• Ao criar várias issues divididas, crie primeiro as que não têm dependências, para que os números reais possam ser colocados em Depends on.
• Após a criação, informe a URL da issue.