chore: refine release skills docs

Made-with: Cursor

Author: danielaEsc

.github/copilot-instructions.md

@@ -1,19 +1,44 @@
 # Instrucciones para Gestión de Releases (Carpeta `release/`)
 
-Cuando se detecte una rama `release/v{VERSION}` creada automáticamente por `release-please` (al detectar commits en `master`), Copilot debe intervenir para finalizar el release:
+Estas instrucciones guían a Copilot sobre cómo intervenir en el flujo de releases cuando se usa `release-please` y la skill de la carpeta `release/`.
 
-1. **Detección de Contexto:**
-   - Confirmar que se encuentra en una rama `release/v{VERSION}`.
-   - Usar el archivo `release/.releaserc.yml` para configuraciones específicas.
-   - Referencia de versión: `package.json` (campo `version`).
+## 1. Detección de contexto
 
-2. **Generación de Changelog en Español:**
-   - Analizar los commits del PR/rama actual.
-   - Generar/Actualizar `release/CHANGELOG.md` con secciones en español (ej. "Características", "Correcciones").
-   - El formato debe seguir lo definido en `.releaserc.yml`.
+- Identificar si el usuario está en:
+  - La rama principal (`master`/`main`) → **Modo A: crear release nuevo**.
+  - Una rama de release creada por `release-please` (por ejemplo `release-please--branches--master--components--simple-test-project` u otra similar) → **Modo B: completar release existente**.
+- Usar el archivo `release/.releaserc.yml` para configuraciones específicas.
+- Referencia de versión: `package.json` (campo `version`) y/o manifestos de `release-please`.
 
-3. **Cierre de Release:**
-   - Actualizar la versión en `package.json`.
+## 2. Modo A – Crear un release nuevo (desde `master`/`main`)
+
+Cuando el usuario pida algo como **"Crea un release nuevo desde master usando release-please"** y esté en `master`/`main`:
+
+1. Verificar que se trata de la rama principal.
+2. Validar que los commits recientes siguen Conventional Commits.
+3. Ayudar a disparar el workflow de `release-please` (no crear ramas/PRs manualmente si no es necesario).
+4. Una vez que `release-please` genere el PR de release:
+   - Sugerir al usuario cambiarse a la rama de release y continuar en **Modo B**.
+
+## 3. Modo B – Completar un PR de release-please ya creado (recomendado)
+
+Cuando el usuario esté en una rama de release creada por `release-please` y pida algo como  
+**"Completa este release en esta rama de release-please: genera o actualiza el CHANGELOG en español, actualiza la versión en package.json y deja todo listo para commit en esta misma rama, sin crear un nuevo PR ni tocar master."**:
+
+1. **Detección de contexto:**
+   - Confirmar que se está en una rama de release (nombre generado por `release-please`).
+   - No cambiar de rama a `master`/`main` ni crear nuevas ramas de release.
+
+2. **Generación de changelog en español:**
+   - Analizar los commits del PR/rama actual (desde el último tag).
+   - Generar o actualizar `release/CHANGELOG.md` con secciones en español (ej. "Características", "Correcciones", "Documentación").
+   - Seguir el formato definido en `.releaserc.yml`.
+
+3. **Cierre de release en la rama actual:**
+   - Actualizar la versión en `package.json` (campo `version`) según la versión del release actual.
    - Realizar un commit con el mensaje: `chore: release v{version} [spanish changelog]`.
    - Ejecutar el **Release & Communication Agent** para generar la síntesis para stakeholders (evidencia, riesgos, etc.).
-   - Dejar el PR listo para revisión y merge manual a `master`. (El tag final lo creará `release-please` al mergear).
+   - Dejar el PR listo para revisión y merge manual a `master`.  
+   - No crear un nuevo PR ni una nueva versión de release.
+
+> Nota: si ya existe un PR de release abierto, Copilot **no debe** intentar generar otro PR de release ni forzar un nuevo cálculo de versión; solo debe completar el contenido del PR actual.

release/skill.md

@@ -5,12 +5,12 @@ Este documento describe la "skill" que reside en la carpeta `release/` y que per
 ### ¿Qué hace?
 
 - Detecta configuración del proyecto mediante `.releaserc.yml`.
