@saulwade/swl-ses 1.0.0

package/habilidades/seguridad-skills-ia/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: seguridad-skills-ia
+description: >
+  Verificación de seguridad para skills y plugins de IA antes de incorporarlos
+  al sistema. Detecta credenciales hardcodeadas, inyección de comandos/prompts,
+  exfiltración de datos, ejecución remota de código y abuso de autonomía.
+  Cargar cuando se crea un skill nuevo, se instala un plugin, o se audita
+  la seguridad de skills existentes.
+version: "1.0.1"
+herramientasPermitidas: [Read, Grep]
+evolvable: false  # bloqueado por lista (skill de seguridad/privacidad)
+nist_csf: [GV.SC-07, GV.OV-01, PR.PS-01, DE.CM-09]
+nist_ai_rmf: [GOVERN-1.1, GOVERN-1.2, MEASURE-2.5, MANAGE-2.4]
+atlas_techniques: [AML.T0010, AML.T0018, AML.T0051, AML.T0054, AML.T0080]
+attack_techniques: [T1195]
+exclusiones:
+  - "No cargar para revisión de seguridad de código de aplicación (inyección SQL, XSS, auth, OWASP Top 10 sobre código de negocio) — para seguridad de código fuente cargar `checklist-seguridad`. Este skill cubre SKILL.md y scripts de skills, no código de aplicación."
+  - "No cargar para auditoría de dependencias del proyecto (CVEs en paquetes npm/pip, licencias) — para vulnerabilidades en librerías cargar `dependencias-auditoria`."
+  - "No cargar para IAM, gestión de secretos o rotación de credenciales de infraestructura — para secretos y credenciales cargar `iam-secretos`."
+  - "No cargar si el artefacto objetivo no ejecuta LLM ni consume prompts externos (hooks deterministas, scripts de formateo, utilidades sin razonamiento) — los patrones de prompt injection y abuso de autonomía no aplican a código sin modelo."
+---
+# Verificación de Seguridad para Skills de IA
+
+Skill derivado del análisis de SkillWard (escáner de seguridad de skills) y adaptado
+para el ecosistema SWL. Provee patrones de detección de amenazas específicos para
+archivos SKILL.md y scripts asociados.
+
+## Cuándo cargar
+
+- Al ejecutar `/swl:crear-skill` — verificación pre-creación
+- Al ejecutar `/swl:plugins install` — gate de seguridad
+- Al auditar skills existentes con `/swl:salud`
+- Al revisar skills generados por `auto-evolucion-swl`
+- Cuando se incorporan skills de `_userland/plugins/` al sistema base
+
+## Cuándo NO cargar
+
+- La revisión es de seguridad sobre código de aplicación (endpoints, auth, inyección, OWASP): cargar `checklist-seguridad`. Este skill audita artefactos SKILL.md y scripts de skills — el boundary es "código que define o guía a un agente", no código de negocio.
+- La auditoría es de dependencias de software (CVEs en npm/pip, licencias, versiones pinned): cargar `dependencias-auditoria`. Los patrones de este skill apuntan a amenazas autorales de skills, no a vulnerabilidades de librerías upstream.
+- La gestión es de IAM, secretos en infraestructura, rotación de tokens o credenciales de servicios externos: cargar `iam-secretos`. Este skill detecta credenciales hardcodeadas en skills, no diseña la capa de secretos.
+- El artefacto objetivo no ejecuta LLM ni consume prompts externos: las categorías 3 (inyección de prompts), 5 (abuso de autonomía) y 6 (inflación de capacidades) no aplican a código determinista sin modelo. En la duda — si el artefacto invoca a un subagente, lee contenido externo, o alimenta un prompt — cargar este skill.
+
+## Modelo de severidad
+
+| Nivel | Significado | Acción |
+|-------|-------------|--------|
+| CRITICO | Amenaza inminente, explotable | Bloquear inmediatamente |
+| ALTO | Amenaza seria, alta probabilidad | Bloquear, requiere revisión humana |
+| MEDIO | Amenaza moderada, depende del contexto | Advertir, pedir confirmación |
+| BAJO | Amenaza baja, mitigable | Advertir en reporte |
+| INFO | Informativo, no es amenaza | Solo registrar |
+
+## Categorías de amenazas
+
+### 1. Credenciales hardcodeadas (CRITICO)
+
+Detectar en scripts/ y SKILL.md:
+
+```
+# Patrones de API keys conocidas
+AKIA[0-9A-Z]{16}                              → AWS Access Key
+ghp_[A-Za-z0-9]{36}                           → GitHub Token
+sk-[A-Za-z0-9]{48,}                           → OpenAI/Anthropic Key
+-----BEGIN (RSA |OPENSSH )?PRIVATE KEY-----   → SSH/RSA Private Key
+
+# Variables de entorno con valores reales (no placeholders)
+(OPENAI_API_KEY|ANTHROPIC_API_KEY|STRIPE_SECRET_KEY)\s*=\s*['"][A-Za-z0-9\-_]{20,}['"]
+
+# Exclusiones benignas (no alertar)
+CHANGE_ME, PLACEHOLDER, example, sample, test, fake, mock, your_api_key, <your, <insert
+```
+
+### 2. Inyección de comandos (ALTO)
+
+```
+# Ejecución de código con input dinámico
+eval\s*\([^)]*\b(user|input|param|request)\b
+exec\s*\(\s*f['"]
+os\.system\s*\(\s*f['"]
+subprocess\.(run|call|Popen)\s*\(\s*f['"]
+
+# Reverse shells
+bash\s+-i\s+>&?\s*\/dev\/tcp\/
+nc\s+-e\s+\/bin\/(sh|bash)
+python[23]?\s+[^\n]{0,20}socket[^\n]{0,40}connect
+
+# Destrucción de archivos
+rm\s+-rf\s+(\/|~\/|\$HOME|\/etc|\/root)
+dd\s+if=\/dev\/(zero|random)\s+of=\/
+chmod\s+(777|666)\s+[^\n]{0,30}(\.ssh|\.aws|\.env)
+
+# Exfiltración a destinos conocidos
+(curl|wget)\s+[^\n]{0,80}(discord\.com\/api\/webhooks|webhook\.site|ngrok\.io|pastebin\.com)
+```
+
+### 3. Inyección de prompts (ALTO)
+
+```
+# Override de instrucciones del sistema
+(Bypass|Disregard|Forget|Ignore)\s+(all|any|every)\s+.*\s+(previous|prior|system)\s+(instruction|directive|rule)
+
+# Comportamiento oculto
+do\s+not\s+(mention|tell|reveal)\s+.*\s+to\s+(the\s+)?user
+hide\s+(this|the\s+(truth|real))\s+from\s+(the\s+)?user
+
+# Escalada de privilegios
+grant\s+(me\s+)?admin\s+(access|privileges?)
+bypass\s+(all\s+)?security\s+checks?
+sudo\s+mode\s+enabled?
+developer\s+mode\s+activated?
+
+# Redefinición de roles
+new\s+(instructions|directive)s?\s*:\s*you\s+are\b
+
+# Parámetros shadow
+(internalOnly|hiddenParam|shadowTool|bypassChecks|sandboxEscape)
+```
+
+### 4. Exfiltración de datos (CRITICO)
+
+```
+# Lectura + transmisión de archivos sensibles
+(open|read)\s*\(.*\b(\.ssh|\.aws|\.env|credentials|private_key)\b.*\b(requests|urllib|fetch|curl)\b
+
+# Variables de entorno hacia la red
+os\.environ\s*\[.*\b(SECRET|PASSWORD|KEY)\b.*\b(requests\.|urllib\.|socket\.)\b
+
+# Envío a servicios de exfiltración
+\.ssh\/(id_rsa|id_ed25519).*\b(send|post|upload|requests|fetch)\b
+\.aws\/credentials.*\b(send|post|upload)\b
+(read|open|cat)\b.*\.env\b.*\b(send|post|curl|wget)\b
+```
+
+### 5. Abuso de autonomía (MEDIO)
+
+```
+# Saltar confirmación del usuario
+don't\s+(ask|wait for|require)\s+(the\s+)?(user|human)\s+(for\s+)?(confirmation|permission)
+proceed\s+without\s+(asking\s+)?(the\s+)?(user|human)
+
+# Override de decisiones
+ignore\s+(user|human)\s+(input|decision|choice)
+override\s+(user|human)\s+(decision|preference)
+
+# Auto-modificación
+modify\s+(my own|this skill's|its own)\s+(code|behavior|instructions?)
+rewrite\s+(myself|itself|this skill)
+
+# Reintentos infinitos
+retry\s+(indefinitely|forever|until success)
+never\s+(stop|give up)\s+(trying|retrying)
+
+# Supresión de errores
+suppress\s+all\s+(errors?|exceptions?)
+ignore\s+(every|all)\s+(error|exception|failure)
+```
+
+### 6. Inflación de capacidades (MEDIO)
+
+```
+# Reclamaciones sobre-amplias
+can\s+do\s+(anything|everything)
+always\s+use\s+(this|me)\s+(first|instead)
+default\s+(tool|skill)\s+for\s+(all|every|any)
+priority\s+over\s+(all|every|other)\s+(tools?|skills?)
+
+# Suplantación certificada (fraude)
+(verified|certified|approved|endorsed)\s+by\s+(anthropic|openai|google|claude)
+
+# Overpromising
+100%\s+(safe|secure|accurate|reliable)
+guaranteed\s+to\s+(never|always)
+never\s+(fails|errors|crashes)
+
+# Triggers ocultos
+(secret\s+(command|keyword)|hidden\s+(feature|mode)|backdoor\s+(access|entry))
+```
+
+### 7. Esteganografía Unicode (MEDIO)
+
+Detectar caracteres invisibles usados para ocultar instrucciones:
+
+```
+# Zero-width characters (>50 en un archivo = sospechoso)
+U+200B (ZERO WIDTH SPACE)
+U+200C (ZERO WIDTH NON-JOINER)
+U+200D (ZERO WIDTH JOINER)
+
+# Overrides direccionales (siempre sospechosos)
+U+202E (RIGHT-TO-LEFT OVERRIDE)
+U+202D (LEFT-TO-RIGHT OVERRIDE)
+
+# Unicode Tags encoded
+\u[Ee]00[0-7][0-9A-Fa-f]
+```
+
+## Protocolo de verificación
+
+### Paso 1 — Análisis estático del SKILL.md
+
+1. Leer el contenido completo del SKILL.md
+2. Verificar frontmatter YAML contra `reglas/skills-estandar.md`
+3. Buscar patrones de las 7 categorías en la descripción e instrucciones
+4. Verificar que los permisos declarados sean coherentes con el contenido
+
+### Paso 2 — Análisis de scripts/
+
+1. Listar todos los archivos en `scripts/` del skill
+2. Aplicar patrones de categorías 1-4 (código ejecutable)
+3. Verificar que no hay archivos ocultos (dotfiles, extensiones dobles)
+4. Verificar que los scripts solo hacen lo que el SKILL.md describe
+
+### Paso 3 — Análisis de coherencia permisos↔comportamiento
+
+Verificar discrepancias:
+- Skill dice "solo lectura" pero scripts ejecutan comandos de escritura
+- Skill dice "sin red" pero scripts hacen requests HTTP
+- Skill dice "sin acceso a filesystem" pero scripts leen archivos del sistema
+
+### Paso 4 — Emisión de veredicto
+
+```
+SEGURO:     Score ≥ 9.0, sin hallazgos CRITICO ni ALTO
+SOSPECHOSO: Score 5.0-8.9, hallazgos MEDIO o discrepancias de permisos
+INSEGURO:   Score < 5.0, hallazgos CRITICO o ALTO confirmados
+```
+
+## Formato de reporte
+
+```markdown
+## Verificación de seguridad — [nombre-skill]
+
+**Fecha**: YYYY-MM-DD
+**Veredicto**: SEGURO | SOSPECHOSO | INSEGURO
+**Score**: N.N/10.0
+
+### Hallazgos
+
+| # | Categoría | Severidad | Archivo:Línea | Detalle |
+|---|-----------|-----------|---------------|---------|
+| 1 | Credencial | CRITICO | scripts/init.py:23 | AWS Key hardcodeada |
+
+### Recomendaciones
+- [Lista de acciones correctivas]
+```
+
+## Gotchas / Errores comunes no obvios
+
+- **Tratar la lista de patrones de detección como exhaustiva**: las 7 categorías documentadas son el piso, no el techo — un skill malicioso puede usar variantes no listadas (ej: ofuscación con sinónimos, encoding base64, división de strings). Causa: publicar patrones exactos en este SKILL.md permite a autores hostiles evadirlos reescribiendo; el análisis debe incluir juicio contextual sobre coherencia permisos↔comportamiento además del grep de patrones. Solución: tras aplicar los patrones de las 7 categorías, ejecutar siempre el Paso 3 (coherencia permisos↔comportamiento) y escalar a `revisor-seguridad-swl` cualquier skill donde la discrepancia entre lo declarado y lo implementado sea no trivial.
+- **Aprobar skills con hallazgos CRITICO porque "el contexto parece benigno"**: un reverse shell, una credencial hardcodeada o una exfiltración documentada se aprueban por inercia si aparecen en un skill "conocido" o "de confianza". Causa: los patrones CRITICO se detectan precisamente porque no admiten excusa contextual — el análisis estático no puede verificar runtime intent. Solución: NUNCA aprobar un skill con hallazgo CRITICO sin revisión humana explícita registrada en `.planning/AUDITORIA.md`; el operador humano asume el riesgo por escrito.
+- **Aplicar exclusiones benignas (test, example, mock) fuera de contexto de pruebas**: marcar como falso positivo una credencial real porque el string `test` aparece en el mismo archivo aprueba skills inseguros. Causa: las exclusiones benignas solo aplican cuando el archivo está claramente en contexto de documentación o pruebas (path `tests/`, nombre `example.*`, bloques marcados como ejemplo); aplicarlas globalmente neutraliza la detección. Solución: verificar la ruta y el propósito del archivo antes de aplicar exclusión; una credencial en `scripts/init.py` no se excluye aunque contenga la palabra `example` en un comentario adyacente.
+- **Confiar en que "sin red" en frontmatter garantiza ausencia de requests**: aprobar un skill porque declara `permisosRed: false` sin validar los scripts asociados produce falsos negativos. Causa: el frontmatter es declaración, no enforcement — un script del skill puede invocar `curl`, `requests` o `fetch` aunque el skill diga que no usa red. Solución: ejecutar siempre el Paso 3 del protocolo (análisis de coherencia) buscando patrones de red en `scripts/`; si hay discrepancia entre lo declarado y lo observado, marcar SOSPECHOSO sin importar el score.
+- **Omitir la esteganografía Unicode en SKILL.md en español**: asumir que los caracteres invisibles solo aparecen en skills de autores hostiles en inglés produce ceguera frente a inyecciones ocultas en texto aparentemente legítimo en español. Causa: los caracteres zero-width y overrides direccionales son agnósticos del idioma natural del archivo; un skill en es-MX puede contenerlos igual de fácil. Solución: ejecutar la detección de categoría 7 sobre todos los SKILL.md sin importar idioma; más de 50 zero-width en un archivo es sospechoso por definición, y U+202D/U+202E siempre lo son.
+
+## Reglas de comportamiento
+
+- NUNCA aprobar un skill con hallazgos CRITICO sin revisión humana explícita.
+- NUNCA ignorar patrones de exfiltración aunque parezcan benignos.
+- Los patrones de exclusión (test, example, mock) solo aplican si el archivo
+  está claramente en contexto de documentación o pruebas.
+- Registrar toda verificación en `.planning/AUDITORIA.md`.
+- Este skill complementa pero NO reemplaza `revisor-seguridad-swl`.

