@saulwade/swl-ses 1.0.0

package/habilidades/planear-fase/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: planear-fase
+description: Crea el PLAN.md ejecutable para una fase de desarrollo. Descompone la fase en tareas atómicas con dependencias explícitas, las agrupa en oleadas de ejecución paralela cuando es posible, y aplica verificación goal-backward para garantizar que el plan completo satisface los criterios de éxito definidos en CONTEXTO.md.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar si no existe CONTEXTO.md para la fase — ejecutar `discutir-fase` primero."
+  - "No cargar para replanificar una tarea individual dentro de una fase ya en ejecución; eso es desviación moderada, manejar con `ejecutar-fase`."
+  - "No cargar para generar backlog de producto o roadmap de alto nivel; usar `nuevo-proyecto` o conversar directamente con el usuario."
+  - "No cargar si el usuario pide 'ajustar' el PLAN.md ya aprobado sin nueva información — cada modificación al plan aprobado debe pasar por discusión primero."
+evolvable: true  # default para skill estandar
+---
+# Habilidad: Planear Fase de Desarrollo
+
+## Propósito
+
+Un plan ejecutable no es una lista de tareas — es un grafo de dependencias con
+criterios de verificación por tarea. Esta habilidad transforma el CONTEXTO.md de
+una fase en un PLAN.md que el agente ejecutor puede seguir sin ambigüedad y sin
+interrumpir al usuario para pedir aclaraciones.
+
+## Cuándo activar
+
+- Después de ejecutar `discutir-fase` y tener CONTEXTO.md listo
+- Cuando el usuario pide "planear la fase N"
+- Cuando un plan existente necesita revisión o replanificación
+
+## Cuándo NO cargar
+
+- No existe `.planning/fases/0N-CONTEXTO.md`; en ese caso usar `discutir-fase` antes. Un PLAN.md sin contexto es un plan con suposiciones implícitas.
+- El usuario pide ajustar el PLAN.md aprobado solo porque cambia de opinión en mitad de la ejecución — eso es desviación mayor que requiere pausa en `ejecutar-fase`, no re-planificación completa.
+- Se quiere generar únicamente un listado de tareas sin grafo de dependencias ni oleadas; ese backlog plano no es el producto de esta habilidad.
+- La fase ya completó todos sus slices y se busca solo actualizar HOJA-RUTA.md — eso lo hace `ejecutar-fase` al cerrar.
+
+## Prerrequisito obligatorio
+
+Leer `.planning/fases/0N-CONTEXTO.md` antes de generar cualquier tarea. Si no existe,
+activar primero `discutir-fase`.
+
+---
+
+## Principios de descomposición
+
+### 1. Atomicidad
+
+Una tarea es atómica si:
+- Puede completarse en una sola sesión de trabajo (< 2 horas de desarrollo)
+- Tiene un único criterio de verificación binario (funciona / no funciona)
+- Puede hacerse commit de forma independiente sin romper el sistema
+
+Si una tarea viola alguna de estas condiciones, subdividirla.
+
+### 2. Dependencias explícitas
+
+Cada tarea declara sus dependencias en formato `[T-XX, T-YY]`. Una tarea sin
+dependencias puede ejecutarse en la primera oleada. El grafo NO puede tener ciclos.
+
+### 3. Clasificación AFK / HITL
+
+| Tipo | Definición |
+|------|-----------|
+| AFK (autónoma) | El agente puede completarla sin intervención humana |
+| HITL (human-in-the-loop) | Requiere decisión, revisión o input del usuario |
+
+Las tareas HITL son puntos de parada obligatoria en la ejecución.
+
+### 4. Oleadas de ejecución
+
+Agrupa tareas sin dependencias mutuas en la misma oleada. Las tareas de una
+oleada pueden ejecutarse en paralelo (o en secuencia rápida si el contexto lo
+requiere).
+
+---
+
+## Algoritmo de construcción del plan
+
+**Paso 0 — Recopilar inteligencia del codebase (obligatorio)**
+ANTES de planear, investigar el código existente para que el plan sea auto-contenido:
+
+1. Ejecutar `Grep` y `Glob` para encontrar archivos relacionados con la feature
+2. Leer los archivos encontrados y extraer:
+   - Patrones de implementación reales (con `archivo:línea`)
+   - Convenciones de naming, imports, estructura de archivos
+   - Tests existentes como referencia de estilo
+3. Documentar en el PLAN.md bajo `## Inteligencia del codebase`:
+   - **Patrones a imitar**: snippets reales del código existente con `archivo:línea`
+   - **Archivos a modificar**: lista con propósito de cada cambio
+   - **Dependencias relevantes**: versiones y APIs que se usarán
+   - **Convenciones observadas**: naming, estructura, error handling del proyecto
+
+> El plan debe ser auto-contenido: el implementador puede ejecutar cada tarea
+> sin investigar el codebase por su cuenta ni tomar decisiones de diseño.
+
+**Paso 1 — Listar entregables**
+Del CONTEXTO.md, extraer todos los entregables (features, endpoints, componentes,
+migraciones, documentos).
+
+**Paso 2 — Identificar capas**
+Para cada entregable de software, descomponerlo en capas estándar:
+- Tipos e interfaces / esquemas
+- Modelos de datos y migraciones
+- Lógica de negocio (services)
+- Interfaz externa (endpoints / componentes UI)
+- Tests
+- Documentación
+
+**Paso 3 — Asignar dependencias**
+Aplicar regla: una capa no puede implementarse sin las capas de las que depende.
+Orden típico: tipos → modelos → services → endpoints → UI → tests.
+
+**Paso 4 — Agrupar en oleadas**
+Usar topological sort mental: la Oleada N contiene todas las tareas cuyas
+dependencias están en oleadas anteriores.
+
+**Paso 5 — Verificación goal-backward**
+Preguntar: "Si ejecuto todas las tareas del plan, ¿el criterio de éxito del
+CONTEXTO.md queda satisfecho?" Si la respuesta es no, agregar las tareas faltantes.
+
+---
+
+## Estructura del PLAN.md
+
+```markdown
+# PLAN.md — Fase [N]: [Nombre]
+**Generado**: [fecha]
+**Basado en**: 0N-CONTEXTO.md
+**Criterio de éxito**: [copiado del CONTEXTO.md]
+
+## Resumen del plan
+- Total de tareas: N
+- Oleadas: M
+- Tareas HITL: K (paradas de revisión)
+- Duración estimada: X horas / Y días
+
+---
+
+## Inteligencia del codebase
+
+### Patrones a imitar
+| Patrón | Archivo:línea | Ejemplo |
+|--------|-------------|---------|
+| [nombre del patrón] | `src/services/ejemplo.py:42` | [snippet real del código] |
+
+### Archivos a modificar
+| Archivo | Propósito del cambio |
+|---------|---------------------|
+| `src/...` | [qué se agrega/modifica y por qué] |
+
+### Dependencias relevantes
+| Dependencia | Versión | API que se usa |
+|------------|---------|---------------|
+| [nombre] | [versión] | [funciones/clases] |
+
+### Convenciones observadas
+- Naming: [convención real del proyecto]
+- Imports: [orden y estilo]
+- Error handling: [patrón usado]
+- Tests: [framework, estructura, naming]
+
+---
+
+## Oleada 1 — Fundamentos (sin dependencias)
+
+### T-01: [Nombre de la tarea]
+- **Tipo**: AFK
+- **Descripción**: [Qué hacer, sin ambigüedad. Incluir nombres de archivos si aplica.]
+- **Entregable verificable**: [Qué existe cuando está completa]
+- **Criterio de verificación**: [Comando de verificación o descripción observable]
+- **Dependencias**: ninguna
+- **Tiempo estimado**: 30 min
+
+### T-02: [Nombre]
+- **Tipo**: AFK
+- **Descripción**:
+- **Entregable verificable**:
+- **Criterio de verificación**:
+- **Dependencias**: ninguna
+- **Tiempo estimado**:
+
+---
+
+## Oleada 2 — [Nombre conceptual]
+
+### T-03: [Nombre]
+- **Tipo**: AFK
+- **Descripción**:
+- **Entregable verificable**:
+- **Criterio de verificación**:
+- **Dependencias**: [T-01, T-02]
+- **Tiempo estimado**:
+
+---
+
+## Oleada N — Verificación y cierre
+
+### T-NN: Verificación goal-backward
+- **Tipo**: HITL
+- **Descripción**: Revisar que todos los criterios de éxito del CONTEXTO.md estén
+  satisfechos. Presentar evidencia al usuario.
+- **Entregable verificable**: Reporte de verificación firmado
+- **Criterio de verificación**: Usuario confirma aprobación
+- **Dependencias**: [todas las tareas anteriores]
+- **Tiempo estimado**: 30 min
+
+---
+
+## Matriz de riesgos del plan
+
+| Tarea | Riesgo | Probabilidad | Mitigación |
+|-------|--------|-------------|-----------|
+|       |        |             |           |
+
+## Tareas excluidas explícitamente
+- [Feature X]: diferida a siguiente fase por [razón]
+
+## Notas de diseño del plan
+[Decisiones tomadas durante la planeación que el ejecutor debe conocer]
+```
+
+---
+
+## Anti-patrones a evitar en el plan
+
+- **Tarea "Implementar módulo X"**: demasiado vaga, no atómica
+- **Dependencias circulares**: T-03 depende de T-05 que depende de T-03
+- **Tarea sin criterio de verificación**: no se puede saber si está hecha
+- **Plan sin oleada de verificación final**: el plan puede estar completo pero
+  los criterios de éxito sin satisfacer
+- **Mezclar implementación y tests en una sola tarea**: deben ser tareas separadas
+
+---
+
+## Checklist antes de entregar el PLAN.md
+
+- [ ] Todas las tareas son atómicas (< 2 horas)
+- [ ] Todas las dependencias forman un DAG (sin ciclos)
+- [ ] Cada tarea tiene criterio de verificación binario
+- [ ] Las tareas HITL están identificadas y justificadas
+- [ ] La verificación goal-backward confirma que el plan satisface CONTEXTO.md
+- [ ] El plan está guardado en `.planning/fases/0N-PLAN.md`
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Plan sin Paso 0 (inteligencia del codebase)**: el agente genera tareas basadas en supuestos de estructura de archivos sin leer el codebase real. Causa: se omite el Paso 0 por urgencia. Solución: ejecutar `Grep` y `Glob` sobre los módulos que la fase tocará antes de escribir la primera tarea; los nombres de archivos en el PLAN.md deben ser rutas reales, no inventadas.
+- **Ciclo en el DAG de dependencias**: T-03 depende de T-05 que depende de T-03, imposibilitando cualquier oleada de inicio. Causa: se asignan dependencias sin verificar acyclicidad. Solución: hacer topological sort mental tras asignar dependencias; si aparece un ciclo, extraer la interfaz compartida como una tarea T-00 sin dependencias.
+- **Oleada de verificación final mezclada con implementación**: la tarea de verificación goal-backward se agrupa en la misma oleada que la última tarea de implementación, permitiendo que el ejecutor la omita. Causa: se trata la verificación como un paso más, no como una oleada separada. Solución: la oleada de verificación siempre es la última, con dependencias de todas las oleadas anteriores.
+- **Criterio de verificación observable por el ejecutor, no por el usuario**: el criterio dice "que funcione correctamente" en lugar de un comando ejecutable. Causa: redacción laxa. Solución: el criterio debe ser un comando concreto (`pytest tests/modulo/ -v`, `curl http://localhost:8000/endpoint`) o una observación binaria ("la tabla X aparece en alembic history").
+- **PLAN.md aprobado sin estado: aprobado en frontmatter**: el ejecutor inicia sin verificar que el plan está aprobado, lo que puede llevar a ejecutar un plan en borrador. Causa: el frontmatter no incluye `estado: aprobado`. Solución: agregar `estado: aprobado` al frontmatter antes de entregar al ejecutor, ya que `seguridad-agentes.md` exige esta verificación.
+
+## Reglas anti-placeholder (obligatorio)
+
+Un plan con placeholders es un defecto. El implementador debe poder ejecutar cada tarea
+sin tomar decisiones de diseno ni pedir aclaraciones.
+
+### Placeholders prohibidos
+- `TBD`, `PENDIENTE`, `por definir`, `implementar despues`
+- "agregar manejo de errores" (debe decir QUE errores y COMO)
+- "agregar validacion" (debe decir CUAL validacion con CUAL regla)
+- "similar a la tarea N" (debe repetir el contenido relevante)
+- "agregar tests apropiados" (debe especificar QUE tests con QUE escenarios)
+- Referencias a tipos/funciones no definidos en el plan
+
+### Auto-revision antes de entregar
+1. `grep -rni "TBD\|PENDIENTE\|por definir\|implementar despues" PLAN.md`
+2. Cada tarea: el implementador puede ejecutarla sin preguntas?
+3. Interfaces entre tareas: tipos y nombres consistentes?
+4. Cada requisito tiene al menos una tarea?