-- Se activa cuando `release-please` crea una rama `release/v{VERSION}`.
+- Se activa cuando `release-please` crea una rama de release (por ejemplo `release-please--branches--master--components--simple-test-project` u otro nombre generado por la acción).
 - Inspecciona commits desde el último tag siguiendo conventional commits.
 - Genera o actualiza el `CHANGELOG.md` en español con secciones estándares.
 - Actualiza la versión en `package.json`.
 - Invoca al Release & Communication Agent para producir notas de versión y gestionar comunicación para stakeholders.
-- Deja el PR listo para revisión y merge manual a `master`.
+- Deja el PR listo para revisión y merge manual a `master`, sin crear PRs adicionales.
 
 ### Estructura de la carpeta
 
@@ -21,9 +21,28 @@ Este documento describe la "skill" que reside en la carpeta `release/` y que per
 
 ### Uso
 
-El usuario simplemente formula una petición a Copilot del tipo:
+La skill tiene dos modos de uso, según la rama en la que estés:
 
-> "Crea un release" o "Genera un release automático".
+1. **Modo A – Crear un release nuevo (desde `master`/`main`)**
+
+   Úsalo solo cuando estés en la rama principal (`master` o `main`) y quieras que `release-please` calcule una nueva versión y genere un PR de release:
+
+   > "Crea un release nuevo desde master usando la configuración de release-please."
+
+   En este modo, el agente valida convenciones y ayuda a disparar el workflow de `release-please`, que creará la rama y el PR de release correspondientes.
+
+2. **Modo B – Completar un PR de release-please ya creado (recomendado)**
+
+   Úsalo cuando ya exista un PR de release generado por `release-please` y estés situado en la **rama de ese PR** (por ejemplo `release-please--branches--master--components--simple-test-project`):
+
+   > "Completa este release en esta rama de release-please: genera o actualiza el CHANGELOG en español, actualiza la versión en package.json y deja todo listo para commit en esta misma rama, sin crear un nuevo PR ni tocar master."
+
+   En este modo, el agente:
+   - Trabaja únicamente sobre la rama de release ya creada por `release-please`.
+   - No recalcula la versión ni crea un nuevo PR.
+   - Genera/actualiza `CHANGELOG.md`, actualiza `package.json` y ejecuta el Release & Communication Agent para dejar el PR listo para revisión.
+
+> Importante: para evitar crear otra versión y otro PR cuando ya existe uno abierto, no uses el prompt genérico "Crea un release" estando en la rama de release. En ese caso, usa siempre el modo B ("Completa este release en esta rama…").
 
 Copilot toma el control mediante los agentes definidos y ejecuta el flujo anterior, respetando la configuración en `release/.releaserc.yml`.
 
@@ -33,7 +52,7 @@ Copilot toma el control mediante los agentes definidos y ejecuta el flujo anteri
 
 Para cada release se sigue este flujo:
 
-1. **Creación Automática:** `release-please` detecta commits en `master` y crea la rama `release/v{VERSION}` (ej: `release/v1.2.0`) y su respectivo PR.
+1. **Creación Automática:** `release-please` detecta commits en `master` y crea una rama de release y su respectivo PR (el nombre puede ser `release/v{VERSION}` o el formato por defecto de release-please, como `release-please--branches--master--components--simple-test-project`).
 2. **Intervención de Copilot:** Una vez en la rama, Copilot:
    - Actualiza `package.json` (campo `version`).
    - Genera `release/CHANGELOG.md` en español.
@@ -42,15 +61,16 @@ Para cada release se sigue este flujo:
 4. **Revisión:** El desarrollador revisa el PR que ya contiene el changelog y la síntesis.
 5. **Merge a master:** Al mergear el PR, `release-please` crea el tag de Git automáticamente.
 
-**Ejemplo de comando Copilot:**
+**Ejemplos de comandos para Copilot:**
 
 ```
-"Crea un release"
+"Crea un release nuevo desde master usando release-please."
+"Completa este release en esta rama de release-please (changelog en español y versión actualizada), sin crear un nuevo PR."
 ```
 
 El sistema automáticamente:
 
-- ✅ Detecta rama `release/v1.2.0` creada por release-please
+- ✅ Detecta la rama de release creada por release-please
 - ✅ Traduce y genera changelog a español
 - ✅ Actualiza versión en package.json
 - ✅ Prepara síntesis de comunicación