@saulwade/swl-ses 1.6.7 → 1.6.8

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — @saulwade/swl-ses v1.6.7
+# CLAUDE.md — @saulwade/swl-ses v1.6.8
 
 ## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
 
@@ -8,8 +8,8 @@ Todo contenido generado DEBE ser en español de México: respuestas, código com
 ### Uso obligatorio del sistema SWL
 Toda tarea DEBE usar el sistema SWL completo: agentes especializados, habilidades, hooks y comandos `/swl:*`. NO hacer trabajo directo que un agente SWL especializado haría mejor. Para tareas complejas: `orquestador-swl`. Para implementación: `implementador-swl` o el agente de stack. Para debugging: `depurador-swl`. Para revisión: `revisor-codigo-swl`. Para planificación: `planificador-swl`. Cargar skills con `Skill("nombre")` antes de implementar.
 
-### Investigar antes de editar
-Investigar el codebase ANTES de editar. NUNCA modificar código que no se ha leído primero. Leer el archivo completo, entender el contexto, y solo entonces hacer cambios.
+### Cuatro principios de implementación (Karpathy)
+Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Tabla operativa + mapeo a agentes SWL en `@docs/karpathy-principios.md`. Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
 
 ### Lectura de documentos Office y Jupyter
 Cuando necesites leer el **contenido** de un archivo `.docx`, `.xlsx`, `.xls`, `.pptx` o `.ipynb`, NUNCA uses el Read tool directamente (no soporta esos formatos). Usa:

package/README.md

@@ -1,4 +1,4 @@
-# swl-ses v1.6.7
+# swl-ses v1.6.8
 
 > El paquete anterior `@saulwadeleon/swl-software-engineering-system` está deprecado. Migrar a `@saulwade/swl-ses` (npmjs.org canónico) o `@saul-wade/swl-ses` (mirror en GitHub Packages) — el CLI `swl-ses` no cambia.
 

package/comandos/swl/claudemd.md

@@ -128,6 +128,14 @@ y genera `./CLAUDE.md` mínimo con:
   operacional de uso del sistema SWL al inicio de cada sesión. Si el proyecto
   tiene otras reglas locales (`@reglas/seguridad.md`, `@reglas/arquitectura.md`,
   etc.), agregarlas debajo.
+- Sección **Reglas de máxima prioridad** con sub-sección obligatoria
+  **Cuatro principios de implementación (Karpathy)**:
+  ```markdown
+  ### Cuatro principios de implementación (Karpathy)
+  Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
+  ```
+  Esta sub-sección es estándar SWL y cubre los gaps cognitivos más
+  frecuentes del agente sin agregar reglas específicas del proyecto.
 - Sección **Stack** poblada (lenguaje, framework, ORM, package manager)
 - Sección **Comandos** poblada (npm scripts detectados o comandos típicos)
 - Sección **Code style** vacía con placeholders
@@ -137,9 +145,23 @@ y genera `./CLAUDE.md` mínimo con:
 
 Si CLAUDE.md ya existe, **NO lo sobreescribe**. Sugiere correr
 `/swl:claudemd refactor` para mejorar el actual. Si detecta que el CLAUDE.md
-existente NO incluye `@reglas/usar-sistema-swl.md`, emitir hallazgo WARN
+existente NO incluye `@reglas/usar-sistema-swl.md` o NO menciona los cuatro
+principios Karpathy (o `prevencion-sobreingenieria`), emitir hallazgo WARN
 recomendando agregarlo manualmente.
 
+### audit — checks específicos sobre Karpathy
+
+El subcomando `audit` verifica además de las dimensiones estándar:
+
+- ¿El CLAUDE.md menciona los cuatro principios Karpathy (texto literal
+  "Karpathy" o nombres de los 4 principios) o referencia
+  `prevencion-sobreingenieria` con `Skill(...)` o `@reglas/`?
+
+Si NO los menciona y el archivo tiene >50 líneas: emitir hallazgo WARN
+recomendando agregar la sub-sección compacta (4 líneas) como guía de
+implementación. NO emite WARN para CLAUDE.md mínimos (<50 LOC) ni para
+archivos `~/.claude/CLAUDE.md` user-level (esos siguen otro contrato).
+
 ## Variables de entorno
 
 Ver `@docs/variables-entorno.md` sección "Calidad de CLAUDE.md":

package/habilidades/prevencion-sobreingenieria/SKILL.md

@@ -7,12 +7,12 @@ description: >
   implementar features, refactorizar código o resolver bugs — especialmente
   cuando el agente tiende a agregar abstracciones especulativas o tocar código
   fuera del alcance solicitado.
-version: "1.1.0"
+version: "1.2.0"
 evolved: true