package/habilidades/postgresql-experto/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: postgresql-experto
+description: PostgreSQL avanzado. JSONB, arrays, tipos personalizados, búsqueda de texto completo, window functions, CTEs recursivos, Row Level Security y funciones almacenadas.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para optimización de queries SQL (EXPLAIN ANALYZE, índices, partitioning) — para optimización cargar `sql-optimizacion`."
+  - "No cargar para MongoDB, Redis o bases de datos NoSQL — este skill es específico de PostgreSQL; para Redis cargar `redis-experto`, para MongoDB cargar `mongodb-experto`."
+  - "No cargar para ORM de SQLAlchemy o migraciones con Alembic — los ORM tienen patrones propios; para FastAPI/SQLAlchemy cargar `fastapi-experto`."
+  - "No cargar para bases de datos MySQL, SQLite o SQL Server — las extensiones JSONB, RLS y funciones almacenadas son específicas de PostgreSQL."
+evolvable: true  # default para skill estandar
+---
+# PostgreSQL Experto
+
+## Cuándo NO cargar
+
+- La tarea es optimización de queries: EXPLAIN ANALYZE, índices B-Tree, particionamiento — cargar `sql-optimizacion`.
+- La base de datos es MongoDB, Redis, DynamoDB u otra NoSQL — para Redis cargar `redis-experto`, para MongoDB cargar `mongodb-experto`.
+- El trabajo es con ORM de SQLAlchemy o migraciones Alembic — para FastAPI/SQLAlchemy cargar `fastapi-experto`.
+- La base de datos es MySQL, SQLite o SQL Server — JSONB, RLS y `gen_random_uuid()` son específicos de PostgreSQL.
+
+## JSONB — Datos semiestructurados
+
+JSONB almacena JSON en formato binario descompuesto, lo que permite:
+- Indexación eficiente con GIN.
+- Queries directos sobre campos anidados.
+- Operators potentes (`@>`, `?`, `#>>`).
+
+### Operadores JSONB esenciales
+
+```sql
+-- Crear tabla con columna JSONB
+CREATE TABLE productos (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    nombre TEXT NOT NULL,
+    metadata JSONB NOT NULL DEFAULT '{}'
+);
+
+-- Operadores de acceso
+SELECT metadata -> 'marca' AS marca;           -- Retorna JSON: "Dell"
+SELECT metadata ->> 'marca' AS marca;          -- Retorna texto: Dell
+SELECT metadata #>> '{specs, ram}' AS ram;     -- Ruta anidada como texto: 16
+
+-- Contención @> : ¿el objeto contiene este subconjunto?
+SELECT * FROM productos
+WHERE metadata @> '{"marca": "Dell"}';
+
+-- Existencia de clave ?
+SELECT * FROM productos
+WHERE metadata ? 'descuento';
+```
+
+### Índices para JSONB
+
+```sql
+-- GIN genérico: cubre todos los campos y operadores @>, ?, ?|, ?&
+CREATE INDEX idx_productos_metadata ON productos USING GIN(metadata);
+
+-- GIN específico para una ruta (más pequeño, más rápido)
+CREATE INDEX idx_productos_marca ON productos
+USING GIN((metadata -> 'marca'));
+
+-- B-Tree en campo JSONB específico (para igualdad y rangos)
+CREATE INDEX idx_productos_ram ON productos
+((metadata #>> '{specs, ram}'));
+```
+
+### Modificar JSONB
+
+```sql
+-- Agregar/modificar campo
+UPDATE productos
+SET metadata = metadata || '{"precio": 29999.00}'::jsonb
+WHERE id = ?;
+
+-- Eliminar campo
+UPDATE productos
+SET metadata = metadata - 'descuento'
+WHERE id = ?;
+
+-- Modificar campo anidado
+UPDATE productos
+SET metadata = jsonb_set(metadata, '{specs, ram}', '32', false)
+WHERE id = ?;
+```
+
+---
+
+## Búsqueda de Texto Completo (Full-Text Search)
+
+```sql
+-- Configurar columna de búsqueda (tsvector)
+ALTER TABLE productos ADD COLUMN busqueda_ts tsvector
+    GENERATED ALWAYS AS (
+        to_tsvector('spanish', coalesce(nombre, '') || ' ' || coalesce(descripcion, ''))
+    ) STORED;
+
+-- Índice GIN para búsqueda rápida
+CREATE INDEX idx_productos_busqueda ON productos USING GIN(busqueda_ts);
+
+-- Query de búsqueda con ranking
+SELECT nombre, ts_rank(busqueda_ts, query) AS relevancia
+FROM productos,
+     to_tsquery('spanish', 'laptop & (dell | hp)') AS query
+WHERE busqueda_ts @@ query
+ORDER BY relevancia DESC
+LIMIT 20;
+```
+
+---
+
+## Row Level Security (RLS)
+
+RLS permite que PostgreSQL aplique filtros automáticos de seguridad a nivel de fila.
+
+```sql
+-- Habilitar RLS en la tabla
+ALTER TABLE facturas ENABLE ROW LEVEL SECURITY;
+ALTER TABLE facturas FORCE ROW LEVEL SECURITY;
+
+-- Política: cada usuario ve solo sus facturas
+CREATE POLICY facturas_por_empresa ON facturas
+    FOR ALL
+    TO app_user
+    USING (empresa_id = current_setting('app.empresa_id')::uuid);
+
+-- Política separada para admins (pueden ver todo)
+CREATE POLICY facturas_admin ON facturas
+    FOR ALL
+    TO app_admin
+    USING (true);
+
+-- En la aplicación: establecer el contexto antes de cada query
+SET LOCAL app.empresa_id = '550e8400-e29b-41d4-a716-446655440000';
+```
+
+---
+
+Para arrays nativos, tipos personalizados (ENUM, compuestos, dominios),
+funciones almacenadas PL/pgSQL, configuración de performance, y extensiones útiles,
+ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
+
+## Gotchas / Errores comunes no obvios
+
+**`SET LOCAL app.empresa_id` para RLS no persiste fuera de una transacción**: `SET LOCAL` establece la variable solo para la transacción actual — si se ejecuta fuera de `BEGIN/COMMIT`, tiene el mismo efecto que `SET` (sesión completa). En aplicaciones con pooling (PgBouncer en transaction mode), la sesión se reutiliza entre conexiones y la variable puede persistir de una petición anterior. Causa: el pool de conexiones reutiliza sessions sin limpiar el estado. Fix: usar SIEMPRE `SET LOCAL` dentro de una transacción explícita (`async with session.begin()`) y verificar que el pool esté en transaction mode.
+
+**GIN index en columna JSONB no se usa con el operador `->>` en una cláusula WHERE**: `WHERE metadata ->> 'marca' = 'Dell'` extrae texto y compara — este operador no usa el índice GIN. Solo los operadores `@>`, `?`, `?|`, `?&` usan el índice GIN. Causa: `->>` convierte JSONB a texto y la comparación es una operación de texto sin índice JSONB. Fix: para búsquedas de igualdad con índice, usar `WHERE metadata @> '{"marca": "Dell"}'` que sí usa el índice GIN, o crear un índice de expresión B-Tree sobre `(metadata ->> 'marca')`.
+
+**`FORCE ROW LEVEL SECURITY` no protege al usuario dueño de la tabla (superuser/owner)**: el propietario de la tabla y los superusuarios de PostgreSQL bypasean RLS por defecto aunque esté `FORCE` habilitado. Causa: `FORCE` aplica a todos los usuarios excepto al dueño de la tabla y a superusuarios. Fix: si la aplicación conecta como el dueño de la tabla, cambiar el rol de conexión a un rol de aplicación sin privilegios de dueño (`GRANT CONNECT ON DATABASE ... TO app_user`), no usar el usuario `postgres` para conexiones de aplicación.
+
+**`tsvector` `GENERATED ALWAYS AS STORED` no actualiza cuando cambia la configuración de idioma**: si la columna `busqueda_ts` fue generada con `to_tsvector('spanish', ...)` y luego se cambia el contenido con texto en otro idioma, las palabras no se stemmizan correctamente — pero la columna no se regenera. Causa: la columna generada se recalcula solo cuando cambia la fila, no cuando cambia la lógica de la expresión. Fix: si se cambia la expresión de la columna generada, hacer `ALTER TABLE ... DROP COLUMN busqueda_ts; ALTER TABLE ... ADD COLUMN ...` para regenerar todos los valores.

