---
name: changelog-generator
description: >
  Generador automático de entradas CHANGELOG.md en formato Keep a Changelog
  desde commits Conventional Commits. Parser determinista que clasifica feat/
  fix/perf/refactor/docs/etc. en categorías user-facing en español, detecta
  breaking changes (marca '!' o trailer 'BREAKING CHANGE:') y reporta nivel
  de conformidad para decidir fallback manual. Cargar en /swl:release Paso 7
  cuando hay commits Conventional, o manualmente para previsualizar el
  changelog antes de un release.
version: 1.1.0
evolved: true
evolved-from: "1.0.0"
evolved-at: "2026-06-11"
evolved-by: "fase-10-slice-5"
evolved-note: "v1.1.0: el parser CC tolera el prefijo de trazabilidad [T-NN]/[REQ-NN] de la convención de ejecutar-fase — commits con prefijo de tarea cuentan como conformes (Fase 10)."
nivelRiesgo: BAJO
herramientasPermitidas: [Read, Bash]
skillsInvocables: [release-semver]
exclusiones:
  - "No invocar para generar release notes con marketing copy o anuncios para usuarios finales — este skill produce listado técnico-legible, no narrativa."
  - "No invocar si el repo no usa Conventional Commits — el parser detecta <80% conformidad y el caller debe abortar a flujo manual de release-semver."
  - "No invocar para reescribir CHANGELOG histórico — solo agrega entrada de la próxima versión al inicio."
---

# /habilidades/changelog-generator — CHANGELOG automático desde Conventional Commits

## Cuándo cargar

- Durante `/swl:release` Paso 7 (Generar CHANGELOG), cuando el flujo automático
  está disponible y los commits del rango siguen Conventional Commits.
- Para previsualizar el changelog candidato antes de bumpear versión:
  `node habilidades/changelog-generator/scripts/parse-commits.js --version X`
- Cuando un colaborador pide un resumen legible de cambios entre dos refs
  arbitrarias del repo.

## Cuándo NO cargar

- Repo sin Conventional Commits (<80% de conformidad): el parser detecta y
  reporta; el caller debe usar `Skill("release-semver")` flujo manual.
- Generación de **release notes** (texto narrativo con contexto de producto):
  este skill produce CHANGELOG técnico-legible; las release notes con marketing
  son tarea aparte (`documentador-swl` con plantilla específica).
- Reescritura histórica del CHANGELOG (squash de varias versiones, corrección
  de entradas antiguas): solo se agrega entrada de la versión nueva al inicio.

## Qué hace el skill

1. **Lee commits** desde la última tag (o entre dos refs arbitrarias) con
   `git log --format=...` usando un separador único para parsear subject + body
   sin colisiones.
2. **Parsea con Conventional Commits 1.0.0**: regex que captura tipo, scope,
   marca `!`, descripción. Soporta tipos extendidos del proyecto SWL:
   `evolucion` (cambios de skills/agentes), además de `feat/fix/perf/refactor/
   docs/style/test/ci/build/chore/revert`. Tolera el prefijo opcional de
   trazabilidad `[T-NN]` / `[REQ-NN]` de la convención de `ejecutar-fase`
   (no altera la semántica CC — el tipo+scope+descripción siguen presentes).
3. **Detecta breaking changes** por marca `!` después del tipo o trailer
   `BREAKING CHANGE:` en el body. Los breaking siempre van al inicio del
   release, sin importar el tipo original.
4. **Transforma descripción técnica → legible**:
   - Elimina referencias a issues al final (`(#123)`, `Refs #456`).
   - Capitaliza primera letra.
   - Elimina punto final (Keep a Changelog usa bullets sin punto).
5. **Agrupa en categorías** con orden canónico:
   1. Breaking changes
   2. Nuevas funcionalidades (feat)
   3. Correcciones (fix)
   4. Mejoras de rendimiento (perf)
   5. Cambios internos (refactor)
   6. Reversiones (revert)
   7. Evoluciones de skills/agentes (evolucion — SWL-specific)
   8. Mantenimiento (docs/style/test/ci/build/chore — colapsadas)
   9. Otros (commits sin prefijo CC válido)
6. **Reporta conformidad**: ratio commits conformes / total. Si <80%, el
   caller debe decidir si abortar o seguir manualmente.