-evolved-from: "1.0.0"
-evolved-at: "2026-04-24"
-evolved-by: "aprender"
-evolved-note: "Sección nueva: variables residuales post-refactor son code smell (F841 con ruff)"
+evolved-from: "1.1.0"
+evolved-at: "2026-05-22"
+evolved-by: "absorcion-temp-karpathy"
+evolved-note: "Recurso nuevo: recursos/EXAMPLES.md con 9 ejemplos MAL→BIEN adaptados del repo andrej-karpathy-skills (MIT). Cierra gap de regla skills-estandar.md § Convención EXAMPLES.md."
 herramientasPermitidas: [Read, Grep]
 toolsRequeridos: Read, Grep, Glob
 exclusiones:
@@ -27,6 +27,10 @@ evolvable: true  # default para skill estandar
 Skill derivado de los principios de Andrej Karpathy sobre errores comunes de LLMs
 al generar código, adaptado al ecosistema SWL.
 
+> **Para 9 ejemplos MAL→BIEN lado a lado con código real**, ver
+> [recursos/EXAMPLES.md](recursos/EXAMPLES.md). Cada ejemplo está mapeado a un
+> escenario operativo concreto de SWL (qué agente debe citarlo, en qué flujo).
+
 ## Cuándo cargar
 
 - Antes de implementar cualquier feature nueva con `implementador-swl` o `backend-*-swl`

package/habilidades/prevencion-sobreingenieria/recursos/EXAMPLES.md

