finishing-a-development-branch

Descripción general

Qué hace esta skill

La skill finishing-a-development-branch te ayuda a cerrar de forma segura una rama de desarrollo de Git cuando el trabajo ya está implementado y la suite de pruebas pasa. Te guía por un flujo de trabajo claro y repetible para que puedas elegir si hacer un merge local, hacer push y abrir un Pull Request, dejar la rama para más adelante o descartarla por completo.

El principio central de la skill es sencillo:

Verificar pruebas → Determinar rama base → Presentar opciones → Ejecutar la elección → Limpiar

En lugar de usar comandos de Git ad‑hoc o de olvidar comprobaciones importantes, finishing-a-development-branch le da a tu agente una checklist consistente para el final de una rama de feature o bugfix.

Para quién es finishing-a-development-branch

• Desarrolladores que trabajan con ramas en Git y quieren una rutina estructurada de “cierre de rama”
• Equipos que exigen que las pruebas pasen antes de hacer merge o abrir un PR
• Usuarios del conjunto de skills obra/superpowers que quieren que los agentes gestionen flujos de trabajo de Git con más seguridad
• Cualquiera que se pregunte a menudo: “¿Esta rama está lista para hacer merge y cómo debería integrarla?”

Encaja especialmente bien en repositorios que ya tienen pruebas automatizadas y ramas base estándar como main o master.

Problemas que resuelve esta skill

• Olvidar ejecutar las pruebas antes de hacer merge o abrir un Pull Request
• No tener claro desde qué rama se creó una feature branch
• Decisiones inconsistentes sobre si hacer merge local, usar PRs o descartar el trabajo
• Ramas sobrantes que ensucian el repositorio porque el paso de cierre nunca estuvo claro

Al imponer primero una comprobación de pruebas y luego presentar un conjunto pequeño de opciones explícitas, finishing-a-development-branch reduce errores y hace que tu flujo de trabajo con Git sea más predecible.

Cuándo encaja bien esta skill

Usa finishing-a-development-branch cuando:

• Una feature o corrección está totalmente implementada
• Esperas que todas las pruebas pasen o quieres bloquear la integración si fallan
• Ya estás listo para decidir cómo debe integrarse la rama o si debería descartarse

No es una buena opción cuando:

• Todavía estás programando activamente o experimentando en la rama
• El repositorio no tiene pruebas utilizables y no puedes ejecutar una suite de pruebas significativa
• Necesitas una gestión de releases multi‑rama compleja más allá de un flujo directo feature → rama base

Si sobre todo necesitas ayuda para escribir código o revisar cambios, plantéate combinar esta skill con otras centradas en implementación o code review; finishing-a-development-branch se ocupa específicamente del paso final de integración.

Cómo usarla

Instalación y configuración

1. Instalar la skill

Instala finishing-a-development-branch desde el repositorio obra/superpowers usando Skills CLI:

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

Esto pone la skill a disposición en el entorno de tu agente para que pueda aplicar el flujo de trabajo guiado de Git a tu repositorio actual.

2. Confirmar los requisitos del repositorio

Para que la skill se comporte como está previsto, tu proyecto debería:

• Ser un repositorio Git con una rama base clara (normalmente main o master).
• Tener una suite de pruebas que se pueda ejecutar, normalmente mediante comandos como:
  • npm test
  • cargo test
  • pytest
  • go test ./...

El comando exacto depende de tu stack; la skill espera que exista algún comando de pruebas y que se pueda ejecutar antes de la integración.

3. Anunciar el uso de la skill

Cuando empieces el proceso de cierre, la skill espera que tú (o tu agente) lo anunciéis explícitamente:

"I'm using the finishing-a-development-branch skill to complete this work."

Esto mantiene el flujo de trabajo transparente para tus colaboradores y deja claro que se está usando el proceso estructurado.

Pasos del flujo de trabajo guiado

Paso 1: Verificar las pruebas

Antes de tomar cualquier decisión de integración, la skill ejecuta o te pide que ejecutes la suite de pruebas del proyecto. Algunos comandos típicos son:

npm test
# or
cargo test
# or
pytest
# or
go test ./...

• Si las pruebas fallan: la skill informa del número de fallos, muestra los errores y detiene el proceso. Indica que no puede continuar con el merge o el PR hasta que las pruebas pasen.
• Si las pruebas pasan: el flujo de trabajo continúa al siguiente paso.

Este estricto filtro de “pruebas primero” ayuda a evitar que se haga merge o se envíe un Pull Request con código roto.

Paso 2: Determinar la rama base

A continuación, finishing-a-development-branch identifica desde qué rama se creó tu rama de desarrollo, usando comandos de Git como:

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Si no puede determinar la rama base automáticamente, la skill recurre a hacer una pregunta aclaratoria como:

"This branch split from main - is that correct?"

Confirmar la rama base correcta es importante porque determina dónde se hará el merge de tu trabajo o a qué rama debe apuntar el Pull Request.

Paso 3: Presentar las opciones de integración

Una vez que las pruebas pasan y se conoce la rama base, la skill presenta exactamente cuatro opciones concisas:

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

Las opciones son deliberadamente cortas y directas, evitando explicaciones extra para que puedas elegir rápidamente.

Casos de uso típicos:

