Crear Issues en GitHub

Creación estructurada de issues en GitHub a partir de hallazgos de revisión o desgloses de tareas. Convierte una lista de hallazgos (de

review-codebase

,

security-audit-codebase

, o análisis manual) en issues de GitHub bien formados con etiquetas, criterios de aceptación y referencias cruzadas.

Cuándo Usar

• Después de una revisión de código que produce una tabla de hallazgos que necesita seguimiento
• Después de una sesión de planificación que identifica elementos de trabajo que deben convertirse en issues
• Al convertir una lista de TODO o un backlog en issues rastreables de GitHub
• Al crear en lote issues relacionados que requieren formato y etiquetado consistente

Entradas

• Requerido:

  findings

  — una lista de elementos, cada uno con al menos un título y descripción. Idealmente también incluye: gravedad, archivos afectados y etiquetas sugeridas
• Opcional:

  • group_by

    — cómo agrupar los hallazgos en issues:

    severity

    ,

    file

    ,

    theme

    (por defecto:

    theme

    )

  • label_prefix

    — prefijo para etiquetas creadas automáticamente (por defecto: ninguno)

  • create_labels

    — si se crean etiquetas faltantes (por defecto:

    true

    )

  • dry_run

    — previsualizar issues sin crearlos (por defecto:

    false

    )

Procedimiento

Paso 1: Preparar Etiquetas

Asegúrate de que todas las etiquetas necesarias existan en el repositorio.

1. Lista las etiquetas existentes:

   gh label list --limit 100

2. Identifica las etiquetas necesarias por los hallazgos (según gravedad, fase o campos de etiqueta explícitos)
3. Mapea las gravedades a etiquetas si aún no están mapeadas:

   critical

   ,

   high-priority

   ,

   medium-priority

   ,

   low-priority

4. Mapea fases/temas a etiquetas:

   security

   ,

   architecture

   ,

   code-quality

   ,

   accessibility

   ,

   testing

   ,

   performance

5. Si

   create_labels

   es true, crea las etiquetas faltantes:

   gh label create "name" --color "hex" --description "desc"

6. Usa colores consistentes: rojo para crítico/seguridad, naranja para alto, amarillo para medio, azul para arquitectura, verde para pruebas

Esperado: Todas las etiquetas referenciadas por los hallazgos existen en el repositorio. No se crean etiquetas duplicadas.

En caso de fallo: Si el CLI

gh

no está autenticado, indica al usuario que ejecute

gh auth login

. Si la creación de etiquetas es denegada (permisos insuficientes), procede sin crearlas y anota cuáles faltan.

Paso 2: Agrupar Hallazgos

Agrupa los hallazgos relacionados en issues lógicos para evitar la proliferación de issues.

1. Si

   group_by

   es

   theme

   : agrupa los hallazgos por fase o categoría (todos los hallazgos de seguridad → 1-2 issues, todos los de accesibilidad → 1 issue)
2. Si

   group_by

   es

   severity

   : agrupa los hallazgos por nivel de gravedad (todos los CRITICAL → 1 issue, todos los HIGH → 1 issue)
3. Si

   group_by

   es

   file

   : agrupa los hallazgos por archivo afectado principal
4. Dentro de cada grupo, ordena los hallazgos por gravedad (CRITICAL primero)
5. Si un grupo tiene más de 8 hallazgos, divídelo en subgrupos por subtema
6. Cada grupo se convierte en un issue de GitHub

Esperado: Un conjunto de grupos de issues, cada uno conteniendo 1-8 hallazgos relacionados. El número total de issues debe ser manejable (típicamente 5-15 para una revisión completa del código).

En caso de fallo: Si los hallazgos no tienen metadatos de agrupación, recurre a un issue por hallazgo. Esto es aceptable para conjuntos pequeños de hallazgos (< 10) pero produce demasiados issues para conjuntos más grandes.

Paso 3: Redactar Issues

Construye cada issue usando una plantilla estándar.

1. Título:

   [Severity] Theme: Brief description

   — por ejemplo,

   [HIGH] Security: Eliminate innerHTML injection in panel.js