@@ -0,0 +1,580 @@
+# Ejemplos MAL→BIEN — prevención de sobre-ingeniería
+
+Catálogo de 9 ejemplos pareados (código que falla / código correcto) para los
+4 principios del skill. Cada uno se mapea a un anti-patrón ya documentado en
+`SKILL.md` y a un escenario operativo de SWL.
+
+Adaptado de
+[andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)
+(MIT) al ecosistema SWL — español de México, escenarios concretos del sistema.
+
+**Cómo usar este archivo**: cuando un agente SWL (`implementador-swl`,
+`revisor-codigo-swl`, agentes de stack) detecta el anti-patrón en su sesión,
+puede citar `recursos/EXAMPLES.md § <ejemplo>` como evidencia observable en
+lugar de invocar la regla abstracta.
+
+---
+
+## Principio 1 — Pensar antes de codificar
+
+### Ejemplo 1.1 — Supuestos ocultos sobre alcance
+
+**Solicitud del usuario**: *"Agrega una feature para exportar datos de usuarios."*
+
+#### ❌ MAL — asume sin preguntar
+
+```python
+def exportar_usuarios(formato='json'):
+    """Exporta todos los usuarios a un archivo."""
+    usuarios = Usuario.query.all()
+
+    if formato == 'json':
+        with open('usuarios.json', 'w') as f:
+            json.dump([u.to_dict() for u in usuarios], f)
+    elif formato == 'csv':
+        with open('usuarios.csv', 'w') as f:
+            writer = csv.DictWriter(f, fieldnames=['id', 'email', 'nombre'])
+            writer.writeheader()
+            writer.writerows([u.to_dict() for u in usuarios])
+
+    return f"Exportados {len(usuarios)} usuarios"
+```
+
+**Problemas**:
+- Asume que se deben exportar TODOS los usuarios (¿paginación? ¿privacidad?)
+- Asume ubicación del archivo sin preguntar
+- Asume campos a incluir (algunos podrían ser sensibles)
+- Hardcodea fieldnames del CSV sin revisar la estructura real
+
+#### ✅ BIEN — explicita supuestos antes de implementar
+
+```
+Antes de implementar, necesito clarificar:
+
+1. **Alcance**: ¿exportar todos los usuarios o un subconjunto filtrado?
+   (implicaciones de privacidad)
+2. **Formato**: cuando dices "exportar", ¿te refieres a:
+   - Descarga de archivo en el navegador?
+   - Job en background con notificación por email?
+   - Endpoint de API que devuelve los datos?
+3. **Campos**: ¿qué campos del usuario? (algunos pueden ser sensibles —
+   datos personales, hash de contraseña, tokens)
+4. **Volumen**: ¿cuántos usuarios típicamente? (afecta el enfoque)
+
+Enfoque más simple: agregar endpoint de API que devuelve JSON paginado.
+Para exportación a archivo necesito más detalle.
+
+¿Cuál prefieres?
+```
+
+**Aplicación SWL**: este patrón está documentado en el `Principio 1` del SKILL.md y
+es exactamente lo que `/swl:discutir-fase` resuelve antes de que llegue a
+`implementador-swl`.
+
+---
+
+### Ejemplo 1.2 — Múltiples interpretaciones, elegir en silencio
+
+**Solicitud del usuario**: *"Haz la búsqueda más rápida."*
+
+#### ❌ MAL — elige una interpretación y construye 200 LOC
+
+```python
+@lru_cache(maxsize=1000)
+async def buscar(query: str) -> list[Resultado]:
+    # ... 200 líneas: cache, índices, async, connection pooling ...
+```
+
+#### ✅ BIEN — presenta interpretaciones con costo estimado
+
+```
+"Más rápida" puede significar tres cosas distintas:
+
+1. **Latencia menor por request** (de 500ms a <100ms)
+   - Agregar índices de BD
+   - Cachear queries frecuentes
+   - Esfuerzo estimado: 2h
+
+2. **Más throughput concurrente**
+   - async/await + connection pooling
+   - Esfuerzo estimado: 4h
+
+3. **Velocidad percibida mejor** (UX)
+   - Mostrar resultados parciales antes
+   - Carga progresiva
+   - Esfuerzo estimado: 3h
+
+La búsqueda actual tarda ~500ms en queries típicas.
+¿Cuál importa más para tu caso de uso?
+```
+
+**Aplicación SWL**: cuando el usuario invoca `/swl:planear-fase` con instrucción
+vaga, el `planificador-swl` debe responder así antes de generar PLAN.md.
+
+---
+
+## Principio 2 — Simplicidad primero
+
+### Ejemplo 2.1 — Abstracción prematura (Strategy pattern para un caso de uso)
+
+**Solicitud del usuario**: *"Agrega una función para calcular descuento."*
+
+#### ❌ MAL — Strategy + Factory + Config para una multiplicación
+
+```python
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+class EstrategiaDescuento(ABC):
+    @abstractmethod
+    def calcular(self, monto: float) -> float: ...
+
+class DescuentoPorcentual(EstrategiaDescuento):
+    def __init__(self, porcentaje: float):
+        self.porcentaje = porcentaje
+    def calcular(self, monto: float) -> float:
+        return monto * (self.porcentaje / 100)
+
+class DescuentoFijo(EstrategiaDescuento):
+    def __init__(self, monto_fijo: float):
+        self.monto_fijo = monto_fijo
+    def calcular(self, monto: float) -> float:
+        return min(self.monto_fijo, monto)
+
+@dataclass
+class ConfigDescuento:
+    estrategia: EstrategiaDescuento
+    compra_minima: float = 0.0
+    descuento_maximo: float = float('inf')
+
+class CalculadoraDescuento:
+    def __init__(self, config: ConfigDescuento):
+        self.config = config
+    def aplicar(self, monto: float) -> float:
+        if monto < self.config.compra_minima:
+            return 0
+        descuento = self.config.estrategia.calcular(monto)
+        return min(descuento, self.config.descuento_maximo)
+
+# 30+ líneas de setup para una multiplicación
+```
+
+#### ✅ BIEN — función directa
+
+```python
+def calcular_descuento(monto: float, porcentaje: float) -> float:
+    """Calcula el descuento. porcentaje en rango 0-100."""
+    return monto * (porcentaje / 100)
+
+# Uso
+descuento = calcular_descuento(100.0, 10.0)  # 10.0
+```
+
+**Cuándo agregar complejidad**: solo cuando aparezca el segundo o tercer tipo
+de descuento. Si la necesidad llega después, refactorizar entonces.
+
+**Aplicación SWL**: regla SKILL.md "Tres usos concretos justifican una
+abstracción; menos de tres, no". Este ejemplo es la materialización del umbral.
+
+---
+
+### Ejemplo 2.2 — Features especulativas no solicitadas
+
+**Solicitud del usuario**: *"Guarda las preferencias del usuario en la base de datos."*
+
+#### ❌ MAL — cache, validator, merge, notificación
+
+```python
+class GestorPreferencias:
+    def __init__(self, db, cache=None, validator=None):
+        self.db = db
+        self.cache = cache or CacheEnMemoria()
+        self.validator = validator or ValidadorDefault()
+
+    def guardar(self, usuario_id: int, prefs: dict,
+                merge: bool = True,
+                validar: bool = True,
+                notificar: bool = False) -> bool:
+        if validar:
+            errores = self.validator.validar(prefs)
+            if errores:
+                raise ValidationError(errores)
+
+        existentes = self.obtener(usuario_id) if merge else {}
+        if merge:
+            existentes.update(prefs)
+            prefs = existentes
+
+        self.db.execute(
+            "UPDATE usuarios SET preferencias = ? WHERE id = ?",
+            (json.dumps(prefs), usuario_id)
+        )
+
+        if self.cache:
+            self.cache.set(f"prefs:{usuario_id}", prefs)
+
+        if notificar:
+            self.notificar_cambio(usuario_id, prefs)
+
+        return True
+```
+
+#### ✅ BIEN — solo lo que pidieron
+
+```python
+def guardar_preferencias(db, usuario_id: int, preferencias: dict):
+    """Guarda las preferencias del usuario en la base de datos."""
+    db.execute(
+        "UPDATE usuarios SET preferencias = ? WHERE id = ?",
+        (json.dumps(preferencias), usuario_id)
+    )
+```
+
+**Agregar después si aparece la necesidad**:
+- Caching → cuando aparezca problema de performance medible
+- Validación → cuando lleguen datos malformados a la BD
+- Merging → cuando emerja el requisito explícito
+
+**Aplicación SWL**: este es exactamente el escenario donde `revisor-codigo-swl`
+debe emitir veto item DRY/sobre-ingeniería contra commits que agregan
+parámetros opcionales sin requisito documentado.
+
+---
+
+## Principio 3 — Cambios quirúrgicos
+
+### Ejemplo 3.1 — Drive-by refactoring (refactor de oportunidad)
+
+**Solicitud del usuario**: *"Corrige el bug donde los emails vacíos rompen el validador."*
+
+#### ❌ MAL — corrige el bug Y "mejora" todo lo demás
+
+```diff
+  def validar_usuario(datos_usuario):
+-     # Verificar formato de email
+-     if not datos_usuario.get('email'):
++     """Valida los datos del usuario."""
++     email = datos_usuario.get('email', '').strip()
++
++     # Validar email
++     if not email:
+          raise ValueError("Email requerido")
+-
+-     # Validación básica de email
+-     if '@' not in datos_usuario['email']:
++     if '@' not in email or '.' not in email.split('@')[1]:
+          raise ValueError("Email inválido")
+
+-     # Verificar nombre de usuario
+-     if not datos_usuario.get('nombre_usuario'):
++     # Validar nombre de usuario
++     nombre_usuario = datos_usuario.get('nombre_usuario', '').strip()
++     if not nombre_usuario:
+          raise ValueError("Nombre de usuario requerido")
++     if len(nombre_usuario) < 3:
++         raise ValueError("Nombre de usuario muy corto")
++     if not nombre_usuario.isalnum():
++         raise ValueError("Nombre de usuario debe ser alfanumérico")
+
+      return True
+```
+
+**Problemas**:
+- "Mejoró" la validación de email más allá del fix
+- Agregó validación de username que nadie pidió
+- Cambió comentarios
+- Agregó docstring
+
+#### ✅ BIEN — solo el fix necesario
+
+```diff
+  def validar_usuario(datos_usuario):
+      # Verificar formato de email
+-     if not datos_usuario.get('email'):
++     email = datos_usuario.get('email', '')
++     if not email or not email.strip():
+          raise ValueError("Email requerido")
+
+      # Validación básica de email
+-     if '@' not in datos_usuario['email']:
++     if '@' not in email:
+          raise ValueError("Email inválido")
+
+      # Verificar nombre de usuario
+      if not datos_usuario.get('nombre_usuario'):
+          raise ValueError("Nombre de usuario requerido")
+
+      return True
+```
+
+**Solo cambió**: las líneas específicas que corrigen el manejo del email vacío.
+
+**Aplicación SWL**: regla del SKILL.md "Cada línea cambiada debe trazar
+directamente al requisito del usuario". `revisor-codigo-swl` revisa cada línea
+del diff contra esta regla.
+
+---
+
+### Ejemplo 3.2 — Style drift (cambiar estilo no solicitado)
+
+**Solicitud del usuario**: *"Agrega logging a la función `subir_archivo`."*
+
+#### ❌ MAL — reformatea todo: comillas, type hints, espaciado
+
+```diff
+- def subir_archivo(ruta, destino):
++ def subir_archivo(ruta: str, destino: str) -> bool:
++     """Sube archivo al destino con logging."""
++     logger.info(f"Subiendo {ruta} a {destino}")
++
+      try:
+-         with open(ruta, 'rb') as f:
+-             datos = f.read()
+-
+-         response = requests.post(destino, files={'file': datos})
+-
+-         if response.status_code == 200:
+-             return True
+-         else:
+-             return False
++         with open(ruta, "rb") as f:
++             datos = f.read()
++         response = requests.post(destino, files={"file": datos})
++         exito = response.status_code == 200
++
++         if exito:
++             logger.info(f"Subida exitosa: {ruta}")
++         else:
++             logger.error(f"Subida falló: {ruta}, status={response.status_code}")
++
++         return exito
+      except Exception as e:
+-         print(f"Error: {e}")
++         logger.exception(f"Error subiendo {ruta}: {e}")
+          return False
+```
+
+**Problemas**:
+- Cambió comillas de simples a dobles
+- Agregó type hints que nadie pidió
+- Agregó docstring
+- Reformateó espaciado
+- Cambió la lógica del return booleano
+
+#### ✅ BIEN — respeta estilo existente
+
+```diff
++ import logging
++
++ logger = logging.getLogger(__name__)
++
+  def subir_archivo(ruta, destino):
++     logger.info(f'Iniciando subida: {ruta}')
+      try:
+          with open(ruta, 'rb') as f:
+              datos = f.read()
+
+          response = requests.post(destino, files={'file': datos})
+
+          if response.status_code == 200:
++             logger.info(f'Subida exitosa: {ruta}')
+              return True
+          else:
++             logger.error(f'Subida falló: {ruta}, status={response.status_code}')
+              return False
+      except Exception as e:
+-         print(f"Error: {e}")
++         logger.exception(f'Error subiendo: {ruta}')
+          return False
+```
+
+**Respetó**: comillas simples, ausencia de type hints, patrón booleano existente,
+estilo de espaciado.
+
+**Aplicación SWL**: este caso es señal de alerta en el "Resumen de señales de
+alerta" del SKILL.md ("Se modificaron archivos fuera del scope"). El hook
+pre-commit y `revisor-codigo-swl` deben marcarlo.
+
+---
+
+## Principio 4 — Ejecución orientada a metas
+
+### Ejemplo 4.1 — Plan vago vs criterios verificables
+
+**Solicitud del usuario**: *"Arregla el sistema de autenticación."*
+
+#### ❌ MAL — plan genérico sin criterios de éxito
+
+```
+Voy a arreglar el sistema de autenticación así:
+1. Revisar el código
+2. Identificar problemas
+3. Hacer mejoras
+4. Probar los cambios
+
+[procede a hacer cambios sin criterio de éxito claro]
+```
+
+#### ✅ BIEN — pide la meta concreta, luego plan verificable
+
+```
+Para "arreglar autenticación" necesito definir el criterio de éxito.
+¿Qué problema específico estamos resolviendo?
+
+Si el problema es "los usuarios quedan logueados después de cambiar contraseña":
+
+Plan:
+1. Test: cambiar contraseña → verificar que la sesión vieja queda invalidada
+   Verificación: el test FALLA (reproduce el bug)
+
+2. Implementación: invalidar sesiones al cambiar contraseña
+   Verificación: el test PASA
+
+3. Casos edge: múltiples sesiones activas, cambios concurrentes
+   Verificación: tests adicionales PASAN
+
+4. Sin regresión: tests de auth existentes siguen pasando
+   Verificación: suite completa en verde
+
+Cobertura actual de auth: [N%]
+¿Cuál es el problema específico que ves?
+```
+
+**Aplicación SWL**: `Skill("verificar-trabajo")` aplica este patrón con 4
+niveles goal-backward (EXISTE → SUSTANTIVO → CONECTADO → DATOS_FLUYEN). El
+ejemplo materializa el nivel "DATOS_FLUYEN" con tests verificables.
+
+---
+
+### Ejemplo 4.2 — Multi-paso con verificación incremental
+
+**Solicitud del usuario**: *"Agrega rate limiting a la API."*
+
+#### ❌ MAL — implementación completa en un solo commit de 300 LOC
+
+```python
+# Implementa rate limiting completo con Redis, múltiples estrategias,
+# sistema de configuración y monitoreo en un solo commit de 300 líneas.
+# Sin pasos de verificación claros.
+```
+
+#### ✅ BIEN — incremental con verificación por paso
+
+```
+Plan para rate limiting:
+
+1. Rate limiting básico en memoria (un solo endpoint)
+   Verificación:
+   - Test: 100 requests → primeros 10 pasan, resto recibe 429
+   - Manual: curl al endpoint 11 veces, ver error de rate limit
+
+2. Extraer a middleware (aplicar a todos los endpoints)
+   Verificación:
+   - Test: rate limits aplican a /usuarios y /posts
+   - Tests existentes de endpoints siguen pasando
+
+3. Backend Redis (para multi-instancia)
+   Verificación:
+   - Test: rate limit persiste entre restarts de la app
+   - Test: dos instancias comparten el contador
+
+4. Configuración (rates por endpoint)
+   Verificación:
+   - Test: /search permite 10/min, /usuarios permite 100/min
+   - Archivo de config parseado correctamente
+
+Cada paso es verificable y desplegable independientemente.
+¿Empezamos con el paso 1?
+```
+
+**Aplicación SWL**: este patrón es el core de `/swl:ejecutar-fase` con commits
+atómicos por tarea. Cada paso del plan corresponde a un commit verificable.
+
+---
+
+### Ejemplo 4.3 — Test-first: reproducir antes de corregir
+
+**Solicitud del usuario**: *"El ordenamiento se rompe cuando hay scores duplicados."*
+
+#### ❌ MAL — corrige sin reproducir primero
+
+```python
+# Cambia inmediatamente la lógica de sort sin confirmar el bug
+def ordenar_scores(scores):
+    return sorted(scores, key=lambda x: (-x['score'], x['nombre']))
+```
+
+#### ✅ BIEN — reproduce con test, luego corrige
+
+```python
+# 1. Primero: test que reproduce el problema
+def test_ordenar_con_scores_duplicados():
+    """Verifica el ordenamiento cuando varios items tienen el mismo score."""
+    scores = [
+        {'nombre': 'Ana', 'score': 100},
+        {'nombre': 'Bruno', 'score': 100},
+        {'nombre': 'Carlos', 'score': 90},
+    ]
+
+    resultado = ordenar_scores(scores)
+
+    # Bug: el orden es no determinista para duplicados
+    # Corriendo este test varias veces debería ser consistente
+    assert resultado[0]['score'] == 100
+    assert resultado[1]['score'] == 100
+    assert resultado[2]['score'] == 90
+
+# Verificación: corre el test 10 veces → falla con orden inconsistente
+
+# 2. Ahora sí, fix con sort estable
+def ordenar_scores(scores):
+    """Ordena por score descendente, luego nombre ascendente para empates."""
+    return sorted(scores, key=lambda x: (-x['score'], x['nombre']))
+
+# Verificación: test pasa consistentemente
+```
+
+**Aplicación SWL**: regla del SKILL.md "Test primero para bugs". `tdd-qa-swl`
+con `Skill("tdd-workflow")` aplica este ciclo RED→GREEN→REFACTOR.
+
+---
+
+## Resumen de anti-patrones
+
+| Principio | Anti-patrón | Fix |
+|---|---|---|
+| Pensar antes | Asume en silencio formato, campos, alcance | Listar supuestos explícitamente, preguntar |
+| Simplicidad | Strategy pattern para un solo cálculo | Una función hasta que la complejidad sea real |
+| Quirúrgico | Reformatea comillas, agrega type hints mientras corrige bug | Solo las líneas que arreglan el bug reportado |
+| Orientado a metas | "Voy a revisar y mejorar el código" | "Test que reproduce X → hacerlo pasar → sin regresiones" |
+
+---
+
+## Insight clave
+
+Los ejemplos "sobre-complicados" no son obviamente incorrectos: siguen design
+patterns y buenas prácticas. El problema es el **timing**: agregan complejidad
+antes de que se necesite, lo cual:
+
+- Hace el código más difícil de entender
+- Introduce más bugs
+- Toma más tiempo implementar
+- Es más difícil de probar
+
+Las versiones "simples" son:
+- Más fáciles de entender
+- Más rápidas de implementar
+- Más fáciles de probar
+- Refactorizables después cuando la complejidad realmente se necesite
+
+> **Buen código es código que resuelve el problema de hoy de forma simple,
+> no el problema de mañana de forma prematura.**
+
+---
+
+## Origen y licencia
+
+Adaptado de [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)
+(MIT License, Andrej Karpathy + Forrest Chang). El skill SWL
+`prevencion-sobreingenieria` consolida los 4 principios + sección propia
+"Variables residuales post-refactor" + calibración para tasks triviales.

