@saulwade/swl-ses 1.0.0

package/habilidades/prevencion-racionalizacion/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: prevencion-racionalizacion
+description: >
+  Patrones para prevenir que los agentes racionalicen atajos, salten procesos o
+  inventen excusas para no seguir el workflow. Incluye tabla de excusas comunes,
+  red flags de pensamiento y técnicas para construir skills resistentes a la
+  racionalización. Cargar al diseñar skills, al detectar agentes saltando procesos,
+  o al revisar por qué un agente no siguió un paso obligatorio.
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para prevenir sobre-ingeniería o cambios fuera del scope — ese es `prevencion-sobreingenieria`; este skill trata racionalización de *omisión* de pasos obligatorios, no de *adición* innecesaria de complejidad."
+  - "No cargar para evaluar si un proceso fue seguido correctamente después de un incidente — eso es `verificar-trabajo` o revisión post-mortem; este skill sirve para diseñar skills resistentes a la evasión, no para auditoría post-hoc."
+  - "No cargar cuando el agente quiere omitir un paso que no está en la spec — en ese caso aplicar las 4 reglas de desviación del implementador; este skill aplica a pasos obligatorios ya documentados en un proceso."
+  - "No cargar si el skill o proceso a proteger aún no tiene los pasos definidos — las cláusulas anti-racionalización requieren un proceso existente sobre el cual construir las reglas 'sin excepciones'."
+evolvable: true  # default para skill estandar
+---
+# Prevención de Racionalización en Agentes
+
+La racionalización ocurre cuando un agente genera una justificación convincente
+para no seguir un proceso que debería seguir. La justificación suena razonable.
+Puede incluso ser técnicamente correcta en abstracto. Pero en el contexto específico,
+es una excusa para tomar un atajo. El resultado es el mismo que si el proceso
+no existiera: el trabajo queda incompleto o mal hecho.
+
+## Cuándo cargar este skill
+
+Invoca `Skill("prevencion-racionalizacion")` cuando:
+
+- Se diseña un skill nuevo y se quieren incluir cláusulas anti-racionalización
+- Se detecta que un agente saltó un paso obligatorio con una justificación
+- Se hace autoresearch de un skill que los agentes no siguen consistentemente
+- Se revisa por qué un proceso falló en producción y la causa fue un atajo
+- Se escribe la sección "Sin excepciones" de cualquier regla obligatoria
+
+## Qué es la racionalización en agentes AI
+
+Un agente racionaliza cuando:
+1. Encuentra que seguir el proceso requiere esfuerzo adicional
+2. Genera una razón por la cual ese esfuerzo no es necesario en este caso
+3. Procede sin seguir el proceso, convencido de que la razón es válida
+
+La diferencia con una excepción legítima es que la excepción legítima está
+documentada en el proceso mismo. Si no está documentada, es racionalización.
+
+## Tabla de excusas comunes
+
+| Excusa del agente | Realidad |
+|---|---|
+| "Es demasiado simple para necesitar diseño" | Hasta features simples se benefician de 5 minutos de diseño. La simplicidad percibida es subjetiva. |
+| "Ya sé qué hacer, no necesito preguntar al usuario" | El usuario puede tener contexto crítico que el agente no tiene. Preguntar cuesta menos que reimplementar. |
+| "Los tests no son necesarios para este cambio" | Todo cambio que modifica comportamiento necesita verificación. La excepción está en el proceso, no en el juicio del agente. |
+| "Solo esta vez voy a saltar este paso" | "Solo esta vez" establece precedente. La próxima vez será más fácil justificarlo. |
+| "El espíritu del proceso es lo que importa" | Si se viola la letra del proceso, se viola el espíritu. El proceso tiene la forma que tiene por razones concretas. |
+| "Ya intenté 3 veces, debo cambiar de enfoque radicalmente" | 3 intentos fallidos con el mismo enfoque indican un problema de raíz, no de enfoque. Diagnosticar antes de cambiar. |
+| "Este skill no aplica a mi situación" | Si hay 1% de probabilidad de que aplique, debe invocarse. El costo de invocar es bajo; el costo de no invocar cuando debía puede ser alto. |
+| "El contexto es diferente aquí" | El proceso fue diseñado para contextos variados. Si el contexto genuinamente lo invalida, hay que documentarlo y escalar. |
+| "El usuario no lo va a notar" | El usuario puede no notar ahora. Lo notará cuando el sistema falle de una forma que este paso prevenía. |
+| "Voy a completarlo después" | "Después" no existe en el contexto de un agente. Si no se hace ahora, no se hace. |
+
+## Red flags de pensamiento
+
+Cuando un agente produce cualquiera de estos patrones de pensamiento, debe detenerse
+y aplicar el proceso completo:
+
+- **"No necesito..."** — si existe un proceso para algo, se necesita. Demostrar con
+  evidencia del proceso mismo que no aplica, no con razonamiento propio.
+
+- **"Esto es obvio..."** — lo obvio para el agente puede no serlo para el usuario
+  o para otro agente. Si es obvio, documentarlo cuesta poco. Si no es obvio, documentarlo
+  previene errores.
+
+- **"Solo voy a..."** — el "solo" minimiza el impacto. Los cambios "solo" tienen
+  consecuencias que el agente no anticipó. Hacer el proceso completo.
+
+- **"Dado el contexto, puedo saltar..."** — el proceso existe precisamente para
+  contextos específicos. Si el contexto justifica una excepción, la excepción debe
+  estar en el proceso. Si no está, no es una excepción, es una violación.
+
+- **"Ya lo hice antes sin problema..."** — el éxito pasado no garantiza el éxito
+  futuro. Cada instancia del proceso es independiente.
+
+- **"El agente anterior ya verificó esto..."** — cada agente es responsable de
+  verificar lo que afirma. La verificación de otro agente no es evidencia propia.
+
+## Principio fundamental
+
+> Si hay 1% de probabilidad de que un skill aplique, DEBE invocarse.
+
+El costo de invocar un skill innecesario es bajo: unos tokens extra de contexto.
+El costo de no invocar un skill necesario puede ser alto: un bug en producción,
+un requisito no implementado, una vulnerabilidad de seguridad.
+
+La racionalización siempre infravalora el costo de no seguir el proceso y sobrevalora
+el costo de seguirlo. Corregir ese sesgo sistemáticamente.
+
+## Cómo construir skills resistentes a la racionalización
+
+Al diseñar o actualizar un skill, incluir estas secciones explícitas:
+
+### 1. Listar excusas específicas del dominio
+
+No usar excusas genéricas. Investigar qué atajos específicos toman los agentes
+en este dominio y documentarlos:
+
+```markdown
+## Excusas comunes en este dominio — y por qué son incorrectas
+
+| Excusa | Por qué es incorrecta |
+|---|---|
+| [excusa específica 1] | [razón concreta] |
+| [excusa específica 2] | [razón concreta] |
+```
+
+### 2. Agregar sección "Sin excepciones" explícita
+
+```markdown
+## Sin excepciones
+
+Las siguientes reglas no tienen excepciones. Si el agente encuentra una razón
+para no seguirlas, esa razón es racionalización, no una excepción legítima:
+
+- [regla 1] — SIEMPRE, incluso si [excusa típica]
+- [regla 2] — SIEMPRE, incluso si [excusa típica]
+
+La única excepción legítima es que el proceso mismo la documente explícitamente.
+```
+
+### 3. Incluir red flags de pensamiento específicos
+
+```markdown
+## Señales de racionalización en este contexto
+
+Detener y reiniciar el proceso si aparece cualquiera de estos pensamientos:
+- "Este endpoint es demasiado simple para necesitar schema Pydantic"
+- "Este test es obvio y no aporta valor"
+- [red flag específico del dominio]
+```
+
+### 4. Documentar el costo de saltarse el proceso
+
+Los agentes racionalizan mejor cuando no tienen visibilidad del costo real:
+
+```markdown
+## Qué pasa cuando se salta este proceso
+
+- [consecuencia concreta 1 de saltarse el proceso]
+- [consecuencia concreta 2]
+```
+
+## Checklist anti-racionalización
+
+Al revisar si un agente siguió un proceso:
+
+- [ ] El agente invocó todos los skills listados en la spec
+- [ ] El agente ejecutó todos los pasos del protocolo, no solo los convenientes
+- [ ] Si el agente se saltó un paso, la excepción está documentada en el proceso mismo
+- [ ] No hubo "solo esta vez" ni "en este contexto particular"
+- [ ] El agente reportó evidencia, no confianza
+
+## Cuándo NO cargar
+
+- Se detecta que el agente está agregando abstracciones o código que nadie pidió — eso es sobre-ingeniería, no racionalización; cargar `prevencion-sobreingenieria`.
+- El paso omitido no estaba documentado en el proceso — las cláusulas anti-racionalización protegen pasos explícitos; si el paso falta en la spec, primero definirlo y luego protegerlo.
+- Se quiere auditar si un proceso específico fue ejecutado correctamente tras una sesión — eso es `verificar-trabajo`; este skill diseña skills resistentes a evasión futura, no valida ejecuciones pasadas.
+- La causa del atajo fue un bug en el proceso, no una justificación del agente — en ese caso aplicar la Regla 1 (AUTO-FIX) del implementador; la racionalización requiere que el agente haya generado activamente una excusa.
+
+## Gotchas / Errores comunes no obvios
+
+- **Cláusula "sin excepciones" tan absoluta que bloquea casos legítimos**: el agente no puede avanzar porque el proceso dice "SIEMPRE invocar X, sin excepción" pero hay un escenario técnico legítimo donde X no está disponible. Causa: las cláusulas anti-racionalización se redactaron sin documentar las excepciones reales del dominio. Solución: el proceso debe incluir las excepciones legítimas explícitamente — toda excepción no documentada es racionalización, pero toda excepción documentada en el proceso sí es válida; redactar las cláusulas como "SIEMPRE, salvo [excepción documentada aquí]".
+- **Red flag "ya lo hice antes sin problema" usado para validar un atajo que efectivamente es correcto**: el agente tiene evidencia empírica real de que el paso puede omitirse en ese contexto específico. Causa: los red flags son señales de alerta, no prohibiciones absolutas. Solución: si el agente tiene evidencia de que un paso es innecesario en un contexto específico, la acción correcta es documentar la excepción en el proceso (Regla 2 AUTO-ADD del implementador), no ignorar el red flag ni proceder silenciosamente.
+- **Tabla de excusas del dominio rellena con excusas genéricas del skill base**: el skill creado tiene como excusa de dominio "este skill no aplica a mi situación" en lugar de una excusa específica del dominio técnico. Causa: copiar la tabla de excusas genéricas sin adaptarla. Solución: las excusas de dominio deben ser observadas de la práctica real — revisar los logs de sesión donde el agente saltó el proceso para extraer las justificaciones reales que usó, no inventarlas a priori.
+- **Usuario reporta "sigue fallando" tras un fix y el agente parcha el síntoma sin investigar causa raíz**: el agente aplica un segundo fix en la misma capa donde aplicó el primero, asumiendo que el primer fix estaba incompleto. En realidad, el bug está en una capa distinta (ej: se normaliza el input del formulario pero el bug real es que la consulta de deduplicación usa una columna cache stale; el tercer usuario reporta duplicados no por error de normalización, sino porque la comparación se hace contra `nombre_normalizado` en BD que fue calculado por una versión anterior de la función). Causa: el modelo mental del agente se ancla en la primera hipótesis — "es el normalizador" — y todos los fixes siguientes intentan mejorar el normalizador en lugar de cuestionar la hipótesis. Solución: cuando el usuario reporta "mismo síntoma tras fix", ejecutar **3 preguntas anti-anclaje** antes de tocar código: (1) ¿qué capa del sistema NO modifiqué en el primer fix?, (2) ¿hay estado persistido entre requests (BD, caché, sesión) que pueda tener valores calculados por la versión anterior del código?, (3) ¿el test que reproduce el bug empezaba con la BD limpia o con datos pre-existentes? Si (3) es "pre-existentes" y el fix no tocó esos datos, el bug probablemente está en la interacción entre el código nuevo y el estado viejo.
+
+---
+*Skill creado con swl:crear-skill el 2026-03-31. Version 1.0.1 (+ Gotcha meta-aprendizaje 2026-04-20).*