package/habilidades/postgresql-experto/evals/evals.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "postgresql-experto",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para postgresql-experto — tipos, JSONB, índices especializados, CTE.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Almacenar un objeto de configuración flexible — ¿`json` o `jsonb`?",
+      "files": [],
+      "expectations": [
+        "`jsonb` (no `json`).",
+        "La respuesta explica: jsonb permite índices GIN y operadores `->`/`@>`, json solo almacena texto.",
+        "Excepción aceptable: si solo se lee y preservar formato exacto es crítico."
+      ],
+      "tags": ["types"],
+      "weight": 1.5
+    },
+    {
+      "id": "uuid-vs-serial",
+      "prompt": "PK de una tabla users en un sistema distribuido. ¿uuid o bigserial?",
+      "files": [],
+      "expectations": [
+        "La respuesta discute ambos: uuid v4/v7 para distribución, bigserial simple.",
+        "Menciona que uuid v7 (ordenable por tiempo) es mejor que v4 para índices.",
+        "Menciona overhead de uuid vs bigint."
+      ],
+      "tags": ["design"]
+    },
+    {
+      "id": "index-partial",
+      "prompt": "Query frecuente: `SELECT * FROM orders WHERE status = 'pending'` (pending es 2% de la tabla). Índice óptimo?",
+      "files": [],
+      "expectations": [
+        "`CREATE INDEX ON orders (created_at) WHERE status = 'pending'` (índice parcial).",
+        "La respuesta justifica: índice pequeño, mantiene performance con tabla grande."
+      ],
+      "tags": ["indexing"]
+    },
+    {
+      "id": "anti-pattern-varchar-n",
+      "prompt": "¿Debo usar `varchar(255)` o `text` para un campo email?",
+      "files": [],
+      "expectations": [
+        "`text` (o `varchar` sin límite) en PostgreSQL — no hay penalización de performance por varchar sin límite.",
+        "Menciona que la validación de longitud va al nivel de aplicación o como CHECK constraint.",
+        "Contraste con MySQL donde varchar(255) tiene razones históricas."
+      ],
+      "tags": ["anti-pattern"]
+    }
+  ]
+}