package/habilidades/sql-optimizacion/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: sql-optimizacion
+description: Optimización SQL. Índices, EXPLAIN ANALYZE, problema N+1, query planning, particionamiento de tablas, materialización de vistas y patrones de queries eficientes.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para diseño inicial de esquema de base de datos (entidades, relaciones, normalización) — ese es el dominio de `postgresql-experto` o `dbml-experto`; este skill asume que el esquema ya existe y necesita optimización."
+  - "No cargar para migrar queries entre ORM diferentes (SQLAlchemy ↔ Django ORM) — las semánticas son distintas; cargar `fastapi-experto` o `django-experto` según el ORM del proyecto."
+  - "No cargar para problemas de conexión a base de datos, autenticación o configuración de PostgreSQL — esos son problemas de infraestructura de BD, no de optimización de queries."
+  - "No cargar cuando el problema de rendimiento está en la lógica de aplicación (bucles en Python, serialización Pydantic) y no en las queries SQL — usar profiling de la aplicación antes de optimizar SQL."
+evolvable: true  # default para skill estandar
+---
+# Optimización SQL
+
+## Cuándo NO cargar
+
+- El esquema de BD no existe todavía y la tarea es diseñarlo — cargar `postgresql-experto` o `dbml-experto`.
+- El ORM está generando queries y la tarea es entender cómo el ORM específico las genera — cargar `fastapi-experto` o `django-experto`.
+- El problema de lentitud está en el código de aplicación, no en las queries — profiling primero, SQL después.
+
+## Proceso de optimización
+
+No optimices a ciegas. Siempre:
+1. **Identificar** el query lento (logs, pg_stat_statements).
+2. **Medir** con EXPLAIN ANALYZE antes de cambiar nada.
+3. **Hipótesis** sobre la causa (falta de índice, seq scan, join ineficiente).
+4. **Cambiar** una cosa a la vez.
+5. **Medir de nuevo** para confirmar la mejora.
+
+---
+
+## EXPLAIN ANALYZE — leer el plan de ejecución
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+SELECT f.id, f.folio, c.nombre
+FROM facturas f
+JOIN clientes c ON f.cliente_id = c.id
+WHERE f.estatus = 'emitida'
+  AND f.fecha >= '2026-01-01'
+ORDER BY f.fecha DESC
+LIMIT 50;
+```
+
+### Cómo leer el plan
+
+- **cost=inicio..total**: estimación del planificador (ignorar valores absolutos).
+- **actual time=inicio..total**: tiempo real en milisegundos.
+- **rows**: filas procesadas.
+- **Buffers: shared hit=N read=M**: N páginas desde cache, M desde disco.
+- **Seq Scan**: señal de índice faltante.
+- **Rows Removed by Filter**: filas descartadas — oportunidad de índice.
+
+---
+
+## Índices
+
+### Tipos de índices en PostgreSQL
+
+```sql
+-- B-Tree (default): igualdad, rangos, ORDER BY
+CREATE INDEX idx_facturas_fecha ON facturas(fecha);
+CREATE INDEX idx_facturas_cliente_fecha ON facturas(cliente_id, fecha DESC);
+
+-- Parcial: solo indexa un subconjunto (más pequeño y rápido)
+CREATE INDEX idx_facturas_pendientes ON facturas(fecha)
+WHERE estatus IN ('borrador', 'pendiente');
+
+-- Funcional: indexa resultado de función
+CREATE INDEX idx_clientes_nombre_lower ON clientes(lower(nombre));
+
+-- GIN: para arrays, JSONB y búsqueda de texto completo
+CREATE INDEX idx_productos_etiquetas ON productos USING GIN(etiquetas);
+
+-- GiST: para geometría, rangos, pg_trgm
+CREATE INDEX idx_productos_nombre_trgm ON productos
+USING GiST(nombre gist_trgm_ops);
+```
+
+### Cuándo crear un índice
+
+**Crear** cuando: columna frecuente en WHERE/JOIN/ORDER BY, cardinalidad alta, tabla >10k filas, lecturas > escrituras.
+
+**No crear** cuando: tabla pequeña, cardinalidad baja (booleano), columna con updates constantes.
+
+### Índices compuestos: el orden importa
+
+```sql
+-- Índice en (empresa_id, estatus, fecha) puede usarse para:
+-- WHERE empresa_id = ?                                    OK
+-- WHERE empresa_id = ? AND estatus = ?                    OK
+-- WHERE empresa_id = ? AND estatus = ? AND fecha > ?      OK
+-- WHERE estatus = ?                                       NO (no empieza con primera columna)
+```
+
+---
+
+## Problema N+1
+
+```python
+# MAL: N+1 en SQLAlchemy
+facturas = session.execute(select(Factura)).scalars().all()
+for factura in facturas:
+    print(factura.cliente.nombre)  # 1 SELECT por factura
+
+# BIEN: eager loading con selectinload
+facturas = session.execute(
+    select(Factura).options(selectinload(Factura.cliente))
+).scalars().all()
+```
+
+### Detectar N+1 en tests
+
+```python
+def test_lista_facturas_no_genera_n_mas_1(db):
+    with count_queries() as contador:
+        facturas = obtener_facturas_con_clientes(db)
+        _ = [f.cliente.nombre for f in facturas]
+    assert contador.count <= 2  # Máximo 2: facturas + clientes
+```
+
+---
+
+## CTEs, Window Functions, Particionamiento y Vistas materializadas
+
+Para ejemplos completos de CTEs (incluyendo recursivos), window functions (RANK, LAG, acumulados), particionamiento por rango de fecha y vistas materializadas con refresh concurrente, ver [recursos/patrones-sql-avanzados.md](recursos/patrones-sql-avanzados.md).
+
+---
+
+## Anti-patrones SQL
+
+```sql
+-- MAL: SELECT * en producción
+SELECT * FROM facturas WHERE empresa_id = ?;
+-- BIEN: seleccionar solo lo necesario
+SELECT id, folio, fecha, monto_total, estatus FROM facturas WHERE empresa_id = ?;
+
+-- MAL: función en WHERE impide uso de índice
+WHERE YEAR(fecha) = 2026
+-- BIEN: rango que usa el índice
+WHERE fecha >= '2026-01-01' AND fecha < '2027-01-01'
+
+-- MAL: OR con columnas distintas (difícil de indexar)
+WHERE empresa_id = ? OR cliente_id = ?
+-- BIEN: UNION ALL (cada parte usa su índice)
+SELECT id FROM facturas WHERE empresa_id = ?
+UNION ALL
+SELECT id FROM facturas WHERE cliente_id = ?
+
+-- MAL: LIKE con wildcard al inicio (no usa B-tree)
+WHERE nombre LIKE '%acme%'
+-- BIEN: pg_trgm o full text search
+WHERE nombre ILIKE '%acme%' -- con índice GiST/pg_trgm
+```
+
+---
+
+## Gotcha: SQL en contextos de agentes y MCP servers
+
+Cuando un agente o MCP server ejecuta SQL dinámico (queries construidas por IA,
+herramientas de exploración de datos, interfaces NL-to-SQL), aplicar protección
+de solo lectura obligatoria:
+
+### Defensa en profundidad (3 capas)
+
+```python
+# Capa 1: Regex de rechazo — bloquear mutaciones antes de enviar al servidor
+import re
+PATRON_MUTACION = re.compile(
+    r'\b(INSERT|UPDATE|DELETE|DROP|ALTER|TRUNCATE|CREATE|GRANT|REVOKE)\b',
+    re.IGNORECASE
+)
+if PATRON_MUTACION.search(query):
+    raise ValueError(f"Query de mutación bloqueada: {query[:100]}")
+
+# Capa 2: Transacción read-only — el servidor rechaza mutaciones escapadas
+async with conexion.begin() as txn:
+    await conexion.execute(text("SET TRANSACTION READ ONLY"))
+    resultado = await conexion.execute(text(query))
+
+# Capa 3: Timeout — limitar queries costosas de agentes
+# statement_timeout protege contra queries que escanean toda la tabla
+await conexion.execute(text("SET statement_timeout = '30s'"))
+```
+
+### Por qué las 3 capas
+
+- Solo regex: un `SELECT ... INTO` o CTE con `DELETE` podría escapar.
+- Solo `READ ONLY`: la query llega al servidor, consume recursos antes de fallar.
+- Solo timeout: permite mutaciones lentas que corrompen datos.
+
+Las 3 capas juntas dan protección robusta para ejecución de SQL no confiable.
+
+## Gotchas / Errores comunes no obvios
+
+- **`CREATE INDEX` en tabla con millones de filas bloquea escrituras hasta que el índice termina**: el `CREATE INDEX` por defecto adquiere un `ShareLock` sobre la tabla completa, bloqueando INSERTs, UPDATEs y DELETEs durante la construcción. Causa: sin `CONCURRENTLY`, PostgreSQL construye el índice en una sola transacción con lock. Solución: usar `CREATE INDEX CONCURRENTLY nombre_idx ON tabla(columna)` — tarda el doble pero no bloquea escrituras; no se puede usar dentro de una transacción explícita.
+- **`EXPLAIN` muestra Seq Scan aunque existe el índice correcto**: el planner de PostgreSQL elige Seq Scan cuando estima que retornará más del ~10-15% de las filas de la tabla. Causa: si la columna indexada tiene baja selectividad (ej: un campo booleano con 50/50 distribución), el Seq Scan es más eficiente que usar el índice. Solución: verificar con `EXPLAIN (ANALYZE, BUFFERS)` si el Seq Scan es realmente lento — si la tabla cabe en memoria (`shared_hit` alto), el Seq Scan puede ser genuinamente más rápido que el índice.
+- **Índice compuesto `(a, b)` no se usa en query que filtra solo por `b`**: los índices compuestos en PostgreSQL solo se usan si la query incluye el prefijo del índice. Causa: el índice `(a, b)` es equivalente a tener una guía telefónica ordenada por apellido+nombre — buscar solo por nombre no aprovecha el orden. Solución: crear un índice separado en `(b)` si se necesita filtrar por `b` solo, o reorganizar el índice compuesto con la columna más selectiva primero.
+- **Query con `LIMIT 50` es lenta aunque hay índice**: la query tiene un `ORDER BY` en una columna diferente a la columna indexada, forzando un sort de todos los resultados antes del LIMIT. Causa: PostgreSQL necesita ordenar todos los rows que cumplen el WHERE antes de aplicar el LIMIT — el índice ayuda al filtro pero no al sort. Solución: crear un índice que incluya tanto la columna del WHERE como la columna del ORDER BY: `CREATE INDEX ON tabla(columna_where, columna_orderby DESC)`.
+- **Columna derivada de función determinista NO es fuente de verdad para comparaciones — es caché**: persistir `nombre_normalizado` y usar `WHERE nombre_normalizado = :n` para deduplicación crea bug latente; cuando se mejora la función de normalización, los valores almacenados quedan stale hasta backfill. Causa: se trata el resultado cacheado como si fuera invariante, pero la función que lo produce puede evolucionar. Solución: dos caminos válidos (no mezclar): (1) **Re-cómputo on-the-fly** — cargar candidatos por scope acotado y aplicar la función en la capa de aplicación al vuelo; funciona con cualquier versión de la función. (2) **Backfill automático con migración** — al cambiar la función, generar migración que re-normalice todas las filas y resuelva colisiones con sufijo `-DUPE-{id}` para revisión manual. La función canónica es la única fuente de verdad — la columna cache es optimización opcional, no contrato.

package/habilidades/sql-optimizacion/evals/evals.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "sql-optimizacion",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para sql-optimizacion — indexes, EXPLAIN, JOINs, evitar N+1.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Query `SELECT * FROM users WHERE email = $1` es lento en 100K filas. ¿Primer fix?",
+      "files": [],
+      "expectations": [
+        "Crear índice `CREATE INDEX ON users (email)`.",
+        "La respuesta menciona que sin índice el query hace seq scan.",
+        "La respuesta sugiere validar con `EXPLAIN ANALYZE` antes y después."
+      ],
+      "tags": ["indexing"]
+    },
+    {
+      "id": "n-plus-one",
+      "prompt": "En una API GET /orders, cada orden hace un SELECT al cliente. 100 órdenes = 101 queries. ¿Cómo lo arreglo?",
+      "files": [],
+      "expectations": [
+        "La respuesta identifica N+1.",
+        "La respuesta da la solución: JOIN eager o eager-loading del ORM (selectinload/joinedload/include).",
+        "La respuesta recomienda medir con query count en tests."
+      ],
+      "grading_guidance": "Failure si no identifica N+1.",
+      "tags": ["anti-pattern"],
+      "weight": 1.5
+    },
+    {
+      "id": "explain-read",
+      "prompt": "¿Qué campo de `EXPLAIN ANALYZE` revela el costo real vs estimado?",
+      "files": [],
+      "expectations": [
+        "`actual time` (vs `cost` estimado).",
+        "Menciona que divergencia grande entre `estimated rows` y `actual rows` indica estadísticas desactualizadas (ANALYZE)."
+      ],
+      "tags": ["explain"]
+    },
+    {
+      "id": "anti-select-star",
+      "prompt": "El equipo usa `SELECT *` en APIs públicas. ¿Está bien?",
+      "files": [],
+      "expectations": [
+        "La respuesta indica que NO.",
+        "Riesgos: overhead de red/serialización, dependencia implícita del schema, exposición de columnas nuevas sin control.",
+        "Solución: seleccionar columnas explícitas."
+      ],
+      "tags": ["anti-pattern"]
+    }
+  ]
+}

package/habilidades/sql-optimizacion/recursos/patrones-sql-avanzados.md

@@ -0,0 +1,131 @@
+# Optimización SQL — Patrones avanzados
+
+## CTEs (Common Table Expressions)
+
+```sql
+-- Mejorar legibilidad de queries complejos
+WITH facturas_vencidas AS (
+    SELECT id, cliente_id, monto_total, fecha_vencimiento
+    FROM facturas
+    WHERE estatus = 'emitida'
+      AND fecha_vencimiento < CURRENT_DATE
+),
+clientes_deudores AS (
+    SELECT
+        cliente_id,
+        COUNT(*) AS num_facturas_vencidas,
+        SUM(monto_total) AS total_deuda
+    FROM facturas_vencidas
+    GROUP BY cliente_id
+    HAVING SUM(monto_total) > 10000
+)
+SELECT
+    c.nombre,
+    c.email,
+    cd.num_facturas_vencidas,
+    cd.total_deuda
+FROM clientes_deudores cd
+JOIN clientes c ON c.id = cd.cliente_id
+ORDER BY cd.total_deuda DESC;
+
+-- CTE recursivo para jerarquías
+WITH RECURSIVE categoria_arbol AS (
+    -- Base: categorías raíz
+    SELECT id, nombre, padre_id, 0 AS nivel
+    FROM categorias
+    WHERE padre_id IS NULL
+
+    UNION ALL
+
+    -- Recursión: hijos
+    SELECT c.id, c.nombre, c.padre_id, ca.nivel + 1
+    FROM categorias c
+    JOIN categoria_arbol ca ON c.padre_id = ca.id
+)
+SELECT * FROM categoria_arbol ORDER BY nivel, nombre;
+```
+
+---
+
+## Window Functions
+
+```sql
+-- Ranking de facturas por cliente
+SELECT
+    f.id,
+    f.folio,
+    c.nombre AS cliente,
+    f.monto_total,
+    RANK() OVER (
+        PARTITION BY f.cliente_id
+        ORDER BY f.monto_total DESC
+    ) AS rank_por_monto,
+    SUM(f.monto_total) OVER (
+        PARTITION BY f.cliente_id
+        ORDER BY f.fecha
+        ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+    ) AS acumulado_cliente
+FROM facturas f
+JOIN clientes c ON f.cliente_id = c.id
+WHERE f.estatus = 'emitida';
+
+-- Funciones de ventana más útiles:
+-- ROW_NUMBER() — número de fila sin empates
+-- RANK()       — ranking con huecos en empates
+-- DENSE_RANK() — ranking sin huecos
+-- LAG(col, n)  — valor de n filas anteriores
+-- LEAD(col, n) — valor de n filas siguientes
+-- FIRST_VALUE(col) / LAST_VALUE(col) — primer/último valor en la ventana
+```
+
+---
+
+## Particionamiento de tablas
+
+```sql
+-- Particionar tabla grande por rango de fecha
+CREATE TABLE facturas (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    fecha DATE NOT NULL,
+    empresa_id UUID NOT NULL,
+    monto_total DECIMAL(12,2),
+    estatus TEXT
+) PARTITION BY RANGE (fecha);
+
+-- Crear particiones por año/trimestre
+CREATE TABLE facturas_2025 PARTITION OF facturas
+    FOR VALUES FROM ('2025-01-01') TO ('2026-01-01');
+
+CREATE TABLE facturas_2026 PARTITION OF facturas
+    FOR VALUES FROM ('2026-01-01') TO ('2027-01-01');
+
+-- Índices en partición — se heredan automáticamente en PostgreSQL 11+
+CREATE INDEX ON facturas(empresa_id, fecha);
+```
+
+---
+
+## Vistas materializadas
+
+```sql
+-- Vista materializada para reportes costosos
+CREATE MATERIALIZED VIEW resumen_ventas_mensuales AS
+SELECT
+    DATE_TRUNC('month', f.fecha) AS mes,
+    e.nombre AS empresa,
+    COUNT(*) AS total_facturas,
+    SUM(f.monto_total) AS total_ventas,
+    AVG(f.monto_total) AS promedio_factura
+FROM facturas f
+JOIN empresas e ON f.empresa_id = e.id
+WHERE f.estatus = 'emitida'
+GROUP BY DATE_TRUNC('month', f.fecha), e.nombre
+ORDER BY mes DESC, total_ventas DESC;
+
+-- Índice en la vista materializada
+CREATE UNIQUE INDEX ON resumen_ventas_mensuales(mes, empresa);
+
+-- Refrescar (puede ser automático con pg_cron)
+REFRESH MATERIALIZED VIEW CONCURRENTLY resumen_ventas_mensuales;
+-- CONCURRENTLY no bloquea lecturas durante el refresh
+```