• Opción 1 – Quieres un merge local rápido, normalmente en proyectos personales pequeños o cuando eres la única persona que mantiene el repositorio.
• Opción 2 – Trabajas en equipo y necesitas code review, CI o aprobaciones a través de una plataforma de Git como GitHub.
• Opción 3 – Aún no quieres decidir, pero quieres confirmar que las pruebas pasan y que el estado de la rama es conocido.
• Opción 4 – Estabas experimentando, o el enfoque ha quedado obsoleto, y quieres eliminar la rama de forma limpia.

Paso 4: Ejecutar la opción elegida

Según tu respuesta, la skill ejecuta las acciones de Git correspondientes y cualquier limpieza relacionada. Aunque el SKILL.md subyacente recorta parte de los comandos detallados, la intención es:

• Para merge local: cambiar a la rama base, hacer merge de la rama de desarrollo y, opcionalmente, borrar la rama finalizada si procede.
• Para push + PR: hacer push de la rama al remoto y guiarte para crear un Pull Request dirigido a la rama base identificada.
• Para mantenerla tal cual: dejar la rama actual intacta y dejar claro que tú te encargarás de la integración más adelante.
• Para descartar: descartar o borrar la rama de forma segura tras confirmar que eso es realmente lo que quieres.

Durante este paso, la skill se centra en la previsibilidad y la seguridad: no hacer merge con pruebas fallando, no hacer merge a una rama base incorrecta y evitar pérdidas accidentales de trabajo.

Consejos prácticos de uso

Integrarla en tu flujo de trabajo personal

• Ejecuta finishing-a-development-branch siempre que consideres que una feature está “terminada”.
• Deja que el filtro de pruebas sea tu comprobación final de calidad antes de decidir entre merge y PR.
• Usa la Opción 2 por defecto en entornos de equipo para asegurar que se activen las revisiones y los pipelines de CI.

Usarla acorde a las convenciones de tu equipo

Si tu equipo tiene políticas específicas de ramas y revisión (por ejemplo, hacer PR siempre primero a develop o no borrar ramas automáticamente nunca), ajusta tu uso de las opciones a esas reglas. La estructura de la skill facilita seguir esas políticas de manera consistente.

Combinarla con otras skills de superpowers

Dentro de la suite obra/superpowers, finishing-a-development-branch está diseñada para complementar skills que ayudan con implementación, refactorización o pruebas. Usa esas para evolucionar la rama y recurre a esta skill cuando realmente estés listo para integrarla.

FAQ

¿Cuándo debería ejecutar la skill finishing-a-development-branch?

Ejecuta finishing-a-development-branch cuando tus cambios estén implementados, esperes que las pruebas pasen y estés listo para decidir cómo integrar la rama (merge, PR, mantener o descartar). Está pensada como el paso final en el ciclo de vida de la rama, no como ayuda para el desarrollo del día a día.

¿Qué pasa si las pruebas fallan?

Si las pruebas fallan, la skill informa de los fallos y detiene el proceso. No continuará con el merge ni con la creación del Pull Request. Se espera que corrijas las pruebas que fallan en la rama, las ejecutes de nuevo y solo entonces invoques finishing-a-development-branch otra vez.

¿Puedo usarla sin una suite de pruebas automatizadas?

La skill está diseñada en torno al principio de “verificar primero las pruebas”. Aunque en teoría podrías adaptarla a un proyecto sin pruebas, estarías eludiendo una de sus salvaguardas principales. Para obtener los mejores resultados, úsala en repositorios donde puedas ejecutar comandos como npm test, cargo test, pytest o go test ./....

¿Cómo decide a qué rama hacer merge?

finishing-a-development-branch intenta determinar la rama base usando merge-base de Git frente a nombres de rama habituales como main o master. Si eso es ambiguo, te pedirá que confirmes cuál debe ser la rama base. Así se asegura de que los merges y Pull Requests apunten a la rama correcta.

¿Crea un Pull Request automáticamente?

El comportamiento documentado de la skill es “push and create a Pull Request” cuando eliges la Opción 2. La mecánica exacta depende de cómo esté configurado el entorno de tu agente con tu plataforma de alojamiento Git. Como mínimo, hará push de tu rama y te guiará para abrir un PR contra la rama base detectada.

¿Borrará mi rama automáticamente?

La descripción de la SKILL se centra en presentar opciones y ejecutar el flujo elegido, incluida la limpieza. El comportamiento exacto de borrado puede depender de cómo tu entorno interprete el paso de cleanup. Trata la Opción 4 (discard this work) como potencialmente destructiva y elígela solo cuando estés seguro de que ya no necesitas la rama.

¿Es finishing-a-development-branch adecuada para flujos de release complejos?

Esta skill está orientada a ramas de feature o fix sencillas que hacen merge a una única rama base. Si gestionas varias ramas de release de larga duración, flujos de hotfix o pipelines de despliegue más complejos, aún puedes usar finishing-a-development-branch por rama, pero probablemente necesites procesos o herramientas adicionales para cubrir la estrategia de release más amplia.

¿Cómo instalo finishing-a-development-branch otra vez?

Usa Skills CLI apuntando al repositorio obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

Después de la instalación, sigue el flujo de trabajo de la skill: ejecuta las pruebas, confirma la rama base, elige una opción y deja que la skill se encargue de los pasos de integración y limpieza.