@saulwade/swl-ses 1.0.0

package/habilidades/redis-experto/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: redis-experto
+description: >
+  Redis: caching patterns (cache-aside, write-through), data structures, pub/sub
+  vs streams, rate limiting, distributed locks con Redlock y pipelining. Cargar
+  cuando se implemente caching, rate limiting o comunicación en tiempo real.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para mensajería async entre microservicios con garantías de durabilidad y reintentos — para colas duraderas con dead letter queue usar `kafka-experto` o SQS/Service Bus."
+  - "No cargar para almacenamiento de sesiones distribuidas en aplicaciones Angular/Next.js — para manejo de sesiones en el frontend el estado vive en el cliente; Redis aplica al backend."
+  - "No cargar para caché de assets estáticos o CDN — para caché de archivos estáticos usar CloudFront, Nginx o similar; Redis es para datos de aplicación."
+  - "No cargar para búsqueda de texto completo — Redis tiene módulos de búsqueda (RediSearch) pero para full-text search general cargar `postgresql-experto` con `tsvector` o usar Elasticsearch."
+---
+# Redis Experto — Caching, Estructuras y Tiempo Real
+
+## Cuándo NO cargar
+
+- La tarea es cola de mensajes con garantías de durabilidad fuerte y DLQ: usar Kafka, SQS o Azure Service Bus.
+- La tarea es caché de assets estáticos o CDN: usar CloudFront, Nginx o un CDN dedicado.
+- La tarea es full-text search: cargar `postgresql-experto` (tsvector) o Elasticsearch.
+- La tarea es base de datos primaria de documentos: Redis no reemplaza a MongoDB o PostgreSQL.
+
+Redis es una estructura de datos en memoria con persistencia. Su velocidad lo
+hace ideal para caching, rate limiting, colas ligeras y pub/sub. Este skill
+cubre los patrones de caching, las estructuras de datos correctas para cada
+caso, y las operaciones atómicas con Lua para garantizar consistencia.
+
+## Cuándo cargar este skill
+
+Invoca `Skill("redis-experto")` cuando:
+
+- Se implemente caching con estrategia cache-aside o write-through
+- Se diseñe rate limiting para endpoints o usuarios
+- Se implemente distributed lock para evitar race conditions
+- Se use pub/sub o Streams para mensajeria
+- Se diseñan claves con TTL y namespacing
+- Se configure connection pooling o Redis Cluster
+
+## Conceptos clave
+
+### Tres estrategias de caching
+
+Cache-aside (lazy loading): la aplicación lee cache primero; si no existe, lee
+la BD y llena el cache. Write-through: al escribir en BD, también se escribe
+en cache. Write-behind: se escribe en cache primero, la BD se actualiza
+asincrónamente. Cache-aside es el patrón más común y seguro.
+
+### Atomicidad con Lua scripts
+
+Redis es single-threaded para comandos. Un script Lua se ejecuta atómicamente:
+ningún otro comando puede interferir entre las instrucciones del script. Usar
+para operaciones que requieren "leer y escribir" sin race conditions.
+
+### Pub/Sub vs Streams
+
+Pub/Sub es fire-and-forget: si un consumidor está desconectado, pierde mensajes.
+Streams (XADD/XREAD) persisten mensajes, soportan consumer groups y permiten
+replay. Usar Streams para eventos importantes; Pub/Sub para notificaciones efímeras.
+
+## Reglas obligatorias
+
+### SIEMPRE definir TTL al crear claves — nunca claves permanentes en produccion
+
+```typescript
+// MAL — clave sin TTL que vive para siempre
+await redis.set(`usuario:${id}`, JSON.stringify(usuario));
+
+// BIEN — TTL explicito segun la naturaleza del dato
+await redis.setex(`usuario:${id}`, 3600, JSON.stringify(usuario)); // 1 hora
+// O con la API moderna:
+await redis.set(`usuario:${id}`, JSON.stringify(usuario), { EX: 3600 });
+```
+
+**Por qué**: Claves sin TTL consumen memoria indefinidamente. En producción,
+la memoria de Redis es limitada y cara.
+
+### Namespacing obligatorio en todas las claves
+
+```typescript
+// MAL — colisión entre ambientes y módulos
+await redis.set('usuario:123', data);
+await redis.set('sesion:abc', token);
+
+// BIEN — prefijo de ambiente y modulo
+const PREFIJO = `${process.env.NODE_ENV}:miapp`;
+await redis.set(`${PREFIJO}:usuario:123`, data, { EX: 3600 });
+await redis.set(`${PREFIJO}:sesion:abc`, token, { EX: 86400 });
+```
+
+### NUNCA usar KEYS * en produccion
+
+```bash
+# MAL — bloquea Redis mientras escanea toda la keyspace
+KEYS usuario:*
+
+# BIEN — SCAN con cursor, no bloquea
+SCAN 0 MATCH usuario:* COUNT 100
+```
+
+En código:
+```typescript
+// Usar scan iterativo, nunca keys()
+for await (const key of redis.scanIterator({ MATCH: 'prod:usuario:*', COUNT: 100 })) {
+    // procesar key
+}
+```
+
+### Distributed Lock con TTL de seguridad — NUNCA lock sin expiracion
+
+```typescript
+// MAL — lock sin TTL, si el proceso muere queda bloqueado para siempre
+await redis.set('lock:proceso-critico', '1');
+
+// BIEN — lock con TTL (NX = solo si no existe, EX = TTL en segundos)
+const adquirido = await redis.set(
+    'lock:proceso-critico',
+    tokenUnico,            // valor único para verificar propiedad al liberar
+    { NX: true, EX: 30 }  // TTL de 30s como safety net
+);
+if (!adquirido) throw new Error('No se pudo adquirir el lock');
+```
+
+## Patrones recomendados
+
+### Cache-aside con helper tipado
+
+```typescript
+class CacheService {
+    constructor(private readonly redis: Redis) {}
+
+    async obtenerOCargar<T>(
+        clave: string,
+        ttlSegundos: number,
+        cargador: () => Promise<T>,
+    ): Promise<T> {
+        const cached = await this.redis.get(clave);
+        if (cached) return JSON.parse(cached) as T;
+
+        const valor = await cargador();
+        await this.redis.setex(clave, ttlSegundos, JSON.stringify(valor));
+        return valor;
+    }
+
+    async invalidar(patron: string): Promise<void> {
+        for await (const clave of this.redis.scanIterator({ MATCH: patron })) {
+            await this.redis.del(clave);
+        }
+    }
+}
+
+// Uso
+const producto = await cache.obtenerOCargar(
+    `prod:producto:${id}`,
+    3600,
+    () => db.producto.findUnique({ where: { id } }),
+);
+```
+
+### Rate limiting con Sorted Sets (sliding window)
+
+```typescript
+async function verificarRateLimit(
+    usuarioId: string,
+    limite: number,
+    ventanaMs: number,
+): Promise<{ permitido: boolean; restantes: number }> {
+    const clave = `prod:ratelimit:${usuarioId}`;
+    const ahora = Date.now();
+    const ventanaInicio = ahora - ventanaMs;
+
+    const [, , conteo] = await redis
+        .multi()
+        .zremrangebyscore(clave, 0, ventanaInicio)  // limpiar entradas viejas
+        .zadd(clave, { score: ahora, value: `${ahora}-${Math.random()}` })
+        .zcard(clave)
+        .expire(clave, Math.ceil(ventanaMs / 1000))
+        .exec();
+
+    const permitido = (conteo as number) <= limite;
+    return { permitido, restantes: Math.max(0, limite - (conteo as number)) };
+}
+```
+
+### Lua script para operación atómica
+
+```typescript
+// Decrementar stock solo si hay suficiente — atomico
+const luaDecrementarStock = `
+    local stock = tonumber(redis.call('GET', KEYS[1]))
+    if stock == nil then return -1 end
+    if stock < tonumber(ARGV[1]) then return -2 end
+    return redis.call('DECRBY', KEYS[1], ARGV[1])
+`;
+
+const resultado = await redis.eval(luaDecrementarStock, {
+    keys: [`prod:stock:${productoId}`],
+    arguments: [cantidad.toString()],
+});
+// -1: clave no existe, -2: stock insuficiente, >=0: nuevo valor
+```
+
+### Streams para cola de eventos con consumer groups
+
+```typescript
+// Productor: agregar evento al stream
+await redis.xadd('prod:eventos:pedidos', '*', {
+    pedidoId: pedido.id,
+    tipo:     'CREADO',
+    datos:    JSON.stringify(pedido),
+});
+
+// Consumidor con consumer group (tolerante a fallos)
+await redis.xgroupCreate('prod:eventos:pedidos', 'procesadores', '0', { MKSTREAM: true });
+
+while (true) {
+    const mensajes = await redis.xreadgroup(
+        'procesadores', 'worker-1',
+        [{ key: 'prod:eventos:pedidos', id: '>' }],
+        { COUNT: 10, BLOCK: 2000 }
+    );
+    for (const { id, message } of mensajes?.[0]?.messages ?? []) {
+        await procesarEvento(message);
+        await redis.xack('prod:eventos:pedidos', 'procesadores', id);
+    }
+}
+```
+
+### Pipelining para operaciones masivas
+
+```typescript
+// MAL — round trip por cada operación
+for (const id of ids) {
+    await redis.get(`prod:usuario:${id}`);
+}
+
+// BIEN — pipeline envia todo de una vez
+const pipeline = redis.multi();
+for (const id of ids) {
+    pipeline.get(`prod:usuario:${id}`);
+}
+const resultados = await pipeline.exec();
+```
+
+## Anti-patrones conocidos
+
+### Single Point of Failure — usar Redis Sentinel o Cluster en producción
+
+Un único nodo Redis que falla detiene la aplicación si no hay fallback.
+Configurar Redis Sentinel para alta disponibilidad o Redis Cluster para
+escalabilidad horizontal.
+
+### Cache sin invalidacion al mutar datos
+
+```typescript
+// MAL — actualiza la BD pero no invalida el cache
+await db.producto.update({ where: { id }, data: { precio } });
+// El cache sigue devolviendo el precio viejo
+
+// BIEN — invalidar el cache inmediatamente después de la mutación
+await db.producto.update({ where: { id }, data: { precio } });
+await redis.del(`prod:producto:${id}`);
+```
+
+### Hash grandes con HGETALL completo
+
+```typescript
+// MAL — carga todo el hash aunque solo se necesite un campo
+const datos = await redis.hgetall(`prod:usuario:${id}`);
+const nombre = datos.nombre;
+
+// BIEN — obtener solo el campo necesario
+const nombre = await redis.hget(`prod:usuario:${id}`, 'nombre');
+```
+
+## Checklist de verificación
+
+- [ ] Todas las claves tienen TTL definido explícitamente
+- [ ] Namespacing con prefijo de ambiente en todas las claves
+- [ ] Sin KEYS * — usar SCAN con cursor
+- [ ] Distributed locks con TTL de seguridad y valor único para verificar propiedad
+- [ ] Operaciones "leer-modificar-escribir" con Lua script o transacciones MULTI/EXEC
+- [ ] Pipelining para operaciones masivas
+- [ ] Redis Sentinel o Cluster configurado en producción
+
+## Referencias
+
+- [Redis Commands](https://redis.io/docs/latest/commands/)
+- [Redis Patterns](https://redis.io/docs/latest/develop/use/patterns/)
+- [node-redis](https://github.com/redis/node-redis)
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**`redis.del(key)` en Node.js `node-redis` v4 no lanza error si la clave no existe — devuelve `0` en lugar de fallar, causando que la invalidación de caché silencie errores de lógica**: un servicio que llama `await redis.del("prod:usuario:123")` después de una mutación asume que la clave existía, pero si la clave ya había expirado o nunca se creó (por un bug en write-through), el `0` pasa desapercibido y el código continúa sin invalidar nada en realidad. Causa: `DEL` en Redis devuelve el número de claves eliminadas; la API de node-redis expone ese número, no un error. Fix: cuando la invalidación es crítica, usar `EXISTS` antes del `DEL` o verificar que el retorno sea `> 0`. Para caché convencional cache-aside, el `0` es aceptable (la clave ya expiró), pero documentar explícitamente la decisión.
+
+**El patrón Redlock con 3 nodos falla en escenarios de split-brain cuando los nodos Redis están en diferentes zonas de disponibilidad con latencia asimétrica**: si el cliente adquiere el lock en 2 de 3 nodos (mayoría), pero el tercer nodo reaparece antes de que expire el TTL del lock, otro cliente puede adquirir el lock en ese nodo tardío y los dos primeros, creando dos titulares del lock simultáneamente. Causa: Redlock asume relojes sincronizados y latencia simétrica entre nodos; en producción cloud con múltiples AZs ambas suposiciones son aproximadas. Fix: usar TTLs de lock generosos (10-30s para operaciones rápidas) y diseñar el trabajo protegido por el lock para ser idempotente — si dos workers ejecutan simultáneamente, el sistema debe tolerarlo o detectarlo y revertir.
+
+**`redis.xreadgroup` con `BLOCK: 2000` bloquea la conexión del pool durante 2 segundos y agota el pool si hay más consumidores concurrentes que conexiones disponibles**: con un pool de 10 conexiones y 8 workers de Streams que bloquean durante 2s esperando mensajes, los requests de la API que llegan durante ese tiempo no encuentran conexiones disponibles y fallan. Causa: las operaciones bloqueantes de Redis (BLPOP, BRPOP, XREAD con BLOCK) mantienen una conexión del pool ocupada durante el período de bloqueo. Fix: usar un pool de conexiones separado exclusivamente para los consumers de Streams, independiente del pool de la API. Configurar el pool de Streams con `max: N_workers + buffer`, donde buffer = 20% para tolerancia.
+
+**`KEYS *` en producción con 1M+ claves congela Redis durante varios segundos porque es una operación O(N) que bloquea el event loop de Redis**: un script de diagnóstico que ejecuta `await redis.keys("prod:session:*")` para contar sesiones activas hace que todas las operaciones del servidor queden en cola durante 3-8 segundos. Causa: Redis es single-threaded para comandos; `KEYS` escanea todo el keyspace sin pausas. Fix: usar siempre `SCAN` con cursor: `for await (const key of redis.scanIterator({ MATCH: "prod:session:*", COUNT: 100 }))` — procesa lotes de 100 claves, cediendo el event loop entre lotes.
+
+*Skill creado con swl:crear-skill el 2026-03-31. Versión 1.0.0.*

package/habilidades/release-semver/.evolved.json

@@ -0,0 +1,9 @@
+{
+  "SKILL.md": {
+    "evolved": true,
+    "evolvedFrom": "5.10.4",
+    "evolvedAt": "2026-04-20",
+    "evolvedBy": "aprender",
+    "evolvedNote": "npx @latest en post-install"
+  }
+}

package/habilidades/release-semver/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: release-semver
+description: Versionado semántico (SemVer). Cuándo bumpar major/minor/patch, changelogs convencionales, estrategia de tags y proceso de release completo.
+version: "1.0.1"
+herramientasPermitidas: [Read, Bash]
+exclusiones:
+  - "No cargar para versionar el sistema SWL — el bump de versión de swl-ses sigue el checklist de 15 ubicaciones documentado en `/swl:release`; este skill cubre SemVer general para proyectos de usuario, no el proceso interno de release del sistema."
+  - "No cargar para decidir el tipo de commit individual (feat/fix/refactor) — el mensaje de commit se elige al hacer commit; este skill se carga cuando se necesita decidir el número de versión del release o crear el proceso completo de release."
+  - "No cargar para proyectos internos sin versionado público ni consumidores externos — si no hay consumidores del paquete que dependen de compatibilidad, la disciplina SemVer completa puede ser excesiva; usar `git-workflow.md` para el flujo de commits."
+  - "No cargar si el proceso de release ya está automatizado en CI con `semantic-release` — en ese caso el número de versión se calcula automáticamente desde los commits y cargar este skill solo agrega duplicación."
+evolvable: true  # default para skill estandar
+---
+# Versionado Semántico (SemVer)
+
+## Principio fundamental
+
+Un número de versión tiene la forma `MAJOR.MINOR.PATCH` (ej. `2.4.1`). Cada segmento comunica
+intención de compatibilidad a los consumidores del paquete o servicio.
+
+---
+
+## Cuándo bumpar cada segmento
+
+### PATCH — arreglos compatibles hacia atrás
+
+Incrementa PATCH cuando:
+- Se corrige un bug sin cambiar la interfaz pública.
+- Se corrige documentación o typos en código que afectan comportamiento.
+- Se mejoran mensajes de error sin cambiar el tipo de excepción.
+- Se actualizan dependencias de parche (`requests 2.31.0 → 2.31.1`).
+
+```
+1.4.2 → 1.4.3   # fix: corrige cálculo incorrecto en factura
+```
+
+### MINOR — funcionalidad nueva compatible hacia atrás
+
+Incrementa MINOR cuando:
+- Se agrega un endpoint, método o parámetro opcional nuevo.
+- Se agrega una funcionalidad que los consumidores pueden ignorar.
+- Se depreca algo (pero aún funciona).
+- Se actualiza una dependencia minor que agrega capacidades.
+
+```
+1.4.3 → 1.5.0   # feat: agrega exportación a PDF
+```
+
+Al subir MINOR, el PATCH siempre regresa a 0.
+
+### MAJOR — cambios incompatibles hacia atrás (breaking changes)
+
+Incrementa MAJOR cuando:
+- Se elimina un endpoint, método o campo.
+- Se cambia el tipo o contrato de un parámetro existente.
+- Se cambia el comportamiento esperado de forma que rompe integraciones existentes.
+- Se cambia la autenticación/autorización de forma incompatible.
+
+```
+1.5.0 → 2.0.0   # feat!: migra autenticación de JWT a OAuth2
+```
+
+Al subir MAJOR, MINOR y PATCH regresan a 0.
+
+### Versión 0.x.y — desarrollo inicial
+
+Mientras la versión MAJOR sea `0`, la API se considera inestable. Cualquier MINOR puede
+contener breaking changes. Cuando el software está listo para producción, se lanza `1.0.0`.
+
+---
+
+## Commits Convencionales
+
+Los commits convencionales generan el changelog automáticamente y determinan el bump.
+
+### Formato
+
+```
+<tipo>[scope opcional][! para breaking]: <descripción corta>
+
+[cuerpo opcional]
+
+[footer opcional: BREAKING CHANGE: descripción]
+```
+
+### Tipos y su impacto en versión
+
+| Tipo       | Impacto versión | Descripción                                      |
+|------------|----------------|--------------------------------------------------|
+| `fix`      | PATCH           | Corrección de bug                                |
+| `feat`     | MINOR           | Nueva funcionalidad                              |
+| `feat!`    | MAJOR           | Nueva funcionalidad con breaking change          |
+| `fix!`     | MAJOR           | Fix con breaking change                          |
+| `refactor` | ninguno         | Refactorización sin cambio de comportamiento     |
+| `chore`    | ninguno         | Tareas de mantenimiento (CI, deps, config)       |
+| `docs`     | ninguno         | Documentación únicamente                         |
+| `test`     | ninguno         | Agregar o corregir tests                         |
+| `perf`     | PATCH           | Mejora de rendimiento sin cambio de interfaz     |
+| `ci`       | ninguno         | Cambios en pipelines de CI/CD                    |
+| `style`    | ninguno         | Formato, espacios, punto y coma (sin lógica)     |
+
+### Ejemplos de commits bien escritos
+
+```bash
+git commit -m "fix(auth): corrige expiración incorrecta de tokens de refresco"
+git commit -m "feat(reportes): agrega exportación a Excel con formato condicional"
+git commit -m "feat(api)!: cambia paginación de offset a cursor
+
+BREAKING CHANGE: el parámetro 'page' fue reemplazado por 'cursor'.
+Los clientes deben actualizar sus integraciones."
+```
+
+---
+
+## Proceso de release
+
+### Paso 1 — Preparar la rama de release
+
+```bash
+# En main, crear rama release
+git checkout -b release/2.1.0
+
+# Actualizar versión en archivos del proyecto
+# Python: pyproject.toml, __version__
+# Node: package.json
+# Java: pom.xml o build.gradle
+```
+
+### Paso 2 — Generar CHANGELOG
+
+Usar `conventional-changelog` o `git-cliff` para generar el changelog automáticamente:
+
+```bash
+# Con git-cliff (recomendado)
+git cliff --tag v2.1.0 --output CHANGELOG.md
+
+# Con conventional-changelog
+npx conventional-changelog -p conventionalcommits -i CHANGELOG.md -s
+```
+
+Estructura esperada del CHANGELOG:
+
+```markdown
+## [2.1.0] - 2026-03-25
+
+### Nuevas funcionalidades
+- feat(reportes): agrega exportación a Excel (#234)
+- feat(usuarios): agrega campo de foto de perfil (#241)
+
+### Correcciones
+- fix(auth): corrige expiración incorrecta de tokens (#238)
+- fix(factura): redondeo incorrecto en descuentos (#240)
+```
+
+### Paso 3 — Commit de versión y tag
+
+```bash
+# Commit del bump de versión
+git add pyproject.toml CHANGELOG.md
+git commit -m "chore(release): v2.1.0"
+
+# Crear tag anotado (no ligero)
+git tag -a v2.1.0 -m "Release v2.1.0"
+
+# Subir rama y tag
+git push origin release/2.1.0
+git push origin v2.1.0
+```
+
+### Paso 4 — Merge a main y develop
+
+```bash
+git checkout main
+git merge --no-ff release/2.1.0
+git push origin main
+
+git checkout develop
+git merge --no-ff release/2.1.0
+git push origin develop
+
+git branch -d release/2.1.0
+```
+
+---
+
+## Estrategia de tags
+
+### Tags anotados vs. ligeros
+
+Siempre usar **tags anotados** (`git tag -a`) para releases. Los tags ligeros son solo para
+marcado temporal interno. Los tags anotados incluyen autor, fecha y mensaje — esto es esencial
+para `git describe` y herramientas de release.
+
+### Convención de nombres
+
+```
+v{MAJOR}.{MINOR}.{PATCH}           # release estable:    v2.1.0
+v{MAJOR}.{MINOR}.{PATCH}-rc.{N}    # release candidate:  v2.1.0-rc.1
+v{MAJOR}.{MINOR}.{PATCH}-beta.{N}  # beta pública:       v2.1.0-beta.2
+v{MAJOR}.{MINOR}.{PATCH}-alpha.{N} # alpha interna:      v2.1.0-alpha.1
+```
+
+### Listar y filtrar tags
+
+```bash
+git tag --sort=-v:refname         # Lista tags en orden semver descendente
+git tag -l "v2.*"                 # Solo tags de la serie 2.x
+git describe --tags --abbrev=0    # Último tag del commit actual
+```
+
+---
+
+## Herramientas recomendadas
+
+| Herramienta            | Uso                                          |
+|------------------------|----------------------------------------------|
+| `git-cliff`            | Generación de CHANGELOG desde commits        |
+| `commitizen`           | Wizard interactivo para commits convencionales |
+| `semantic-release`     | Release automatizado desde CI                |
+| `bump2version`         | Bump de versión en archivos Python           |
+| `conventional-commits` | Spec oficial de commits convencionales       |
+
+---
+
+## Anti-patrones a evitar
+
+- **Nunca reutilizar un tag**: Si el release `v2.1.0` se publicó, no se puede mover ese tag.
+  Si hay un error, publicar `v2.1.1`.
+- **Nunca usar tags ligeros en releases**: No aportan metadata y dificultan trazabilidad.
+- **Nunca saltarse MAJOR por miedo**: Si hay breaking change, es MAJOR. Ocultarlo como MINOR
+  rompe la confianza de los consumidores.
+- **No mezclar tipos de commit en uno solo**: Un commit = un cambio lógico = un tipo.
+- **No escribir changelogs manuales sin estructura**: Usar el formato estándar para que las
+  herramientas puedan procesarlos.
+
+## Cuándo NO cargar
+
+- Se versiona el sistema SWL propio — ese proceso usa el checklist de 15 ubicaciones de `/swl:release`; este skill cubre SemVer general para proyectos de aplicación, no el flujo interno del sistema.
+- Se elige el tipo de commit para un cambio individual — el tipo (`feat`, `fix`, `refactor`) se decide al redactar el mensaje del commit; cargar este skill es excesivo para esa decisión puntual.
+- `semantic-release` ya está configurado en CI — si el release está automatizado, el número de versión se calcula desde los commits sin intervención manual; cargar este skill duplicaría el trabajo.
+- El proyecto es una herramienta interna sin consumidores que dependan de compatibilidad de versión — SemVer completo compensa cuando hay consumidores que confían en los números de versión para evaluar breaking changes.
+
+## Gotchas / Errores comunes no obvios
+
+- **Tag ligero creado en lugar de anotado para el release**: `git tag v2.1.0` sin la flag `-a` crea un tag ligero que no incluye metadata de autor, fecha ni mensaje. Causa: olvidar la flag `-a` o la costumbre de usar tags ligeros para marcado temporal. Solución: siempre `git tag -a v2.1.0 -m "Release v2.1.0"` para releases — los tags anotados son los que `git describe` y las herramientas de changelog usan correctamente.
+- **MAJOR evitado por considerar el breaking change "pequeño"**: el equipo sube de `1.4.2` a `1.5.0` un endpoint que cambió su contrato de respuesta. Causa: subestimar el impacto del breaking change para evitar el salto de versión mayor. Solución: si un consumidor tiene que actualizar su código para seguir funcionando, es MAJOR sin importar el tamaño del cambio — el anti-patrón "Nunca saltarse MAJOR por miedo" es explícito en el skill.
+- **Changelog generado con `git cliff` sin configuración personalizada incluye commits de chore y docs**: el CHANGELOG.md resultante tiene 80% de entradas de limpieza que no interesan a los consumidores. Causa: `git cliff` sin `.cliff.toml` incluye todos los tipos de commit. Solución: crear `.cliff.toml` en el repo con la sección `[git]` filtrando solo `feat`, `fix`, `perf` y `BREAKING CHANGE` para el changelog de release público.
+- **Rama `release/2.1.0` mergeada a `main` pero no a `develop`**: el próximo desarrollo parte de `develop` sin incluir los commits del release, generando conflictos en la siguiente rama de feature. Causa: el Paso 4 requiere merge a ambas ramas pero se omite el merge a `develop` por considerar que el release ya está en `main`. Solución: el proceso de release de 4 pasos del skill requiere merge a `main` Y a `develop` antes de eliminar la rama de release — ambos merges son parte del mismo paso atómico.
+- **`npx <paquete> <comando>` sin `@latest` usa caché stale indefinidamente**: tras publicar una nueva versión, `npx swl-ses doctor` sigue ejecutando la primera versión que el usuario cacheó (por ejemplo v5.7.0 cuando ya hay v5.10.3 instalada). Causa: npx resuelve a la primera versión disponible y la cachea; sin `@latest` nunca vuelve a consultar el registry. Solución: SIEMPRE usar `npx paquete@latest <comando>` en mensajes post-install, hooks de alerta de nueva versión, docs del README, ejemplos en CHANGELOG y scripts de inicialización. Nunca `npx paquete <comando>` desnudo — incluso si el paquete acaba de publicarse; el caché de un desarrollador vecino puede tener una versión anterior desde hace meses. Un bump sin `@latest` en los mensajes post-install perpetúa el problema para todos los usuarios nuevos.