2. Estructura del cuerpo:

   ## Summary
   One-paragraph overview of what this issue addresses and why it matters.
   
   ## Findings
   1. **[SEVERITY]** Finding description (`file.js:line`) — brief explanation
   2. **[SEVERITY]** Finding description (`file.js:line`) — brief explanation
   
   ## Acceptance Criteria
   - [ ] Criterion derived from finding 1
   - [ ] Criterion derived from finding 2
   - [ ] All changes pass existing tests
   
   ## Context
   Generated from codebase review on YYYY-MM-DD.
   Related: #issue_numbers (if applicable)
   

3. Aplica etiquetas: etiqueta de gravedad + etiqueta de tema + etiquetas personalizadas adicionales
4. Si los hallazgos hacen referencia a archivos específicos, mencionarlos en el cuerpo (no como asignados)

Esperado: Cada issue tiene un título claro, hallazgos numerados con insignias de gravedad, criterios de aceptación en casillas de verificación y etiquetas apropiadas.

En caso de fallo: Si el cuerpo supera el límite de tamaño de issue de GitHub (65536 caracteres), divide el issue en partes y haz referencias cruzadas entre ellas.

Paso 4: Crear Issues

Crea los issues usando el CLI

gh

e informa de los resultados.

1. Si

   dry_run

   es true, imprime el título y cuerpo de cada issue sin crearlo y detente
2. Para cada issue redactado, créalo:

   gh issue create --title "title" --body "$(cat <<'EOF'
   body content
   EOF
   )" --label "label1,label2"
   

3. Registra la URL de cada issue creado
4. Después de crear todos los issues, imprime una tabla resumen:

   #número | Título | Etiquetas | Cantidad de hallazgos

5. Si los issues deben estar secuenciados, añade referencias cruzadas: edita el primer issue para mencionar "Blocked by #X" o "See also #Y"

Esperado: Todos los issues creados con éxito. Se imprime una tabla resumen con los números de issue y URLs.

En caso de fallo: Si un issue individual falla al crearse, registra el error y continúa con los issues restantes. Informa de los fallos al final. Fallos comunes: autenticación expirada, etiqueta no encontrada (si

create_labels

era false), tiempo de espera de red agotado.

Validación

• Todos los hallazgos están representados en al menos un issue
• Cada issue tiene al menos una etiqueta
• Cada issue tiene criterios de aceptación con casillas de verificación
• No se crearon issues duplicados (comprueba los títulos contra los issues abiertos existentes)
• El número de issues es razonable para la cantidad de hallazgos (no 1:1 para conjuntos grandes)
• Se imprimió la tabla resumen con todas las URLs de los issues

Errores Comunes

• Proliferación de issues: Crear un issue por hallazgo produce más de 20 issues difíciles de gestionar. Agrupa de forma agresiva — 5-10 issues de una revisión completa es lo ideal
• Criterios de aceptación faltantes: Los issues sin casillas de verificación no pueden verificarse como completos. Cada hallazgo debe corresponder al menos a una casilla
• Caos de etiquetas: Crear demasiadas etiquetas hace inútil el filtrado. Cíñete a gravedad + tema, no etiquetas por hallazgo individual
• Referencias desactualizadas: Al crear issues a partir de una revisión antigua, verifica que los hallazgos aún aplican antes de crear los issues. El código puede haber cambiado
• Olvidar el modo de prueba: Para conjuntos grandes de hallazgos, previsualiza siempre con

  dry_run: true

  primero. Es mucho más fácil editar un plan que cerrar 15 issues incorrectos

Habilidades Relacionadas

• review-codebase

  — produce la tabla de hallazgos que esta habilidad consume

• review-pull-request

  — produce hallazgos con alcance de PR que también pueden convertirse en issues

• manage-backlog

  — organiza los issues en sprints y prioridades tras la creación

• create-pull-request

  — crea PRs que referencian y cierran los issues

• commit-changes

  — hace commit de las correcciones que resuelven los issues