package/habilidades/prevencion-sobreingenieria/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: prevencion-sobreingenieria
+description: >
+  Previene sobre-ingeniería y código innecesario en generación asistida por IA.
+  Cuatro principios: pensar antes de codificar, simplicidad primero, cambios
+  quirúrgicos y ejecución orientada a metas verificables. Cargar antes de
+  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"
+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)"
+herramientasPermitidas: [Read, Grep]
+toolsRequeridos: Read, Grep, Glob
+exclusiones:
+  - "No cargar cuando el agente omite pasos obligatorios del proceso — eso es racionalización, no sobre-ingeniería; cargar `prevencion-racionalizacion`."
+  - "No cargar para tasks one-liner obvias (fix de typo, rename de variable, one-shot de una línea) — el propio skill indica que la simplicidad aplica al proceso; añadir análisis de sobre-ingeniería a cambios triviales es en sí mismo sobre-ingeniería."
+  - "No cargar para auditar código ya existente en busca de complejidad acumulada — ese análisis es parte de `mapear-codebase` o `revisor-codigo-swl`; este skill guía la implementación en curso, no la auditoría de deuda técnica."
+  - "No cargar cuando la abstracción propuesta tiene 3 o más casos de uso concretos ya identificados — el criterio de 3 usos es el umbral del skill para justificar una abstracción; por encima de ese umbral, diseñarla es correcto."
+evolvable: true  # default para skill estandar
+---
+# Prevención de sobre-ingeniería
+
+Skill derivado de los principios de Andrej Karpathy sobre errores comunes de LLMs
+al generar código, adaptado al ecosistema SWL.
+
+## Cuándo cargar
+
+- Antes de implementar cualquier feature nueva con `implementador-swl` o `backend-*-swl`
+- Cuando un agente tiende a agregar abstracciones que nadie pidió
+- Al refactorizar código existente (riesgo de "mejorar" código adyacente)
+- Cuando el usuario reporta que el agente "hace demasiado" o "cambia cosas que no debía"
+- En revisiones de código donde se detecta complejidad innecesaria
+
+## Principio 1 — Pensar antes de codificar
+
+Antes de escribir una sola línea, explicitar supuestos y resolver ambigüedades.
+
+### Reglas
+
+1. **Explicitar supuestos** — Si hay ambigüedad en la instrucción, preguntar. NUNCA
+   asumir silenciosamente qué quiso decir el usuario.
+2. **Presentar interpretaciones** — Si hay múltiples formas válidas de resolver el
+   problema, presentarlas brevemente y dejar que el usuario elija.
+3. **Surfacear tradeoffs** — Si la solución tiene consecuencias no obvias (performance,
+   complejidad, dependencias nuevas), mencionarlas antes de implementar.
+
+### Anti-patrón
+
+```python
+# MAL — asume scope sin preguntar
+def exportar_usuarios():
+    usuarios = db.query(Usuario).all()
+    csv = generar_csv(usuarios, campos=TODOS_LOS_CAMPOS)
+    enviar_email(admin, csv)
+    registrar_log_auditoria("export_usuarios")
+    return csv
+# El usuario solo pidió "exportar usuarios" — ¿qué campos? ¿formato?
+# ¿enviar email? ¿log de auditoría? Todo fue asumido.
+
+# BIEN — clarifica antes de implementar
+# Antes de implementar: ¿qué campos necesitas en el export?
+# ¿Formato CSV o JSON? ¿Solo usuarios activos o todos?
+# ¿Se requiere notificación o solo el archivo?
+def exportar_usuarios(campos: list[str], solo_activos: bool = True) -> bytes:
+    query = db.query(Usuario)
+    if solo_activos:
+        query = query.filter(Usuario.es_activo == True)
+    return generar_csv(query.all(), campos=campos)
+```
+
+## Principio 2 — Simplicidad primero
+
+El código más simple que resuelve el problema es el código correcto. Toda
+complejidad adicional requiere justificación explícita.
+
+### Reglas
+
+1. **Código mínimo viable** — Escribir la solución más corta y clara que cumpla
+   el requisito. Si 200 líneas pueden ser 50, reescribir.
+2. **Sin abstracciones especulativas** — No crear interfaces, factories, strategies
+   ni patrones de diseño para un solo caso de uso. Tres usos concretos justifican
+   una abstracción; menos de tres, no.
+3. **Sin features fantasma** — No agregar configurabilidad, flags, parámetros
+   opcionales ni manejo de errores para escenarios que no existen hoy.
+4. **Sin error handling para lo imposible** — No validar que un parámetro interno
+   no sea null cuando el tipo lo garantiza. Validar solo en fronteras del sistema.
+
+### Anti-patrón
+
+```python
+# MAL — Strategy pattern para un solo tipo de descuento
+class DiscountStrategy(ABC):
+    @abstractmethod
+    def calculate(self, price: Decimal) -> Decimal: ...
+
+class PercentageDiscount(DiscountStrategy):
+    def __init__(self, pct: Decimal):
+        self.pct = pct
+    def calculate(self, price: Decimal) -> Decimal:
+        return price * self.pct / 100
+
+class DiscountFactory:
+    _strategies = {"percentage": PercentageDiscount}
+    @classmethod
+    def create(cls, type: str, **kwargs) -> DiscountStrategy:
+        return cls._strategies[type](**kwargs)
+
+# BIEN — función directa para un solo caso de uso
+def calcular_descuento(precio: Decimal, porcentaje: Decimal) -> Decimal:
+    return precio * porcentaje / 100
+```
+
+### Test de simplicidad
+
+Antes de hacer commit, preguntar: *¿un ingeniero senior diría que esto está
+sobre-complicado?* Si la respuesta es "sí" o "tal vez", simplificar.
+
+## Principio 3 — Cambios quirúrgicos
+
+Solo tocar el código que la tarea requiere. Cada línea cambiada debe trazar
+directamente al requisito del usuario.
+
+### Reglas
+
+1. **No "mejorar" código adyacente** — Si el usuario pide corregir un bug en la
+   función A, no renombrar variables en la función B ni agregar type hints en C.
+2. **No refactorizar de oportunidad** — Si el código existente funciona y no es
+   parte del cambio, dejarlo. Aunque "podría ser mejor".
+3. **Respetar estilo existente** — Si el archivo usa comillas simples, usar comillas
+   simples. Si usa tabs, usar tabs. Incluso si preferirías otro estilo.
+4. **Solo eliminar lo que tu cambio hizo innecesario** — Si tu cambio hace que un
+   import quede sin uso, elimínalo. Pero no eliminar imports que ya estaban sin uso
+   antes de tu cambio.
+
+### Anti-patrón
+
+```python
+# Tarea: "corregir el cálculo de IVA cuando la tasa es 0%"
+
+# MAL — corrige el bug Y además "mejora" cosas que no le pidieron
+def calcular_impuestos(
+    precio: Decimal,  # type hint agregado (no pedido)
+    tasa: float,
+) -> Decimal:  # return type agregado (no pedido)
+    """Calcula impuestos sobre el precio."""  # docstring agregado (no pedido)
+    if tasa == 0:
+        return Decimal("0")  # ← este es el fix real
+    return precio * Decimal(str(tasa))  # refactorizado sin necesidad
+
+# BIEN — solo el fix necesario
+def calcular_impuestos(precio, tasa):
+    if tasa == 0:
+        return Decimal("0")  # fix: evitar multiplicación innecesaria con tasa 0
+    return precio * Decimal(str(tasa))
+```
+
+### Test quirúrgico
+
+Revisar el diff antes del commit: *¿cada línea cambiada es directamente necesaria
+para cumplir lo que el usuario pidió?* Si hay líneas que no pasan este test,
+revertirlas.
+
+## Principio 4 — Ejecución orientada a metas
+
+Transformar instrucciones vagas en criterios de éxito verificables antes de
+implementar.
+
+### Reglas
+
+1. **Definir criterio de éxito** — Antes de implementar, declarar qué significa
+   "terminado" en términos verificables (tests que pasan, comportamiento observable).
+2. **Plan breve con verificación** — Para tareas multi-paso, declarar los pasos
+   y cómo se verifica cada uno.
+3. **Test primero para bugs** — Al corregir un bug, escribir primero el test que
+   lo reproduce. Verificar que falla. Luego corregir. Verificar que pasa.
+
+### Plantillas de transformación
+
+| Instrucción vaga | Meta verificable |
+|---|---|
+| "Agregar validación" | Escribir tests de inputs inválidos → hacerlos pasar |
+| "Corregir el bug" | Escribir test que reproduce el bug → hacerlo pasar |
+| "Refactorizar X" | Tests existentes pasan antes Y después del cambio |
+| "Hacerlo más rápido" | Definir métrica (p95 latencia) + baseline + objetivo |
+| "Mejorar la autenticación" | Definir qué problema específico resolver primero |
+
+### Anti-patrón
+
+```markdown
+# MAL — plan vago sin verificación
+1. Revisar el sistema de autenticación
+2. Identificar problemas
+3. Implementar mejoras
+4. Probar
+
+# BIEN — meta concreta con verificación por paso
+Meta: las sesiones se invalidan al cambiar contraseña.
+1. Test: cambiar contraseña → sesión anterior rechazada (FAIL esperado)
+2. Implementar invalidación de sesiones en cambio de contraseña
+3. Verificar: test anterior PASA
+4. Verificar: login con nueva contraseña funciona (sin regresión)
+```
+
+## Resumen de señales de alerta
+
+| Señal | Problema | Acción |
+|---|---|---|
+| Se necesita "y" para describir el cambio | Múltiples cambios en uno | Dividir en commits separados |
+| Clase con 1 solo uso | Abstracción prematura | Reemplazar con función |
+| Parámetro `**kwargs` "por flexibilidad" | Feature fantasma | Parámetros explícitos |
+| `try/except` para error que nunca ocurre | Manejo defensivo excesivo | Eliminar |
+| Se modificaron archivos fuera del scope | Cambio no quirúrgico | Revertir extras |
+| "Aproveché para mejorar…" | Refactor de oportunidad | Commit separado o no hacerlo |
+| `if config.get("feature_x", False)` | Feature flag prematuro | Código directo |
+
+## Calibración: cuándo NO aplicar rigor completo
+
+Estos principios sesgan hacia cautela sobre velocidad. Para tareas triviales
+(fix de typo, one-liner obvio, rename de variable), usar criterio. No toda línea
+de código requiere análisis profundo. La simplicidad también aplica al proceso.
+
+## Cuándo NO cargar
+
+- El agente omite un paso obligatorio del proceso con una justificación — eso es racionalización, no sobre-ingeniería; cargar `prevencion-racionalizacion`.
+- La tarea es un fix de typo, rename de variable u otro one-liner obvio — el análisis completo de los 4 principios no compensa; el propio skill reconoce que "la simplicidad también aplica al proceso".
+- El objetivo es identificar complejidad acumulada en código heredado — ese análisis es parte de `mapear-codebase` (Paso 5: deuda técnica) o de una revisión de código; este skill previene sobre-ingeniería durante la implementación, no la audita después.
+- La abstracción ya tiene 3 o más casos de uso concretos identificados — el umbral del skill para justificar una abstracción es 3 usos; si ya se cumplen, diseñar la interfaz es correcto y este skill no agrega restricciones.
+
+## Gotchas / Errores comunes no obvios
+
+- **Test quirúrgico fallado porque el diff incluye cambios de formato automático del linter**: el agente revisa el diff antes del commit y ve líneas reformateadas por `black` o `prettier` que no estaban en el scope. Causa: el linter se ejecuta sobre archivos tocados y formatea líneas adyacentes al cambio real. Solución: distinguir entre cambios del agente y cambios del formateador automático — si el formateador era parte del flujo pre-commit, las líneas de formato no cuentan como cambios fuera del scope; si no era parte del flujo, revertir el formato y solo incluir el cambio mínimo.
+- **Principio de "no mejorar código adyacente" interpretado como prohibición de agregar type hints al código que se modifica**: el agente corrige un bug pero no actualiza el type hint del parámetro que cambió de tipo. Causa: generalizar la regla de "no tocar lo adyacente" a partes del código que sí deben actualizarse como parte del fix. Solución: la regla aplica a código que no necesita cambiar; un type hint incorrecto *después del cambio* es parte del fix, no una mejora de oportunidad.
+- **Principio 1 (clarificar antes de implementar) aplicado a tareas que ya tienen spec completa**: el agente pregunta por decisiones que ya están documentadas en el PLAN.md aprobado. Causa: no leer la spec antes de preguntar. Solución: el Principio 1 aplica cuando hay ambigüedad real después de leer el PLAN.md, CLAUDE.md y los archivos relevantes — si la respuesta está en los documentos ya leídos, preguntar es sobreingeniería del proceso, no clarificación.
+- **Criterio de 3 usos para abstracciones aplicado a tipos (interfaces/protocolos)**: el agente no crea una interfaz para un tipo que se usa en un solo lugar. Causa: confundir "3 usos para abstracciones de comportamiento" con "3 usos para tipos". Solución: el criterio de 3 usos aplica a factories, strategies, y patrones de comportamiento especulativos; una interfaz TypeScript o un Protocol Python que define un contrato usado una vez puede ser la solución correcta si el tipo es el boundary entre módulos.
+
+---
+
+## Variables residuales post-refactor son code smell
+
+### Regla
+
+Variables asignadas pero no usadas (F841 en ruff/flake8) **post-refactor** son
+casi siempre residuos de una versión anterior del código que el refactor no
+limpió. Se parecen a "variables temporales del desarrollador" pero delatan un
+refactor incompleto — la lógica que las usaba se movió o eliminó, pero las
+asignaciones quedaron.
+
+### Por qué son peligrosas
+
+- **Confunden al próximo lector**: asumirá que la variable se usa más abajo.
+- **Inflan el diff cognitivo** del refactor real.
+- **Ocultan bugs sutiles**: el valor asignado puede tener side effects (llamada
+  a función costosa o con efecto en estado) que ya no aporta nada al flujo.
+- **Invalidan la métrica de cobertura**: líneas "cubiertas" por tests que en
+  realidad no afectan el resultado.
+
+### Patrón operativo
+
+Después de **cualquier refactor** que modifique el flujo de una función (extraer
+método, inlinear función, cambiar el shape de un return), correr:
+
+```bash
+ruff check --select=F841 ruta/al/modulo.py
+# o para todo el proyecto
+ruff check --select=F841 .
+```
+
+Cada F841 detectado post-refactor es candidato 1 de 2:
+
+1. **Variable muerta** (caso común post-refactor): eliminarla.
+2. **Variable viva pero mal nombrada** (caso raro): si el valor se usa como
+   side effect intencional (ej: evaluar una propiedad para cachear), renombrar
+   con prefijo `_` y comentar el propósito.
+
+### Anti-patrón típico
+
+```python
+# Antes del refactor: había un if que usaba exito_key
+def procesar(data):
+    exito, exito_key = intentar(data)
+    if exito_key == "via_rapida":
+        return procesar_rapido(data)
+    return procesar_normal(data, exito_key)
+
+
+# Después de refactor que eliminó la rama "via_rapida"
+def procesar(data):
+    exito, exito_key = intentar(data)   # ← F841: exito_key asignado, no usado
+    return procesar_normal(data)         # ← también exito residual
+```
+
+### Patrón canónico
+
+```python
+# Post-refactor limpio
+def procesar(data):
+    _ = intentar(data)   # si el side effect de intentar() importa
+    return procesar_normal(data)
+
+# o mejor: si ni siquiera el side effect importa
+def procesar(data):
+    return procesar_normal(data)
+```
+
+### Reglas
+
+- **Gate pre-commit**: agregar `ruff check --select=F841` al pre-commit hook del proyecto. No bloquea en un repo grande donde F841 preexiste, pero sí bloquea en los archivos modificados por el commit actual.
+- **Revisión explícita post-refactor grande**: tras extraer 5+ métodos o mover 5+ bloques, correr `ruff --select=F401,F841` sobre los archivos tocados.
+- **NO silenciar con `# noqa: F841` sin justificación** — la excepción legítima (side effect intencional con nombre `_`) es tan rara que vale la pena documentarla; silenciar sin comentario es ocultar deuda.
+- **Incluir en checklist de PR**: "F841 limpio en archivos tocados" como item explícito.
+
+### Aplicabilidad
+
+Detectable en:
+
+- Python: `ruff --select=F841`, `flake8 --select=F841`.
+- TypeScript/JavaScript: `eslint --rule 'no-unused-vars: error'`.
+- Go: el compilador lo hace obligatorio (`declared but not used`).
+- Rust: warning `unused_variables`, promovido a error con `#![deny(unused_variables)]`.