package/habilidades/swl-claudemd/SKILL.md

@@ -58,7 +58,7 @@ node scripts/auditar-claudemd.js --json    # para parsing
 node scripts/auditar-claudemd.js --strict  # exit 1 si WARN
 ```
 
-El auditor verifica seis dimensiones:
+El auditor verifica siete dimensiones:
 
 | Dimensión | Regla | Severidad |
 |---|---|---|
@@ -68,6 +68,7 @@ El auditor verifica seis dimensiones:
 | Secciones canónicas | Stack, Comandos, Code style, Conventions presentes | WARN |
 | @references | Archivos >80 líneas usan al menos un `@docs/...md` | WARN |
 | Placeholders | `[TBD]`, `[TODO]`, `[COMPLETAR]` | ERROR |
+| Karpathy reference | Project-level >50 LOC menciona "Karpathy", los 4 principios, o `prevencion-sobreingenieria` | WARN |
 
 Veredicto final: ERROR → WARN → OK (el más severo gana).
 
@@ -168,6 +169,9 @@ Genera `./CLAUDE.md` raíz del proyecto detectando stack actual.
 2. Ejecutar `detectarStackDetallado(process.cwd())` (de
    `scripts/lib/detectar-stack-detallado.js`).
 3. Generar archivo con secciones pobladas:
+   - **Reglas obligatorias**: `@reglas/usar-sistema-swl.md`
+   - **Reglas de máxima prioridad** con sub-sección **Cuatro principios de
+     implementación (Karpathy)** — bloque exacto definido abajo
    - **Stack**: lenguaje + framework + ORM + package manager detectados
    - **Comandos**: npm scripts detectados o comandos típicos por lenguaje
    - **Code style**: placeholders explícitos (`<!-- pendiente: definir convención de X -->`)
@@ -177,6 +181,42 @@ Genera `./CLAUDE.md` raíz del proyecto detectando stack actual.
 4. Imprimir mensaje con próximo paso: "ejecuta `/swl:claudemd audit`
    para verificar".
 
+### Bloque obligatorio Karpathy en init-project
+
+Toda generación nueva incluye esta sub-sección literal en "Reglas de
+máxima prioridad":
+
+```markdown
+### Cuatro principios de implementación (Karpathy)
+Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
+```
+
+Justificación: el skill `prevencion-sobreingenieria` y su `recursos/EXAMPLES.md`
+se distribuyen con cada instalación SWL, así que la referencia siempre resuelve.
+La sub-sección compacta (5 líneas) ataca los gaps cognitivos más frecuentes
+de cualquier proyecto sin agregar opinión específica.
+
+### Check Karpathy en audit
+
+`scripts/auditar-claudemd.js` debe verificar (search regex case-insensitive):
+
+- `/karpathy/i`
+- `/cuatro principios/i` o `/4 principios/i`
+- `/prevencion-sobreingenieria/`
+- `/Skill\(["'`]prevencion-sobreingenieria["'`]\)/`
+
+Si NO encuentra ninguna AND el archivo tiene >50 LOC AND es project-level
+(no `~/.claude/CLAUDE.md`): emitir hallazgo WARN con mensaje:
+
+```
+CLAUDE.md no menciona los cuatro principios Karpathy ni el skill
+prevencion-sobreingenieria. Considerar agregar la sub-sección compacta
+(ver /swl:claudemd init-project § Bloque obligatorio Karpathy).
+```
+
+Esta dimensión es WARN, no ERROR — guía sin imponer. CLAUDE.md user-level
+(`~/.claude/`) NO se evalúa contra este check.
+
 ---
 
 ## Gotchas / Errores comunes no obvios

package/manifiestos/skills-lock.json

@@ -1,8 +1,8 @@
 {
   "lockfileVersion": 1,
-  "generatedAt": "2026-05-21T20:46:43.799Z",
+  "generatedAt": "2026-05-22T17:02:33.598Z",
   "skillsCount": 177,
-  "lockHash": "sha256:f87e22a97a86a4abe7f1da215dc894433c3c8c9dfe9434e53d5a70e5b4912406",
+  "lockHash": "sha256:5d644809f2e8c7741a4553f1f6f493d309d4913782c9560bf06bd735eed1701e",
   "skills": [
     {
       "nombre": "accesibilidad-a11y",
@@ -889,9 +889,9 @@
     {
       "nombre": "prevencion-sobreingenieria",
       "path": "habilidades/prevencion-sobreingenieria/SKILL.md",
-      "hash": "sha256:7396e1d8e7c87dd0154e9b34d1eff4124997566ca9a9da63b8a0514680af131e",
-      "bytes": 16468,
-      "version": "\"1.1.0\""
+      "hash": "sha256:9f6d0d4f5c54e29aff3e5fa66d89c42a0dabfd0a59eefcfbf6715ca085984f3e",
+      "bytes": 16812,
+      "version": "\"1.2.0\""
     },
     {
       "nombre": "privacy-memoria",
@@ -1099,8 +1099,8 @@
     {
       "nombre": "swl-claudemd",
       "path": "habilidades/swl-claudemd/SKILL.md",
-      "hash": "sha256:18cef250bd32a7841db3b6362b9303679bf2851e5e1efe7f3d81f0dd514ec5eb",
-      "bytes": 11585,
+      "hash": "sha256:dd8ef172d38668e261fc88ff22e614559a05a4f13b2c612c2da3ea2388494377",
+      "bytes": 13666,
       "version": "\"1.0.2\""
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saulwade/swl-ses",
-  "version": "1.6.7",
+  "version": "1.6.8",
   "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 61 agentes, 177 habilidades, 44 comandos, 69 reglas y 42 hooks. Soporta 11 lenguajes y 7 runtimes: Claude Code, OpenClaude, OpenCode, Gemini CLI, Cursor, Codex CLI (soporte completo); GitHub Copilot (soporte parcial). 100% en espanol (Mexico). Multi-target install (--target CSV / --all-runtimes), autoconfig MCP en Cursor/Codex con --with-mcp, agentes Codex en TOML, hooks Cursor (17 eventos) y Codex (6 eventos). Gateway bidireccional con relay Telegram y auditoria profunda Nemesis con loop evaluator-optimizer opt-in (ADR-0021) y 8 tools ejecutables. v1.6.5 integra 3 patrones de awesome-codex-skills (ComposioHQ, MIT) — agent-deep-links + changelog-generator + gh-fix-ci-swl — ADR-0029, y promueve 3 evoluciones SIGAF al sistema global (D1 nemesis SendMessage + D2 verificar smoke frontend + L2 alineacion veredicto).",
   "bin": {
     "swl-ses": "bin/swl-ses.js",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "swl-ses",
-  "version": "1.6.7",
+  "version": "1.6.8",
   "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot. 61 agentes, 177 habilidades, 44 comandos, 69 reglas y 42 hooks. 62 librerias. 11 lenguajes. Soporta Claude Code, Copilot, OpenCode, Codex y Gemini CLI. Loop evaluator-optimizer en /swl:nemesis (ADR-0021). 3 patrones de awesome-codex-skills (ComposioHQ, MIT) adoptados (ADR-0029) — agent-deep-links + changelog-generator + gh-fix-ci-swl. Promueve 3 evoluciones SIGAF (D1 nemesis SendMessage, D2 verificar smoke frontend, L2 alineacion veredicto).",
   "author": "Saul Wade Leon",
   "license": "MIT",

package/scripts/auditar-claudemd.js

@@ -13,6 +13,7 @@
  *   - Presencia de secciones canónicas (Stack, Comandos, Code style, Conventions, @references)
  *   - Uso de @references (al menos 1 si el archivo supera 80 líneas)
  *   - Placeholders sin reemplazar ([TBD], [TODO], [COMPLETAR])
+ *   - Referencia Karpathy (CLAUDE.md project-level >50 LOC menciona los 4 principios o el skill)
  *
  * Uso:
  *   node scripts/auditar-claudemd.js [ruta]                # Audita CLAUDE.md (default: ./)
@@ -26,11 +27,13 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 // ─── Config ───────────────────────────────────────────────────────────────
 const MAX_LINES = parseInt(process.env.SWL_CLAUDEMD_MAX_LINES, 10) || 200;
 const MAX_BULLET_CHARS =
   parseInt(process.env.SWL_CLAUDEMD_MAX_BULLET_CHARS, 10) || 1000;
+const KARPATHY_MIN_LINES = 50;
 
 const SECCIONES_CANONICAS = [
   { nombre: 'Stack', regex: /^##\s+Stack/m },
@@ -39,6 +42,15 @@ const SECCIONES_CANONICAS = [
   { nombre: 'Conventions', regex: /^##\s+(Conventions|Convenciones)/im },
 ];
 
+// Patrones que reconocen que el CLAUDE.md incorpora los 4 principios Karpathy
+// o referencia explícita al skill prevencion-sobreingenieria.
+const KARPATHY_PATTERNS = [
+  /karpathy/i,
+  /cuatro\s+principios/i,
+  /4\s+principios/i,
+  /prevencion-sobreingenieria/i,
+];
+
 const PLACEHOLDERS = /\[(TBD|TODO|COMPLETAR|PENDIENTE|XXX|FIXME)\]/g;
 
 // ─── Auditoría ────────────────────────────────────────────────────────────
@@ -129,6 +141,19 @@ function auditar(rutaClaudeMd) {
     });
   }
 
+  // 6. Referencia a los 4 principios Karpathy o al skill prevencion-sobreingenieria.
+  //    Solo aplica a CLAUDE.md project-level con tamaño no trivial.
+  const tieneReferenciaKarpathy = detectarReferenciaKarpathy(contenido);
+  const esProjectLevel = !esRutaUserLevel(rutaClaudeMd);
+  if (!tieneReferenciaKarpathy && lineas.length > KARPATHY_MIN_LINES && esProjectLevel) {
+    hallazgos.push({
+      severidad: 'WARN',
+      regla: 'karpathy-reference',
+      mensaje: 'CLAUDE.md no menciona los cuatro principios Karpathy ni el skill prevencion-sobreingenieria',
+      sugerencia: 'Agregar la sub-sección compacta (ver `/swl:claudemd init-project` § Bloque obligatorio Karpathy)',
+    });
+  }
+
   // ─── Veredicto ───────────────────────────────────────────────────────────
   const tieneError = hallazgos.some(h => h.severidad === 'ERROR');
   const tieneWarn = hallazgos.some(h => h.severidad === 'WARN');
@@ -145,11 +170,33 @@ function auditar(rutaClaudeMd) {
       secciones_presentes: SECCIONES_CANONICAS.filter(s => s.regex.test(contenido)).map(s => s.nombre),
       secciones_ausentes: seccionesAusentes.map(s => s.nombre),
       tiene_at_references: /@[a-zA-Z][a-zA-Z0-9_\-./]+\.md/.test(contenido),
+      tiene_referencia_karpathy: tieneReferenciaKarpathy,
+      es_project_level: esProjectLevel,
     },
     hallazgos,
   };
 }
 
+/**
+ * True si el contenido menciona los 4 principios Karpathy o el skill
+ * prevencion-sobreingenieria (cualquier coincidencia case-insensitive).
+ */
+function detectarReferenciaKarpathy(contenido) {
+  return KARPATHY_PATTERNS.some(re => re.test(contenido));
+}
+
+/**
+ * True si la ruta apunta a un CLAUDE.md user-level (~/.claude/CLAUDE.md).
+ * El check Karpathy NO aplica a user-level — esos siguen otro contrato
+ * (preferencias personales, no implementación).
+ */
+function esRutaUserLevel(rutaClaudeMd) {
+  if (!rutaClaudeMd) return false;
+  const homeClaudeDir = path.resolve(path.join(os.homedir(), '.claude'));
+  const rutaAbs = path.resolve(rutaClaudeMd);
+  return rutaAbs.startsWith(homeClaudeDir + path.sep) || rutaAbs === path.join(homeClaudeDir, 'CLAUDE.md');
+}
+
 /**
  * Detecta bullets/párrafos cuyo contenido excede MAX_BULLET_CHARS.
  * Un "bullet" es una línea que empieza con `-` o `*` (ignorando indentación).
@@ -249,6 +296,9 @@ function imprimirReporte(resultado) {
       console.log(`  - Secciones ausentes: ${m.secciones_ausentes.join(', ')}`);
     }
     console.log(`  - @references: ${m.tiene_at_references ? 'sí' : 'no'}`);
+    if (m.es_project_level) {
+      console.log(`  - Referencia Karpathy: ${m.tiene_referencia_karpathy ? 'sí' : 'no'}`);
+    }
     console.log('');
   }
 
@@ -294,4 +344,14 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { auditar, ubicarClaudeMd, detectarBulletsGigantes, main, MAX_LINES, MAX_BULLET_CHARS };
+module.exports = {
+  auditar,
+  ubicarClaudeMd,
+  detectarBulletsGigantes,
+  detectarReferenciaKarpathy,
+  esRutaUserLevel,
+  main,
+  MAX_LINES,
+  MAX_BULLET_CHARS,
+  KARPATHY_MIN_LINES,
+};