yasukei/agent-skills

Creación de issues de GitHub

Habilidad para escribir issues con el formato definido por el usuario. El objetivo es crear issues que "se puedan leer y poner en marcha / determinar su finalización directamente". Especialmente los criterios de aceptación se usarán directamente como condiciones de finalización al implementar/revisar con issue-to-pr, por lo que deben redactarse de forma verificable.

1. Verificar primero las plantillas del repositorio

Si el repositorio tiene plantillas, estas tienen prioridad sobre la plantilla de esta habilidad. Lugares donde buscar:

• Archivos *.md y *.yml / *.yaml en .github/ISSUE_TEMPLATE/ (config.yml es un archivo de configuración, no una plantilla)
• .github/ISSUE_TEMPLATE.md, ISSUE_TEMPLATE.md en la raíz, docs/ISSUE_TEMPLATE.md
• Si no hay nada de lo anterior, buscar en el repositorio común de la organización <owner>/.github en las mismas ubicaciones

Si hay un clon local, leer los archivos directamente. Si no, obtenerlos con gh api repos/<owner>/<repo>/contents/.github/ISSUE_TEMPLATE o similar.

Cuando se encuentre una plantilla:

• Elegir la que coincida con el tipo de issue (tarea / bug) según el nombre de archivo, name, about y labels.
• Usar la estructura de encabezados de la plantilla, sin mezclar los encabezados de esta habilidad. Solo añadir brevemente información importante al final si no hay lugar para dependencias u otros datos.
• En el caso de formularios YAML, GitHub guarda el contenido enviado como cuerpo con los attributes.label como encabezados ### <label>. Armar el cuerpo de la misma forma y completar los campos con required: true.
• Reflejar el title (prefijo), labels y assignees del frontmatter / definición del formulario.

Si no hay plantilla para el tipo de issue (ejemplo: hay plantilla de bug pero no de tarea), usar para ese tipo la plantilla de esta habilidad.

2. Determinar el tipo

• Tarea: Nueva funcionalidad, mejora, refactorización, documentación, CI, investigación, etc. ("algo que hacer"). → Plantilla de tarea
• Bug: Corrección de algo que no funciona como se espera. → Plantilla de bug

Si hay duda, decidir según "¿El comportamiento actual contradice la especificación?". Si es así, es bug.

3. Plantilla de tarea

## Goal

<Qué lograr en 1-2 frases. Incluir una breve razón de por qué es necesario>

## Scope

- <Qué hacer. Si hay varios bloques, agruparlos con **subencabezados en negrita**>

## Out of scope

- <Qué no hacer. Indicar áreas vecinas que podrían malinterpretarse>

## Acceptance criteria

- <Condiciones verificables para dar por terminado. Pruebas, CI, resultados de comandos, etc.>

## Depends on

- #<número>

Part of #<número de issue padre>.

Puntos clave:

• Goal: Incluir tanto "qué" como "por qué" para que quien lo lea después pueda entender la prioridad y la justificación.
• Scope: Con el nivel de detalle suficiente para que quien lo implemente no tenga dudas: nombres de tipos, comandos, archivos, etc. Si hay elementos pendientes de revisiones anteriores, separarlos con un subencabezado que lo indique.
• Out of scope: Indicar explícitamente "esto no se incluye" para evitar la expansión del alcance. Si no hay nada, escribir - None y mantener la sección (para que quede claro que no se olvidó, sino que no aplica).
• Acceptance criteria: Redactar de forma que un tercero pueda verificar: no "se ha implementado X" sino "existe una prueba para X y pasa" o "se ejecuta Y en CI y tiene éxito".
• Depends on: Listar issues que deben estar completados primero, con - #número (GitHub muestra el título automáticamente). Si no hay, escribir - None.
• Si es una tarea dividida de un issue padre, añadir Part of #<número>. al final.
• Añadir ## Notes solo si hay materiales de referencia, enlaces o decisiones pendientes. No crearlo innecesariamente.

4. Plantilla de bug

## Summary

<Qué está ocurriendo en 1-2 frases>

## Steps to reproduce

1. <paso>
2. <paso>

## Expected behavior

<Cómo debería comportarse>

## Actual behavior

<Cómo se comporta realmente. Pegar mensajes de error o logs en bloques de código>

## Environment

- Version / commit: <versión o hash de commit>
- <SO / navegador / Node / etc. según corresponda>

## Acceptance criteria

- Con los pasos anteriores, el comportamiento debe coincidir con el esperado
- Se añade una prueba de regresión que reproduzca el bug y pase

## Notes

<Suposiciones sobre la causa, issues/PR relacionados, soluciones alternativas. Omitir esta sección si no hay nada>

Puntos clave:

• Escribir solo lo que se ha obtenido del usuario o verificado personalmente. Si algún campo se desconoce, poner Unknown o preguntar al usuario. No inventar pasos de reproducción, ya que desviarán la investigación.
• Las posibles causas deben separarse de los hechos (Actual behavior) y colocarse en Notes. Mezclar síntomas e hipótesis dificulta la lectura si la hipótesis resulta incorrecta.
• Si ya se ha decidido un enfoque de corrección, incluirlo también en Notes.

5. Título, etiquetas y metadatos

• El título debe tener el formato <área>: <descripción> (ejemplo: core: data types, tree IR, and UI–runtime protocol). El área debe coincidir con las existentes en el repositorio (etiquetas area:*, etc.). Para bugs, describir el síntoma, no la corrección (ejemplo: runtime: TON timer does not fire after coldReset).
• Las etiquetas se eligen de las existentes con gh label list. Además de las de área, si es un bug añadir bug si existe. No crear etiquetas que no existan.
• Establecer el hito y el issue padre si se conocen.
• El idioma del título y el cuerpo debe coincidir con el de los issues y PRs existentes en el repositorio (verificar con gh issue list --state all --limit 10 y gh pr list --state all --limit 10). Si no hay issues ni PRs previos, escribir en japonés.
• Los nombres de las secciones (Goal, Scope, Summary, Steps to reproduce, etc.) se mantienen en inglés incluso si el cuerpo está en japonés. Sin embargo, si se usa una plantilla del repositorio, usar los encabezados de esa plantilla.

6. Creación

Escribir el cuerpo en un archivo temporal y pasarlo con --body-file (para evitar que las comillas del shell rompan el contenido).

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

• Si el usuario dice explícitamente "crea", crearlo directamente. Si solo pide un borrador o si gran parte del contenido se ha inferido, mostrar el cuerpo y pedir confirmación antes de crearlo.
• Si hay un issue padre, además de escribir Part of #N. en el cuerpo, vincularlo como sub-issue de GitHub (con gh api usando POST /repos/<owner>/<repo>/issues/<número_padre>/sub_issues, pasando el id del issue hijo, no su número). Si la API no está disponible, basta con la referencia en el cuerpo.
• Si se crean varios issues divididos, crearlos en orden de dependencia para que los números reales se puedan poner en Depends on.
• Después de crear, informar la URL del issue.