package/habilidades/privacy-memoria/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: privacy-memoria
+description: >
+  Sistema de privacidad para la memoria SWL: tags <private>, filtrado de contenido
+  sensible, y mejores prácticas para proteger datos en aprendizajes y sesiones.
+  Cargar cuando se trabaje con datos sensibles, se configure el sistema de memoria
+  o se implementen componentes que lean/escriban APRENDIZAJES.md o session-store.
+herramientasPermitidas: [Read, Write]
+evolvable: false  # bloqueado por lista (skill de seguridad/privacidad)
+nist_csf: [GV.OV-01, PR.DS-01, PR.DS-02, DE.CM-09]
+nist_ai_rmf: [GOVERN-1.2, MAP-4.1, MANAGE-4.1]
+atlas_techniques: [AML.T0048]
+exclusiones:
+  - "No cargar para privacidad en esquemas de base de datos (columnas cifradas, tokenización, GDPR en modelos) — para diseño de privacidad en persistencia cargar `postgresql-experto` o `dbml-experto`."
+  - "No cargar para cumplimiento regulatorio formal (GDPR, HIPAA, LFPDPPP) — la evaluación regulatoria requiere `threat-model-lite` combinado con asesoría legal externa, no tags de memoria."
+  - "No cargar para cifrado en tránsito (TLS, mTLS, cifrado de payloads entre servicios) o gestión de claves — para transporte cifrado y rotación de credenciales cargar `iam-secretos`."
+  - "No cargar para escaneo de credenciales hardcodeadas en código fuente — para secretos en source cargar `checklist-seguridad` y el hook `escaneo-secretos`; los tags `<private>` no sustituyen la detección estática."
+---
+# Privacy Tags y Filtrado de Memoria
+
+## Cuándo cargar
+
+- Implementar o modificar hooks que lean/escriban `APRENDIZAJES.md`
+- Configurar `session-store.js` o `inyeccion-contexto.js`
+- Trabajar con datos que puedan contener PII, credenciales o información confidencial
+- Revisar que aprendizajes capturados no filtren información privada
+
+## Cuándo NO cargar
+
+- El diseño es de privacidad a nivel de base de datos (columnas cifradas, tokenización, políticas de retención en tablas): cargar `postgresql-experto` o `dbml-experto`. Los tags `<private>` operan sobre la capa de memoria de agentes (APRENDIZAJES.md, session-store), no sobre datos en reposo en BD.
+- La tarea es cumplimiento regulatorio formal (GDPR, HIPAA, LFPDPPP): los tags son un mecanismo de higiene interna, no un control de cumplimiento. Cargar `threat-model-lite` y consultar asesoría legal externa para el marco regulatorio aplicable.
+- La necesidad es cifrado en tránsito o gestión de claves (TLS, rotación de tokens, mTLS entre servicios): cargar `iam-secretos`. Este skill no cubre transporte ni criptografía.
+- La búsqueda es de credenciales hardcodeadas en código fuente: los tags `<private>` no protegen código — cargar `checklist-seguridad` (A02) y confiar en el hook `escaneo-secretos`. Los tags son una capa de conveniencia para aprendizajes, no de seguridad real.
+
+---
+
+## Tags de privacidad disponibles
+
+Envuelve contenido sensible en cualquiera de estos tags para excluirlo del
+almacenamiento de aprendizajes y sesiones:
+
+```
+<private>contenido que no debe persistir</private>
+<secreto>credenciales temporales, tokens de API</secreto>
+<privado>datos personales, PII</privado>
+```
+
+Los tres tags son equivalentes en comportamiento. Usar el que sea más legible
+en el contexto: `<private>` en código predominantemente en inglés, `<secreto>`
+o `<privado>` en contextos en español.
+
+---
+
+## Donde aplica el filtrado
+
+El módulo `hooks/lib/privacy-filter.js` expone `filtrarPrivacidad()` y debe
+invocarse en estos puntos del pipeline antes de escribir a disco o memoria:
+
+| Componente | Punto de filtrado |
+|-----------|------------------|
+| `extraccion-aprendizajes.js` | Antes de escribir en `APRENDIZAJES.md` |
+| `inyeccion-contexto.js` | Antes de inyectar contexto en nueva sesión |
+| `session-store.js` | Antes de persistir el summary de sesión |
+
+Patrón de uso en hooks:
+
+```js
+const { filtrarPrivacidad, contieneTagsPrivados } = require('./lib/privacy-filter');
+
+// Antes de persistir
+const { textoFiltrado, tagsRemovidos } = filtrarPrivacidad(textoOriginal);
+if (tagsRemovidos > 0) {
+  // Opcional: loguear cuántos bloques privados se removieron
+}
+// Usar textoFiltrado en lugar de textoOriginal
+```
+
+---
+
+## Qué NO cubre este sistema
+
+- **Código fuente con credenciales**: usar `escaneo-secretos.js` (hook PreToolUse)
+- **Variables de entorno**: usar `escaneo-secretos.js` con patrones de `.env`
+- **Archivos binarios o imágenes con datos sensibles**: no hay soporte de tags en binarios
+- **Datos sensibles en rutas de archivos**: usar la regla `cloud-infra.md` para secretos en IaC
+
+---
+
+## Limite de seguridad (ReDoS prevention)
+
+El módulo tiene un límite de `MAX_TAGS = 100` tags por texto procesado. Si un
+texto supera ese límite, los tags restantes quedan sin procesar (no se filtran).
+
+Este límite previene ataques de denegación de servicio via texto con miles de
+tags anidados o mal formados. Para textos legítimos el límite no debería alcanzarse.
+
+---
+
+## Reglas obligatorias
+
+1. **Nunca depender solo de tags para seguridad de secretos reales.** Los tags
+   son una capa de conveniencia para aprendizajes; las credenciales de producción
+   van en variables de entorno o gestores de secretos.
+
+2. **Tags anidados no están soportados.** `<private><secreto>x</secreto></private>`
+   puede comportarse de forma inesperada. Usar un solo nivel de tag.
+
+3. **Tags malformados se ignoran silenciosamente.** `<private>texto sin cierre`
+   no se filtra. Verificar que el tag de cierre existe si el contenido es crítico.
+
+4. **El filtrado es case-sensitive en los tags.** `<PRIVATE>` no se filtra.
+   Siempre usar minúsculas: `<private>`, `<secreto>`, `<privado>`.
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Confiar en tags `<private>` para proteger credenciales reales de producción**: el filtrado se aplica solo en puntos específicos del pipeline de memoria (APRENDIZAJES.md, session-store, inyección de contexto) y no sustituye la gestión de secretos. Causa: los tags son una capa de conveniencia para aprendizajes, no un control de seguridad — un `DATABASE_URL` envuelto en `<secreto>` sigue estando en memoria del proceso y en logs intermedios. Solución: credenciales de producción van en variables de entorno o gestores de secretos (Vault, AWS Secrets Manager); los tags solo marcan contenido transitorio de sesión que no debe persistirse en aprendizajes.
+- **Asumir que el filtrado es automático**: escribir a APRENDIZAJES.md sin invocar `filtrarPrivacidad()` explícitamente deja tags sin procesar en el archivo persistido. Causa: el módulo `hooks/lib/privacy-filter.js` expone la función pero no intercepta escrituras — cada hook debe llamarla explícitamente antes de `fs.writeFileSync` o equivalente. Solución: antes de persistir cualquier texto que pueda contener tags, invocar `const { textoFiltrado } = filtrarPrivacidad(textoOriginal)` y usar `textoFiltrado`; revisar que los hooks listados en la tabla "Donde aplica el filtrado" invocan la función.
+- **Anidar tags esperando filtrado recursivo**: escribir `<private>contexto <secreto>token</secreto> mas contexto</private>` puede comportarse de forma inesperada, dejando el contenido anidado sin filtrar o rompiendo la estructura. Causa: los tags anidados no están soportados en el parser actual; procesar recursivamente expone el riesgo de parsing ambiguo. Solución: usar un solo nivel de tag por bloque; si hace falta marcar varios tipos de sensibilidad, separar en bloques independientes consecutivos.
+- **Usar mayúsculas en los tags**: `<PRIVATE>contenido</PRIVATE>` no se filtra y el contenido se persiste en claro. Causa: el filtrado es case-sensitive por diseño (evita costo de regex case-insensitive sobre textos largos). Solución: siempre minúsculas `<private>`, `<secreto>`, `<privado>`; si el tag debe aparecer en un contexto de plantilla en inglés que exige mayúsculas, cambiar el contexto, no el tag.
+- **Dejar tags malformados sin cierre**: `<private>texto sin cierre` se ignora silenciosamente y el contenido queda visible en el archivo persistido. Causa: el parser exige tag de cierre; contenido con apertura sin cierre se trata como texto literal, no como bloque privado. Solución: verificar siempre el tag de cierre antes de escribir contenido crítico; si se genera texto programáticamente, validar balance de tags antes de enviar a `filtrarPrivacidad()`.
+
+---
+
+## Anti-patrones
+
+```
+# MAL: usar tags para ocultar credenciales reales de producción
+DATABASE_URL=<secreto>postgresql://prod:realpassword@host/db</secreto>
+
+# MAL: tag anidado
+<private>contexto <secreto>token</secreto> mas contexto</private>
+
+# MAL: confiar en el filtrado si el hook no lo invoca explícitamente
+# (el filtrado NO es automático, requiere llamada explícita a filtrarPrivacidad())
+
+# BIEN: marcar información de sesión que no debe aprenderse
+Durante la sesión use <private>el token temporal X para la API de staging</private>
+El patrón que aprendí fue: siempre validar el schema antes de persistir.
+```