@saulwade/swl-ses 1.0.0

package/habilidades/performance-baseline/SKILL.md

@@ -0,0 +1,297 @@
+---
+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.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para observabilidad de producción en tiempo real (Prometheus, Grafana, alertas) — para monitoreo y alertas de sistemas en producción cargar `monitoring-alertas`."
+  - "No cargar para profiling de memoria o CPU con flamegraphs en producción bajo carga real sin un baseline previo — establecer primero la línea base antes de profiling avanzado."
+  - "No cargar para load testing de APIs externas o terceros sin autorización — las pruebas de carga sobre infraestructura ajena sin permiso constituyen un ataque DoS."
+  - "No cargar para benchmarks de hardware o comparación de proveedores cloud — este skill mide la aplicación propia, no la plataforma subyacente."
+---
+# Habilidad: Performance Baseline
+
+## Cuándo NO cargar
+
+- La tarea es monitoreo de producción en tiempo real (Prometheus, alertas, dashboards): cargar `monitoring-alertas`.
+- La tarea es load testing de sistemas externos o terceros sin autorización escrita: no proceder.
+- La tarea es comparar proveedores cloud o benchmarks de hardware: usar documentación del proveedor directamente.
+- La tarea es profiling avanzado de un componente ya identificado como cuello de botella: iniciar con este skill para el baseline, luego proceder al profiling específico.
+
+## 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
+  });
+```
+
+---
+
+## Profiling browser-based — Trazas de rendimiento real
+
+Lighthouse da un score sintético. Las trazas de rendimiento dan datos reales de lo que
+ocurre frame-a-frame en el navegador. Preferir trazas cuando se necesita diagnosticar
+**por qué** un Web Vital falla, no solo **que** falla.
+
+**Workflow de profiling con DevTools** (manual o vía MCP con `chrome-devtools-mcp`):
+
+1. Navegar a la página bajo prueba con throttling de CPU 4x y red "Fast 3G"
+2. Grabar traza de rendimiento (botón Record → interactuar → Stop)
+3. Extraer Performance Insights — cada uno indica una causa raíz específica:
+
+| Performance Insight | Qué detecta | Acción correctiva |
+|--------------------|--------------|--------------------|
+| **LCPBreakdown** | Desglose de LCP: TTFB + load delay + load time + render delay | Optimizar el componente con mayor porcentaje |
+| **DocumentLatency** | TTFB alto del documento principal | Revisar server response time, CDN, redirects |
+| **RenderBlocking** | Scripts/CSS que bloquean el primer render | `async`/`defer` en scripts, inline critical CSS |
+| **ThirdPartyIssues** | Scripts de terceros que consumen main thread | Lazy-load o eliminar; mover a web worker si es posible |
+| **LayoutShift** | Elementos que causan CLS (imágenes sin dimensiones, fonts) | `width`/`height` explícitos, `font-display: swap` |
+| **LongTask** | Tareas JS > 50ms que bloquean interactividad (INP) | Code-split, `requestIdleCallback`, web workers |
+
+**Gotcha crítico**: Lighthouse scores (lab data) ≠ experiencia real del usuario (field data).
+Un LCP de 1.8s en Lighthouse puede ser 4.2s en un dispositivo móvil real con red 4G.
+Para datos de campo reales usar CrUX (Chrome User Experience Report) o web-vitals library
+en producción.
+
+---
+
+## 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.
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**Locust reporta latencia p99 dentro del target pero los usuarios se quejan de lentitud porque Locust mide solo el tiempo de respuesta de red y no incluye el tiempo de renderizado del navegador ni los assets**: en una prueba de carga Locust con 100 usuarios y p99=400ms, los usuarios reales experimentan 2.8s porque el bundle JS pesa 3MB y se descarga en paralelo con la API. Causa: Locust mide exclusivamente el tiempo de la llamada HTTP al endpoint, sin incluir la carga de assets estáticos, scripts ni el tiempo de parseo del navegador. Fix: complementar Locust con Lighthouse y trazas de Chrome DevTools. El baseline real de experiencia de usuario combina ambas mediciones, no solo la capa API.
+
+**`memory_profiler` en Python muestra consumo de memoria estable pero la aplicación en producción tiene un leak real porque `memory_profiler` mide solo el proceso Python y no la memoria del pool de conexiones de SQLAlchemy ni los buffers del driver de PostgreSQL**: después de 4 horas de carga, el RSS del proceso crece de 150MB a 1.2GB sin que `@profile` muestre ninguna función acumulando objetos. Causa: `psycopg2` y `asyncpg` usan buffers de memoria C nativos no rastreados por el GC de Python. Fix: medir el RSS completo con `psutil.Process().memory_info().rss` cada N requests en producción, y revisar `pg_stat_activity` para conexiones huérfanas. Si el pool no tiene `pool_recycle` configurado, las conexiones viejas retienen buffers indefinidamente.
+
+**Los resultados de `pg_stat_statements` son inestables en la primera semana de activarlo porque el módulo sólo agrega estadísticas de queries ejecutadas después de su activación**: hacer `CREATE EXTENSION pg_stat_statements` en una BD existente con meses de operación muestra historial vacío; las queries con `mean_time` alto son outliers de las primeras horas, no el comportamiento habitual. Causa: `pg_stat_statements` no retroactiva — solo mide desde su activación. Fix: esperar al menos 48 horas bajo carga normal antes de sacar conclusiones del baseline de queries. Hacer `SELECT pg_stat_statements_reset()` al inicio para tener un período de medición limpio y definido.
+
+**El throughput máximo medido con `locust --headless` es artificialmente bajo cuando el servidor de prueba corre en la misma máquina que la aplicación porque ambos compiten por CPU**: en desarrollo local con 4 núcleos, Locust consume 1.5 núcleos para simular 200 usuarios, dejando solo 2.5 núcleos para la aplicación. El baseline registra 340 RPS como máximo, pero en staging dedicado el mismo sistema alcanza 820 RPS. Causa: la contención de recursos en la máquina local es un factor de confusión sistemático. Fix: ejecutar siempre las pruebas de carga desde una máquina separada (o en CI con runner dedicado) hacia la aplicación en un servidor aislado. Documentar en el baseline si la prueba fue local o remota.

package/habilidades/php-experto/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: php-experto
+description: >
+  PHP moderno con Laravel: Service Container, Eloquent ORM, Form Requests,
+  API Resources, Events, Jobs/Queues, Middleware y Sanctum. Cargar cuando
+  se implementen APIs Laravel, modelos Eloquent, jobs asíncronos o autenticación.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para diseñar patrones Laravel (Action classes, DTOs readonly, Pipeline) — para diseño cargar `php-patrones`."
+  - "No cargar para escribir tests PHPUnit o Pest — para testing cargar `php-testing`."
+  - "No cargar para errores de compilación PHP o Composer — para build errors cargar `build-errors-php`."
+  - "No cargar para PHP sin Laravel (vanilla PHP, Symfony, Slim) — este skill cubre patrones idiomáticos de Laravel específicamente."
+evolvable: true  # default para skill estandar
+---
+# PHP Experto — Laravel Moderno
+
+Laravel es un framework con opiniones fuertes. Este skill cubre los patrones
+idiomáticos de Laravel 10/11: inyección de dependencias via Service Container,
+Eloquent con relaciones complejas, Jobs con Horizon y autenticación con Sanctum.
+
+## Cuándo cargar este skill
+
+Invoca `Skill("php-experto")` cuando:
+
+- Se implementen endpoints en una API Laravel (controllers, routes)
+- Se definan modelos Eloquent con relaciones o query scopes
+- Se escriban Form Requests para validación
+- Se creen Jobs, Events o Listeners
+- Se configure autenticación con Laravel Sanctum
+- Se implementen Artisan commands custom
+
+## Cuándo NO cargar
+
+- La pregunta es sobre diseñar patrones Laravel (Action classes, DTOs readonly, Pipeline) — para diseño cargar `php-patrones`.
+- La tarea es escribir tests PHPUnit o Pest — cargar `php-testing`.
+- Los errores son de Composer, autoload o extensiones PHP — cargar `build-errors-php`.
+- El proyecto usa PHP sin Laravel (Symfony, Slim, vanilla PHP) — este skill cubre patrones idiomáticos de Laravel específicamente.
+
+## Conceptos clave
+
+### Service Container y Dependency Injection
+
+El Service Container resuelve dependencias automáticamente. Inyectar en constructores
+de controllers y services — nunca instanciar con `new` dentro de métodos de negocio.
+
+### Eloquent Relationships
+
+Eloquent soporta `hasOne`, `hasMany`, `belongsTo`, `belongsToMany`, `morphTo` y
+variantes polimórficas. Cada relación tiene un método que retorna el Builder,
+no la colección — la colección se obtiene accediendo a la propiedad.
+
+### Query Scopes
+
+Los scopes encapsulan condiciones de query reutilizables. Los `local scopes` se
+activan con un prefijo `scope` y se encadenan como métodos. Los `global scopes`
+se aplican automáticamente a todas las queries del modelo.
+
+## Reglas obligatorias
+
+### Usar Form Requests para validación — NUNCA validar en el Controller
+
+```php
+// MAL — logica de validacion en el controller
+public function store(Request $request) {
+    $request->validate([...]);
+    // ...
+}
+
+// BIEN — Form Request separado
+public function store(StoreProductoRequest $request) {
+    // $request ya viene validado y autorizado
+    $data = $request->validated();
+}
+```
+
+**Por qué**: Los Form Requests permiten reutilizar validación, separar autorización
+y tienen método `prepareForValidation` para normalizar inputs antes de validar.
+
+### Eager loading OBLIGATORIO para relaciones en colecciones
+
+```php
+// MAL — N+1 queries
+$pedidos = Pedido::all();
+foreach ($pedidos as $pedido) {
+    echo $pedido->cliente->nombre; // query por cada pedido
+}
+
+// BIEN — 2 queries sin importar el tamano de la coleccion
+$pedidos = Pedido::with('cliente')->get();
+```
+
+**Cómo verificar**: Activar `DB::listen` en desarrollo o usar Telescope/Debugbar
+para contar queries. Más de 2 queries para una colección es señal de N+1.
+
+### API Resources para serializar respuestas — NUNCA retornar modelos directamente
+
+```php
+// MAL
+return response()->json($usuario); // expone todos los campos incluidos sensibles
+
+// BIEN
+return new UsuarioResource($usuario);
+return UsuarioResource::collection($usuarios);
+```
+
+### Jobs SIEMPRE en queues para operaciones costosas (>200ms)
+
+```php
+// Dispatch a queue, no sincrono
+EnviarEmailBienvenida::dispatch($usuario)->onQueue('emails');
+
+// Con reintento y delay
+EnviarFactura::dispatch($factura)
+    ->delay(now()->addMinutes(5))
+    ->onQueue('documentos');
+```
+
+### Bindings en TODAS las queries raw — NUNCA interpolacion
+
+```php
+// MAL — SQL injection
+DB::statement("UPDATE usuarios SET rol = '{$rol}' WHERE id = {$id}");
+
+// BIEN — parametros nombrados
+DB::statement("UPDATE usuarios SET rol = :rol WHERE id = :id", [
+    'rol' => $rol,
+    'id'  => $id,
+]);
+```
+
+## Patrones recomendados
+
+### Eloquent Relationships correctamente definidas
+
+```php
+class Pedido extends Model
+{
+    // hasMany: un pedido tiene muchos items
+    public function items(): HasMany
+    {
+        return $this->hasMany(ItemPedido::class);
+    }
+
+    // belongsTo: un pedido pertenece a un cliente
+    public function cliente(): BelongsTo
+    {
+        return $this->belongsTo(Cliente::class);
+    }
+
+    // morphTo: comentarios polimorficos
+    public function comentarios(): MorphMany
+    {
+        return $this->morphMany(Comentario::class, 'comentable');
+    }
+}
+```
+
+### Query Scopes para filtros reutilizables
+
+```php
+class Producto extends Model
+{
+    // Local scope: $query->activo()
+    public function scopeActivo(Builder $query): Builder
+    {
+        return $query->where('activo', true);
+    }
+
+    // Scope con parametro: $query->precioMenorA(500)
+    public function scopePrecioMenorA(Builder $query, float $precio): Builder
+    {
+        return $query->where('precio', '<', $precio);
+    }
+}
+
+// Uso encadenado
+$productos = Producto::activo()->precioMenorA(500)->with('categoria')->get();
+```
+
+### Event + Listener desacoplados
+
+```php
+// Disparar el evento en el service
+event(new PedidoCreado($pedido));
+
+// El listener se encola automaticamente si implementa ShouldQueue
+class NotificarClientePedidoCreado implements ShouldQueue
+{
+    public function handle(PedidoCreado $event): void
+    {
+        $event->pedido->cliente->notify(new PedidoCreadoNotification($event->pedido));
+    }
+}
+```
+
+### Sanctum — proteger rutas de API
+
+```php
+// routes/api.php
+Route::middleware('auth:sanctum')->group(function () {
+    Route::apiResource('pedidos', PedidoController::class);
+});
+
+// Crear token para el usuario
+$token = $usuario->createToken('app-movil', ['pedidos:leer'])->plainTextToken;
+```
+
+### Artisan Command custom
+
+```php
+class SincronizarCatalogo extends Command
+{
+    protected $signature = 'catalogo:sincronizar {--forzar : Ignorar cache}';
+    protected $description = 'Sincroniza el catalogo desde la API externa';
+
+    public function handle(CatalogoService $servicio): int
+    {
+        $this->info('Iniciando sincronizacion...');
+        $resultado = $servicio->sincronizar(forzar: $this->option('forzar'));
+        $this->table(['Categoria', 'Productos'], $resultado->resumen());
+        return Command::SUCCESS;
+    }
+}
+```
+
+## Anti-patrones conocidos
+
+### Fat Controllers — NUNCA poner lógica de negocio en controllers
+
+```php
+// MAL — controller con 80 lineas de logica
+public function store(Request $request) {
+    $descuento = $request->codigo ? Cupon::where('codigo', $request->codigo)
+        ->where('activo', true)->first()?->descuento ?? 0 : 0;
+    $total = collect($request->items)->sum(fn($i) => $i['precio'] * $i['cantidad']);
+    $totalConDescuento = $total * (1 - $descuento / 100);
+    // ... 50 lineas mas
+}
+
+// BIEN — delegar a un service o action
+public function store(StorePedidoRequest $request, CrearPedidoAction $action): JsonResponse
+{
+    $pedido = $action->ejecutar($request->validated());
+    return new PedidoResource($pedido);
+}
+```
+
+### Model Observers para lógica compleja — usar Events en su lugar
+
+Los Observers son invisibles al lector del código. Para lógica de negocio
+significativa (enviar emails, actualizar inventario) usar Events explícitamente.
+
+### Collections::all() en tablas grandes sin paginación
+
+```php
+// MAL — carga toda la tabla en memoria
+$productos = Producto::all();
+
+// BIEN — paginar o usar lazy collection
+$productos = Producto::paginate(50);
+$productos = Producto::lazy(); // procesa de a chunks sin cargar todo
+```
+
+## Checklist de verificación
+
+- [ ] Validación en Form Request, no en el controller
+- [ ] Relaciones cargadas con `with()` en colecciones (sin N+1)
+- [ ] Respuestas de API usando API Resources
+- [ ] Operations >200ms despachadas como Jobs
+- [ ] Sin interpolación de strings en queries SQL
+- [ ] Autenticación con Sanctum en rutas protegidas
+- [ ] `$fillable` o `$guarded` definido en cada modelo
+
+## Referencias
+
+- [Laravel Documentation](https://laravel.com/docs)
+- [Laravel Best Practices](https://github.com/alexeymezenin/laravel-best-practices)
+
+## Gotchas / Errores comunes no obvios
+
+**Eloquent `with()` cargado en el controller no se aplica a queries del service**: si el controller hace `Factura::with('cliente')->find($id)` pero el service tiene su propio `Factura::find($id)` internamente, la relación `cliente` no se carga en la segunda query. Causa: `with()` es por query, no por modelo. Fix: centralizar el eager loading en el repositorio o service — no dispersarlo entre capas.
+
+**`Job::dispatch()` en un test sin `Queue::fake()` ejecuta el job de forma síncrona**: sin `Queue::fake()`, Laravel ejecuta el job inmediatamente en el mismo proceso del test si la queue driver es `sync` (la default en `testing`). Esto puede causar efectos secundarios inesperados en los datos del test. Fix: agregar `Queue::fake()` en el `setUp()` de todos los tests que disparan jobs, y usar `Queue::assertPushed(MiJob::class)` para verificar que fue despachado.
+
+**`FormRequest` con `authorize()` retornando `false` lanza `AuthorizationException` pero en tests lanza `403` sin mensaje descriptivo**: en tests de feature, un `authorize()` que retorna `false` devuelve 403 sin indicar cuál rule falló. Causa: la excepción de autorización no incluye el mensaje del FormRequest. Fix: usar `$this->actingAs($usuario)` con el usuario correcto en los tests, y verificar el comportamiento de `authorize()` en un test unitario del FormRequest separado.
+
+**Eloquent `$fillable` vs `$guarded` — usar `$guarded = ['id']` en lugar de `$fillable` en modelos con muchos campos puede exponer campos no deseados al añadir nuevos**: si se añade un campo sensible al modelo sin actualizar `$fillable`, no se puede asignar masivamente (seguro). Pero con `$guarded = ['id']`, el nuevo campo sí acepta asignación masiva automáticamente. Fix: usar `$fillable` explícito en modelos con campos sensibles para que el default sea denegar asignación masiva.
+
+---
+*Skill creado con swl:crear-skill el 2026-03-31. Versión 1.0.0.*