Qué es realmente un sub-issue
Todo rastreador de trabajo termina teniendo ese issue.
Tiene cinco peticiones distintas enterradas en la descripción, tres personas comentando sobre temas no relacionados y nadie sabe qué significa “terminado”.
La solución obvia es dividirlo en sub-issues.
Dividir demasiado pronto genera desorden: un issue padre sin cerrar, sub‑issues sin reclamar y carga administrativa que supera la claridad buscada.
Esta guía recorre la decisión.
Aprenderás las señales que indican que una tarea realmente necesita dividirse.
También aprenderás cuándo un solo issue te sirve mejor.
Finalmente, verás cómo estructurar los sub-issues para que te ayuden a seguir el progreso.
Un sub-issue es un issue normal con una relación registrada hacia un issue padre.
En GitHub, puedes agregar sub-issues a un issue para dividir piezas grandes de trabajo en tareas.
Los sub-issues muestran su relación con el issue padre, lo que te permite seguir tu trabajo en toda la plataforma.
El progreso de los issues padres y de los sub-issues también está disponible en los proyectos, donde puedes crear vistas, filtrar y agrupar por issue padre.
Los sub-issues pueden contener a su vez sub-issues, de modo que puedes construir jerarquías que visualicen una pieza completa de trabajo.
GitHub permite hasta 100 sub‑issues por issue padre y ocho niveles de anidamiento, mostrando que la función está pensada para estructuras serias, no solo listas.
El punto clave: la relación es visible y legible por las herramientas.
Eso es lo que separa a los sub-issues de simplemente escribir “parte 1, parte 2” en una descripción.
Como el vínculo existe, las herramientas pueden consolidar el progreso y tú puedes filtrar por él.
Señales de que un issue debería dividirse
Usa estas comprobaciones antes de crear nada.
Si varias se cumplen, dividir probablemente valdrá la pena.
- Metas de cierre distintas. El issue describe trabajo que podría entregarse o revisarse en momentos diferentes. Si una parte puede quedar lista esta semana y otra depende de algo fuera de tu control, pertenecen a issues separados.
- Responsables distintos. Dos personas no pueden “ser responsables” de un mismo issue de forma limpia. Si el diseño, la construcción y el lanzamiento tienen cada uno un responsable natural distinto, los sub-issues hacen explícita la responsabilidad.
- Los comentarios se dispersan. Cuando la discusión sobre un aspecto entierra las novedades de otro, los colaboradores dejan de leer el hilo. Issues separados dan a cada conversación su propio hogar.
- La descripción necesita una lista de verificación de más de unos pocos elementos. Una lista corta dentro de un issue está bien. Cuando la lista misma tiene dependencias y un orden, esos elementos son tareas, no notas.
- Quieres un progreso visible. Si una parte interesada preguntará “¿qué tan avanzado está esto?”, un issue padre con sub-issues lo responde visualmente, porque el progreso se consolida desde los sub-issues.
Un ejemplo hipotético concreto: estás lanzando un boletín comunitario pequeño.
Un issue titulado “Lanzar el boletín” escondería al menos tres trabajos distintos: redactar la primera edición, configurar la página de registro y anunciarlo.
Redactar depende solo de ti.
La página de registro podría depender de una transferencia de dominio.
El anuncio depende de ambas.
Esas cadenas de dependencia distintas son la señal más fuerte de que los sub-issues ayudarán.
Cuándo un solo issue es la mejor opción
Dividir tiene costos reales, y vale la pena nombrarlos para sopesar el intercambio con honestidad.
- Carga de coordinación. Cada sub-issue necesita un título, un responsable y, eventualmente, un cierre. Para trabajo pequeño, esa administración toma más tiempo que la tarea misma.
- Pérdida de contexto. Un solo issue mantiene toda la discusión en un hilo. Dividirla la dispersa, y quien llegue después debe abrir varios issues para entender el conjunto.
- Estructura prematura. Al inicio de un proyecto a menudo aún no conoces los pasos reales. Dividir el trabajo en sub-issues antes de entenderlo fija una suposición, y gastarás esfuerzo reasignando padres y renombrando después.
Mantén un solo issue cuando el trabajo tiene un responsable único, una meta de cierre y una discusión que sigue siendo legible.
Una regla práctica útil: si puedes describir toda la tarea en dos oraciones y terminarla en una sola sesión, no la dividas.
Si no puedes describirla en dos oraciones, eso mismo es una señal que vale la pena atender.
También existe un camino intermedio.
Empieza con un issue y una lista de verificación.
Cuando un elemento de la lista desarrolla su propia discusión, dependencias o responsable, promuévelo a sub-issue en ese momento.
Dividir con evidencia supera a dividir por instinto.
Cómo dividir bien cuando decides hacerlo
Si las señales apuntan a dividir, la estructura importa más que la herramienta.
Sigue este orden.
- Escribe el issue padre como un resultado. El issue padre debe declarar qué significa “terminado” para todo el esfuerzo, no listar tareas. “Lanzamiento del boletín anunciado a la lista” es un resultado. “Escribir correo, construir página, publicar anuncio” es una lista de tareas disfrazada de resultado.
- Haz que cada sub-issue se pueda cerrar de forma independiente. Un sub-issue debería poder terminarse sin abrir otro primero, salvo donde exista una dependencia genuina. Si dos sub-issues solo pueden cerrarse juntos, probablemente son una sola tarea.
- Mantén el anidamiento poco profundo. GitHub admite hasta ocho niveles de sub-issues anidados, pero la profundidad no es una meta. La mayoría del trabajo queda claro en uno o dos niveles. Las jerarquías profundas suelen significar que el issue padre se describió de forma demasiado vaga.
- Asigna y etiqueta al crear. Cuando creas un sub-issue en GitHub, puedes definir su descripción, tipo de issue, responsables, etiquetas, proyectos e hitos en el mismo diálogo. Hacerlo en el momento de la creación evita la pila de sub-issues sin dueño que nadie quiere reclamar después.
- Agrega issues existentes en lugar de duplicarlos. Si el trabajo ya tiene un issue, puedes agregarlo como sub-issue de un issue padre en lugar de crear una copia, incluidos issues de otros repositorios. Esto conserva el historial y la discusión.
La CLI de GitHub admite las mismas relaciones.
Crea un issue nuevo con un issue padre usando la opción --parent en gh issue create .
Adjunta issues existentes con --add-sub-issue en gh issue edit .
Elimina una relación con --remove-sub-issue o --remove-parent .
La mecánica es fácil; el juicio sobre qué merece un sub-issue es la parte difícil.
Usar la estructura una vez que existe
La recompensa por dividir es la visibilidad, y esa proviene de tus vistas de proyecto, no de los issues por sí solos.
GitHub Projects combina tabla, tablero y hoja de ruta, se enlaza con issues y pull requests, y sincroniza la información al modificarse.
Al mostrar el progreso de issues padres y sub‑issues en proyectos, puedes agrupar por issue padre y observar cómo avanza de “sin iniciar” a completado al cerrar sub‑issues.
Dos hábitos prácticos hacen que esto funcione.
Primero, coloca cada sub-issue en el mismo proyecto que su issue padre, o filtra deliberadamente, para que tu vista no omita sub-issues en silencio.
Segundo, resiste la tentación de crear un sub-issue para algo que no querrías ver en ese tablero.
Si una tarea es demasiado trivial para rastrearla, una línea en la lista de verificación del issue padre es el lugar honesto para ella.
Los campos personalizados pueden llevar el contexto que no pertenece a los títulos.
Los proyectos aceptan hasta 50 campos personalizados, como fecha de entrega, número de complejidad o prioridad de selección única.
Un campo de prioridad en los sub-issues, por ejemplo, te permite ordenar los sub-issues de un issue padre según qué hacer a continuación sin renombrar nada.
Un resumen rápido para decidir
Situación: Un responsable, una meta de cierre, una sesión; Mejor opción: Issue único; Por qué: Dividir agrega administración sin agregar claridad
Situación: Varios responsables o metas de cierre; Mejor opción: Sub-issues; Por qué: Cada sub-issue obtiene un responsable claro y una definición de terminado
Situación: Hilos de discusión que se dispersan entre temas; Mejor opción: Sub-issues; Por qué: Cada conversación obtiene su propio hogar
Situación: Exploración temprana, pasos aún desconocidos; Mejor opción: Issue único con lista de verificación; Por qué: Evita fijar una suposición; promueve los elementos después
Situación: Las partes interesadas necesitan ver el progreso; Mejor opción: Sub-issues en un proyecto; Por qué: El progreso se consolida de los sub-issues hacia el issue padre
Errores comunes que conviene evitar
- Dividir antes de entender el trabajo. Si no puedes nombrar el resultado del issue padre, espera. Una estructura construida sobre un padre vago colapsa en un ciclo constante de reasignaciones.
- Crear sub-issues sin responsable. Un sub-issue sin dueño es un deseo, no una tarea. Asigna al crearlo, aunque el responsable seas tú.
- Anidar por anidar. Dos niveles cubren casi todo el trabajo real. Pregúntate qué comunica un tercer nivel que las etiquetas o los campos no comunican.
- Duplicar issues existentes. Si un issue ya existe, vincúlalo como sub-issue para que su historial quede en un solo lugar.
Tu siguiente acción
Abre el issue que motivó esta pregunta.
Escribe una oración que describa qué significa “terminado” para todo el esfuerzo.
Si esa oración cubre un solo responsable y una sola meta de cierre, deja el issue como está y agrega una lista de verificación.
Si esconde dos o más trabajos distintos con dependencias o responsables diferentes, crea primero la declaración de resultado del issue padre.
Luego agrega sub-issues para cada trabajo, asignando y etiquetando cada uno a medida que avanzas.
Un ejercicio breve como este ahora puede evitar semanas de hilos ambiguos después.
Dividir bien el trabajo es una parte de iniciar proyectos de forma limpia.
Si estás evaluando si tu proyecto necesita un inicio estructurado, esto se combina naturalmente con decidir si necesitas una reunión de arranque de proyecto.
Y si el issue que estás dividiendo forma parte de un lanzamiento con más riesgo, un pre-mortem antes de empezar puede revelar los modos de falla que merecen sus propios sub-issues.
Para coordinar a los involucrados, un plan de comunicación indica quién necesita actualizaciones de progreso.
Referencias de fuente: docs.github.com; docs.github.com.
Da el siguiente paso con Ideoreto.
Usa las ideas de esta guía como punto de partida para tu próximo proyecto.
Regístrate en Ideoreto para comenzar.