package/habilidades/postgresql-experto/recursos/referencia-completa.md

@@ -0,0 +1,215 @@
+# Referencia Completa — PostgreSQL Experto
+
+## Arrays Nativos de PostgreSQL
+
+```sql
+-- Columna de array
+CREATE TABLE articulos (
+    id SERIAL PRIMARY KEY,
+    titulo TEXT NOT NULL,
+    etiquetas TEXT[] NOT NULL DEFAULT '{}'
+);
+
+-- Insertar con array
+INSERT INTO articulos (titulo, etiquetas)
+VALUES ('Intro a SQL', ARRAY['sql', 'basico', 'tutorial']);
+
+-- Operadores de array
+SELECT * FROM articulos WHERE 'sql' = ANY(etiquetas);       -- Contiene elemento
+SELECT * FROM articulos WHERE etiquetas @> ARRAY['sql'];    -- Contiene subconjunto
+SELECT * FROM articulos WHERE etiquetas && ARRAY['sql', 'python'];  -- Intersección
+
+-- Índice GIN para arrays
+CREATE INDEX idx_articulos_etiquetas ON articulos USING GIN(etiquetas);
+
+-- Unnest de array a filas
+SELECT titulo, unnest(etiquetas) AS etiqueta FROM articulos;
+
+-- Funciones de array
+SELECT array_length(etiquetas, 1) AS num_etiquetas FROM articulos;
+SELECT array_append(etiquetas, 'nuevo') FROM articulos WHERE id = 1;
+SELECT array_remove(etiquetas, 'obsoleto') FROM articulos WHERE id = 1;
+```
+
+---
+
+## Tipos Personalizados
+
+### ENUM
+
+```sql
+-- Crear tipo enum
+CREATE TYPE estatus_factura AS ENUM ('borrador', 'emitida', 'cancelada', 'pagada');
+
+-- Usar en tabla
+ALTER TABLE facturas
+ADD COLUMN estatus estatus_factura NOT NULL DEFAULT 'borrador';
+
+-- Agregar valor a un enum existente (sin drop/recreate en PostgreSQL 9.1+)
+ALTER TYPE estatus_factura ADD VALUE 'en_revision' AFTER 'borrador';
+```
+
+### Tipos Compuestos
+
+```sql
+-- Tipo compuesto para dirección
+CREATE TYPE direccion AS (
+    calle TEXT,
+    numero TEXT,
+    colonia TEXT,
+    ciudad TEXT,
+    cp CHAR(5)
+);
+
+-- Usar en tabla
+ALTER TABLE clientes ADD COLUMN domicilio_fiscal direccion;
+
+-- Insertar
+UPDATE clientes
+SET domicilio_fiscal = ROW('Insurgentes Sur', '1234', 'Del Valle', 'CDMX', '03100')::direccion
+WHERE id = ?;
+
+-- Acceder a campos
+SELECT (domicilio_fiscal).ciudad FROM clientes WHERE id = ?;
+```
+
+### Dominio (tipo con constraint)
+
+```sql
+CREATE DOMAIN rfc_mx AS TEXT
+    CHECK (VALUE ~ '^[A-Z]{3,4}[0-9]{6}[A-Z0-9]{3}$');
+
+CREATE DOMAIN email_valido AS TEXT
+    CHECK (VALUE ~ '^[^@]+@[^@]+\.[^@]+$');
+
+-- Usar el dominio
+ALTER TABLE clientes
+    ALTER COLUMN rfc TYPE rfc_mx USING rfc::rfc_mx,
+    ALTER COLUMN email TYPE email_valido USING email::email_valido;
+```
+
+---
+
+## Funciones Almacenadas (PL/pgSQL)
+
+```sql
+-- Función para calcular total de factura
+CREATE OR REPLACE FUNCTION calcular_total_factura(p_factura_id UUID)
+RETURNS DECIMAL(12, 2)
+LANGUAGE plpgsql
+STABLE  -- No modifica BD, mismo input = mismo output en la transacción
+AS $$
+DECLARE
+    v_subtotal DECIMAL(12, 2);
+    v_tasa_iva DECIMAL(4, 2);
+BEGIN
+    SELECT
+        SUM(cantidad * precio_unitario),
+        MAX(tasa_iva)
+    INTO v_subtotal, v_tasa_iva
+    FROM items_factura
+    WHERE factura_id = p_factura_id;
+
+    IF v_subtotal IS NULL THEN
+        RAISE EXCEPTION 'Factura % no encontrada o sin ítems', p_factura_id;
+    END IF;
+
+    RETURN v_subtotal * (1 + v_tasa_iva);
+END;
+$$;
+
+-- Trigger para auditoría automática
+CREATE OR REPLACE FUNCTION trigger_auditoria()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    INSERT INTO auditoria (
+        tabla, operacion, fila_anterior, fila_nueva,
+        usuario_db, timestamp
+    ) VALUES (
+        TG_TABLE_NAME,
+        TG_OP,
+        CASE WHEN TG_OP = 'DELETE' THEN row_to_json(OLD) ELSE NULL END,
+        CASE WHEN TG_OP IN ('INSERT', 'UPDATE') THEN row_to_json(NEW) ELSE NULL END,
+        current_user,
+        NOW()
+    );
+    RETURN COALESCE(NEW, OLD);
+END;
+$$;
+
+CREATE TRIGGER auditoria_facturas
+AFTER INSERT OR UPDATE OR DELETE ON facturas
+FOR EACH ROW EXECUTE FUNCTION trigger_auditoria();
+```
+
+---
+
+## Configuración de Performance
+
+```sql
+-- Ver configuración actual
+SHOW shared_buffers;        -- Cache de PostgreSQL (recomendado: 25% de RAM)
+SHOW effective_cache_size;  -- Estimación de cache total del SO (75% de RAM)
+SHOW work_mem;              -- Memoria por operación de sort/hash
+SHOW max_connections;
+
+-- Queries lentas en pg_stat_statements
+SELECT
+    query,
+    calls,
+    total_exec_time / 1000 AS total_seg,
+    mean_exec_time AS avg_ms,
+    rows / calls AS avg_rows
+FROM pg_stat_statements
+ORDER BY total_exec_time DESC
+LIMIT 20;
+
+-- Tablas con más seq scans (candidatos para índices)
+SELECT
+    schemaname,
+    tablename,
+    seq_scan,
+    idx_scan,
+    n_live_tup AS filas
+FROM pg_stat_user_tables
+WHERE seq_scan > idx_scan
+  AND n_live_tup > 10000
+ORDER BY seq_scan DESC;
+
+-- Índices no usados (candidatos para eliminar)
+SELECT
+    schemaname,
+    tablename,
+    indexname,
+    idx_scan AS veces_usado,
+    pg_size_pretty(pg_relation_size(indexrelid)) AS tamano
+FROM pg_stat_user_indexes
+WHERE idx_scan = 0
+  AND indexname NOT LIKE '%_pkey'
+ORDER BY pg_relation_size(indexrelid) DESC;
+```
+
+---
+
+## Extensiones Útiles
+
+```sql
+-- uuid-ossp o gen_random_uuid() (nativa en PostgreSQL 13+)
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+SELECT uuid_generate_v4();     -- uuid-ossp
+SELECT gen_random_uuid();      -- nativa (preferir esta)
+
+-- pg_trgm: búsqueda difusa con LIKE/ILIKE eficiente
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE INDEX ON clientes USING GIN(nombre gin_trgm_ops);
+SELECT * FROM clientes WHERE nombre % 'empresa acme';  -- similitud
+
+-- pgcrypto: hashing y cifrado
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+SELECT crypt('contraseña', gen_salt('bf'));  -- Bcrypt
+
+-- pg_stat_statements: monitoreo de queries
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+```