## Helper programático

```js
const {
  parsearCommits,
  leerCommitsGit,
  generarChangelog,
} = require('./habilidades/changelog-generator/scripts/parse-commits');

// 1. Leer commits desde la última tag hasta HEAD
const commits = leerCommitsGit({ to: 'HEAD' });

// 2. Parsear y clasificar
const { categorias, conformidad, totalCommits, conformes } = parsearCommits(commits);

// 3. Si conformidad < 0.8, abortar o avisar al usuario
if (conformidad < 0.8) {
  console.warn(`Conformidad CC: ${conformes}/${totalCommits}. Revisar "Otros".`);
}

// 4. Generar markdown listo para insertar en CHANGELOG.md
const md = generarChangelog(categorias, {
  version: '1.6.5',
  fecha: '2026-05-22',  // opcional, default = hoy
  incluirHash: true,    // muestra hash corto al inicio de cada bullet
});
```

## Uso CLI

Previsualizar changelog candidato sin escribir nada:

```bash
node habilidades/changelog-generator/scripts/parse-commits.js \
  --version 1.6.5 \
  --format markdown
```

Filtrar por rango específico:

```bash
node habilidades/changelog-generator/scripts/parse-commits.js \
  --from v1.6.4 \
  --to HEAD \
  --version 1.6.5
```

Salida JSON estructurado para post-procesamiento:

```bash
node habilidades/changelog-generator/scripts/parse-commits.js \
  --from v1.6.4 \
  --format json > /tmp/changelog-candidato.json
```

## Reglas de uso desde /swl:release

1. Llamar a `leerCommitsGit` con la última tag detectada en el Paso 1 del
   release.
2. Verificar `conformidad >= 0.8`. Si menor, presentar al usuario los commits
   bajo "Otros" y pedir decisión: (a) continuar con el changelog, (b) abortar
   y reescribir commits, (c) editar manualmente la categoría "Otros".
3. Si `--dry-run` está activo en `/swl:release`, mostrar el output de
   `generarChangelog` sin escribir a disco.
4. Si conformidad OK: leer CHANGELOG.md actual, insertar el bloque generado
   al inicio después del header `# Changelog`, escribir atómicamente.
5. NO hacer commit aquí — eso lo hace el Paso 8 de `/swl:release`.

## Gotchas observables

- **Conventional Commits sin scope son válidos**: `fix: corregir X` parsea
  igual que `fix(modulo): corregir X`. El parser no exige scope.
- **El subject debe ir en una sola línea**: si un commit usa newline en el
  subject, el parser lo trata como completo pero `git log %s` ya lo trunca.
- **Tipos no estándar van a "Otros"**: si un equipo usa `mejora:`, `cambio:`,
  el parser los marca como no conformes. El usuario debe ajustar la lista
  `CATEGORIAS` en `parse-commits.js` o adoptar tipos estándar.
- **El skill NO escribe a disco directamente**: solo retorna markdown. El
  caller (`/swl:release` Paso 7) es responsable de leer el CHANGELOG actual,
  insertar al inicio y escribir atómicamente.
- **Commits revert vienen del propio git**: `git revert` genera mensajes
  `Revert "Subject original"` que el parser categoriza correctamente bajo
  Reversiones (regex matchea `revert:` sin que el usuario lo escriba si usa
  `git revert -e` para editar el mensaje al formato CC).
- **El hash corto se trunca a 7 chars**: alineado con el formato `git log
  --oneline` estándar.

## Origen

Adaptado del skill `changelog-generator` de
`temp/awesome-codex-skills-master/changelog-generator/` (ComposioHQ, MIT) con:

- Frontmatter al estándar SWL (es-MX, `nivelRiesgo: BAJO`, `exclusiones`).
- Parser determinista en Node.js (`parse-commits.js`) — el origen es solo
  documentación; este skill agrega la implementación ejecutable.
- Tipo `evolucion:` específico de SWL agregado al parser.
- Soporte para breaking changes `!` y trailer `BREAKING CHANGE:` (origen
  solo menciona el segundo).
- Reporte de conformidad <80% como gate explícita para fallback manual.
- Integración con `/swl:release` Paso 7 documentada en `comandos/swl/release.md`.

Documentado en ADR-0029 (integración parcial awesome-codex-skills, Opción B).
