swl-ses 3.3.2

package/habilidades/performance-baseline/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: performance-baseline
+description: Establece y documenta una línea base de rendimiento para el sistema. Mide latencia p50/p95/p99, throughput, uso de memoria y CPU. Identifica cuellos de botella con herramientas de profiling. Guía la optimización con datos, no con suposiciones.
+---
+
+# Habilidad: Performance Baseline
+
+## Propósito
+
+"Optimizar sin medir es adivinar." Esta habilidad establece mediciones reales
+del sistema antes de cualquier optimización, documenta el baseline y guía
+el trabajo de mejora con evidencia. Ninguna optimización se acepta sin una
+comparación before/after con los mismos benchmarks.
+
+## Cuándo activar
+
+- Antes de iniciar una fase de optimización de rendimiento
+- Cuando el usuario reporta "el sistema está lento" sin métricas
+- Al establecer SLOs para un sistema nuevo
+- Antes y después de cambios en queries, caching o arquitectura
+
+---
+
+## Métricas clave a medir
+
+### Latencia (la más importante para APIs)
+
+| Percentil | Descripción | Target típico web |
+|-----------|-------------|------------------|
+| p50 | Mediana — 50% de requests son más rápidos | < 100ms |
+| p95 | 95% de requests terminan antes de este tiempo | < 300ms |
+| p99 | El "peor caso razonable" | < 1000ms |
+| p99.9 | Outliers extremos | < 3000ms |
+
+**Por qué p95 y p99, no promedio**: El promedio oculta las colas lentas. Un
+sistema con p50=50ms y p99=10000ms tiene un promedio "aceptable" pero una
+experiencia terrible para 1 de cada 100 usuarios.
+
+### Throughput
+
+- **Requests por segundo (RPS)**: Cuántas peticiones puede manejar el sistema
+- **Concurrencia máxima**: Número de requests simultáneos sin degradación
+- **Punto de quiebre**: RPS donde la latencia p99 supera el threshold aceptable
+
+### Recursos del sistema
+
+- **CPU**: % de uso en carga normal, pico y stress
+- **Memoria**: RSS basal, memoria en carga, crecimiento por hora (leak detection)
+- **I/O de BD**: queries/segundo, tiempo de query p95, conexiones activas
+- **Network**: bytes in/out, conexiones abiertas
+
+---
+
+## Herramientas de medición por stack
+
+### Backend Python / FastAPI
+
+**Profiling de CPU** — encontrar funciones lentas:
+```python
+# Con cProfile (incluido en stdlib)
+import cProfile
+import pstats
+import io
+
+def profile_function():
+    pr = cProfile.Profile()
+    pr.enable()
+    # ... función a perfilar
+    pr.disable()
+
+    s = io.StringIO()
+    ps = pstats.Stats(pr, stream=s).sort_stats('cumulative')
+    ps.print_stats(20)  # Top 20 funciones más lentas
+    print(s.getvalue())
+```
+
+**Profiling de memoria** — detectar leaks:
+```bash
+pip install memory-profiler
+python -m memory_profiler mi_script.py
+```
+
+**Profiling de queries SQL** — con SQLAlchemy:
+```python
+# En desarrollo, activar logging de queries con tiempo
+import logging
+logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)
+
+# O con pgBadger / pg_stat_statements en PostgreSQL
+# Ver queries más lentas:
+SELECT query, calls, total_time, mean_time, stddev_time
+FROM pg_stat_statements
+ORDER BY mean_time DESC
+LIMIT 20;
+```
+
+**Load testing** — con locust:
+```python
+# locustfile.py
+from locust import HttpUser, task, between
+
+class APIUser(HttpUser):
+    wait_time = between(0.1, 0.5)
+
+    @task(3)  # peso 3 = ejecuta 3x más frecuente
+    def listar_recursos(self):
+        self.client.get("/api/v1/recursos",
+                        headers={"Authorization": f"Bearer {self.token}"})
+
+    @task(1)
+    def crear_recurso(self):
+        self.client.post("/api/v1/recursos",
+                         json={"nombre": "test"},
+                         headers={"Authorization": f"Bearer {self.token}"})
+```
+
+```bash
+# Ejecutar con 100 usuarios, rampa de 10/segundo
+locust -f locustfile.py --headless -u 100 -r 10 --run-time 2m \
+  --host http://localhost:8000
+```
+
+### Frontend Angular
+
+**Core Web Vitals** (métricas que Google y usuarios ven):
+| Métrica | Descripción | Target |
+|---------|-------------|--------|
+| LCP | Largest Contentful Paint — tiempo hasta que el contenido principal es visible | < 2.5s |
+| FID / INP | First Input Delay / Interaction to Next Paint | < 100ms |
+| CLS | Cumulative Layout Shift — estabilidad visual | < 0.1 |
+| TTFB | Time to First Byte | < 600ms |
+
+```bash
+# Lighthouse CLI
+npm install -g lighthouse
+lighthouse http://localhost:4200 --output=json --output-path=lighthouse-report.json
+
+# Analizar bundle size
+ng build --stats-json
+npx webpack-bundle-analyzer dist/*/stats.json
+```
+
+**Profiling de Angular en desarrollo**:
+```typescript
+// Habilitar profiler de Angular
+import { enableProdMode } from '@angular/core';
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+// En main.ts para development
+platformBrowserDynamic().bootstrapModule(AppModule)
+  .then(() => {
+    // Chrome DevTools > Performance > Profile
+    // Buscar "Angular" en la traza para ver change detection cycles
+  });
+```
+
+---
+
+## Plantilla de documento baseline
+
+### `.planning/PERFORMANCE-BASELINE.md`
+
+```markdown
+# PERFORMANCE-BASELINE.md
+**Fecha de medición**: [fecha]
+**Versión del sistema**: [git commit hash]
+**Entorno**: [staging / producción / local con datos reales]
+**Herramientas usadas**: [locust, pytest-benchmark, lighthouse, etc.]
+
+## Condiciones del test
+- Datos en BD: [número de registros en tablas principales]
+- Concurrencia simulada: [N usuarios simultáneos]
+- Duración del test: [N minutos]
+- Hardware del servidor: [specs o instancia cloud]
+
+## Resultados de latencia (API)
+
+| Endpoint | p50 | p95 | p99 | RPS máx |
+|----------|-----|-----|-----|---------|
+| GET /api/v1/[recurso] | Xms | Xms | Xms | N |
+| POST /api/v1/[recurso] | Xms | Xms | Xms | N |
+
+## Resultados de recursos
+
+| Métrica | Basal | Bajo carga | Pico |
+|---------|-------|-----------|------|
+| CPU % | | | |
+| Memoria RSS | | | |
+| Conexiones BD activas | | | |
+| Queries/segundo | | | |
+
+## Core Web Vitals (si aplica)
+
+| Métrica | Valor medido | Target | Estado |
+|---------|-------------|--------|--------|
+| LCP | | < 2.5s | PASS/FAIL |
+| INP | | < 100ms | PASS/FAIL |
+| CLS | | < 0.1 | PASS/FAIL |
+
+## Top 5 queries más lentas
+| Query | Duración media | Llamadas/min | Plan de optimización |
+|-------|---------------|-------------|---------------------|
+|       |               |             |                     |
+
+## Cuellos de botella identificados
+1. [Descripción, causa raíz, impacto estimado]
+
+## SLOs propuestos (basados en baseline)
+| Métrica | SLO | Alerta si supera |
+|---------|-----|-----------------|
+| Latencia p95 | < Xms | > Xms |
+| Error rate | < 0.1% | > 0.5% |
+| Disponibilidad | > 99.5% | < 99.0% |
+```
+
+---
+
+## Proceso de optimización guiada por datos
+
+```
+1. Medir → documentar baseline
+2. Identificar el cuello de botella más costoso (no el más fácil)
+3. Hipótesis: "Creo que X es lento porque Y"
+4. Implementar UNA optimización
+5. Medir con los MISMOS benchmarks del baseline
+6. Comparar before/after
+7. Documentar resultado en PERFORMANCE-BASELINE.md
+8. Si mejoró: hacer commit, continuar con siguiente cuello de botella
+9. Si no mejoró: revertir, revisar hipótesis
+```
+
+### Optimizaciones por orden de impacto típico
+
+1. **Índices de BD faltantes** — impacto: 10x-1000x en queries lentas
+2. **N+1 queries** — impacto: reducción de O(n) queries a O(1)
+3. **Caching de resultados costosos** — impacto: 5x-50x en datos calientes
+4. **Connection pooling** — impacto: elimina overhead de conexiones
+5. **Paginación de resultados grandes** — impacto: reducción de tiempo y memoria
+6. **Bundle splitting en frontend** — impacto: reducción de tiempo de carga inicial
+
+**Anti-patrón a evitar**: optimizar código Python/TypeScript antes de verificar
+que las queries de BD no son el problema real. El 80% de los problemas de
+rendimiento en aplicaciones web tienen origen en la capa de datos.

package/habilidades/planear-fase/SKILL.md

@@ -0,0 +1,184 @@
+---
+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 CONTEXT.md.
+---
+
+# 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 CONTEXT.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 CONTEXT.md listo
+- Cuando el usuario pide "planear la fase N"
+- Cuando un plan existente necesita revisión o replanificación
+
+## Prerrequisito obligatorio
+
+Leer `.planning/CONTEXT-[fase].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 1 — Listar entregables**
+Del CONTEXT.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
+CONTEXT.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**: CONTEXT-[fase].md
+**Criterio de éxito**: [copiado del CONTEXT.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
+
+---
+
+## 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 CONTEXT.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 CONTEXT.md
+- [ ] El plan está guardado en `.planning/PLAN-fase-[N].md`