@saulwade/swl-ses 1.0.0

package/habilidades/evaluacion-agentes/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: evaluacion-agentes
+description: >
+  Framework de evaluación de agentes SWL con métricas pass@k y tracking de fiabilidad.
+  Cargar cuando se necesite evaluar la efectividad de un agente, auditar su rendimiento
+  histórico, diagnosticar agentes con baja fiabilidad o integrar métricas en swl:salud.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para evaluar la calidad de un skill (SKILL.md) — ese es el trabajo de `autoresearch`; este skill mide agentes (frontmatter + instrucciones + historial de ejecución), no skills aislados."
+  - "No cargar para evaluar si un artefacto del plan cumple criterios de aceptación — eso es `verificar-trabajo`; este skill genera métricas pass@k, no verifica slices."
+  - "No cargar cuando se quiera hacer una revisión puntual de código producido por un agente — usar `revisor-codigo-swl` o `checklist-calidad`; este skill requiere historial de múltiples ejecuciones para ser significativo."
+  - "No cargar si el agente tiene menos de 5 ejecuciones registradas — el cálculo de pass@k con n < 5 no es estadísticamente válido y llevaría a acciones incorrectas."
+evolvable: true  # default para skill estandar
+---
+# Evaluación de Agentes SWL
+
+Framework para medir, registrar y mejorar la fiabilidad de los agentes del sistema SWL
+usando la métrica pass@k, estándar en benchmarks de modelos de lenguaje.
+
+## Cuándo cargar
+
+- Se evalúa la efectividad de un agente tras una sesión de trabajo
+- Se audita el rendimiento histórico de agentes en `.planning/EVALUACION.md`
+- Un agente produce resultados inesperados con frecuencia y se necesitan datos
+- Se ejecuta `swl:salud` con la opción de incluir métricas de agentes
+- Se decide si un agente necesita evolución mediante `swl:evolucionar`
+
+---
+
+## Métrica pass@k — Concepto
+
+**pass@k** mide la probabilidad de que un agente produzca al menos una solución
+correcta en k intentos sobre el mismo problema.
+
+| Variante | Significado |
+|----------|-------------|
+| pass@1   | Éxito en el primer intento sin reintento |
+| pass@3   | Éxito si se dan hasta 3 oportunidades |
+| pass@5   | Éxito si se dan hasta 5 oportunidades |
+
+**Interpretación práctica para SWL**:
+- **pass@1 alto** → el agente produce output correcto en la primera ejecución.
+  Indica instrucciones claras y bien calibradas.
+- **pass@1 bajo pero pass@3 alto** → el agente necesita guidance pero puede
+  autocorregirse. Candidato a mejora de instrucciones en su SKILL.md.
+- **pass@3 bajo** → el agente falla sistemáticamente. Requiere evolución urgente.
+
+---
+
+## Fórmula de cálculo
+
+La fórmula estadística exacta para estimar pass@k a partir de n ejecuciones con c correctas:
+
+```
+pass@k = 1 - ( C(n-c, k) / C(n, k) )
+
+donde:
+  n = número total de ejecuciones registradas
+  c = número de ejecuciones con resultado correcto
+  k = número de intentos evaluados (1, 3 o 5)
+  C(a, b) = combinatorio "a sobre b" = a! / (b! * (a-b)!)
+```
+
+**Ejemplo concreto** — agente con 10 ejecuciones, 7 correctas, evaluando pass@1:
+
+```
+pass@1 = 1 - C(10-7, 1) / C(10, 1)
+       = 1 - C(3, 1) / C(10, 1)
+       = 1 - 3/10
+       = 0.70  →  70%
+```
+
+**Cuando n < 5**: no calcular pass@k — la muestra es insuficiente para ser
+representativa. Registrar como "datos insuficientes (n=N)".
+
+---
+
+## Criterios de éxito por ejecución
+
+Una ejecución se registra como **correcta** si cumple TODOS los criterios aplicables:
+
+| Criterio | Aplica a | Cómo verificar |
+|----------|----------|----------------|
+| Build pasa sin errores | Agentes implementadores | `npm run build` / `pytest` sin errores |
+| Tests pasan | Agentes implementadores y QA | suite de tests verde |
+| Review aprueba | Agentes revisores | revisor-codigo-swl da score >= 9.0 |
+| Output tiene estructura esperada | Todos los agentes | frontmatter completo, secciones requeridas |
+| Sin placeholders pendientes | Todos los agentes | grep -cE '\[(PENDIENTE|TBD)\]' output == 0 |
+| Entregable referenciado en ESTADO.md | Agentes de documentación | ESTADO.md actualizado |
+
+Si un criterio no aplica al tipo de agente, se omite de la evaluación.
+
+---
+
+## Objetivos por tipo de agente
+
+| Tipo de agente | pass@1 objetivo | pass@3 objetivo | Acción si no se cumple |
+|----------------|-----------------|-----------------|----------------------|
+| Implementadores (backend, frontend) | >= 70% | >= 90% | Revisar instrucciones de implementación |
+| Revisores (código, seguridad) | >= 85% | >= 95% | Revisar criterios de evaluación del agente |
+| Build resolvers | >= 80% | >= 95% | Agregar ejemplos de errores frecuentes |
+| Planificadores (planificador-swl) | >= 75% | >= 92% | Revisar formato de PLAN.md |
+| Documentadores | >= 80% | >= 95% | Revisar templates en recursos/ |
+| Orquestadores | >= 65% | >= 85% | Revisar lógica de delegación |
+
+**Umbral de alerta**: pass@1 < 60% en cualquier tipo → el agente necesita mejora
+urgente antes de la próxima sesión de producción.
+
+---
+
+## Formato de registro en EVALUACION.md
+
+Cada evaluación se registra en `.planning/EVALUACION.md`. Si el archivo no existe,
+crearlo al registrar la primera evaluación.
+
+### Estructura del archivo
+
+```markdown
+# EVALUACION.md — Métricas de agentes SWL
+
+Última actualización: YYYY-MM-DD
+
+## Resumen ejecutivo
+
+| Agente | Ejecuciones (n) | Correctas (c) | pass@1 | pass@3 | Estado |
+|--------|-----------------|---------------|--------|--------|--------|
+| planificador-swl | 12 | 9 | 75% | 92% | OK |
+| backend-python-swl | 8 | 5 | 63% | 88% | REVISAR |
+| revisor-codigo-swl | 15 | 13 | 87% | 100% | OK |
+
+## Detalle por agente
+
+### planificador-swl
+
+- **n total**: 12 ejecuciones
+- **c correctas**: 9
+- **pass@1**: 75%  (objetivo: >= 75%) — CUMPLE
+- **pass@3**: 92%  (objetivo: >= 92%) — CUMPLE
+- **Errores frecuentes**: slices sin criterio de éxito definido (2 casos)
+- **Última evaluación**: 2026-03-25
+
+#### Historial reciente (últimas 5)
+
+| Fecha | Resultado | Notas |
+|-------|-----------|-------|
+| 2026-03-25 | correcto | — |
+| 2026-03-20 | incorrecto | faltó slice de migración |
+| 2026-03-15 | correcto | — |
+| 2026-03-10 | correcto | — |
+| 2026-03-05 | correcto | — |
+```
+
+### Reglas de registro
+
+- Registrar cada ejecución al finalizar la sesión, no acumular varias sin registrar.
+- El campo "Notas" debe explicar el motivo del fallo si el resultado fue incorrecto.
+  Un registro sin notas en fallo es inútil para mejorar el agente.
+- Recalcular pass@1 y pass@3 cada vez que se agrega un registro nuevo.
+- Si n aumenta pero c no (fallo), actualizar los porcentajes.
+
+---
+
+## Proceso de evaluación — paso a paso
+
+1. **Identificar el agente evaluado** y localizar su entrada en EVALUACION.md.
+   Si no existe, crear la sección con n=0, c=0.
+
+2. **Determinar si la ejecución fue correcta** aplicando los criterios de la tabla
+   de criterios de éxito. Documentar cuáles criterios se verificaron.
+
+3. **Registrar en el historial** con fecha, resultado y notas si hubo fallo.
+
+4. **Incrementar n**. Si fue correcto, incrementar también c.
+
+5. **Recalcular pass@1 y pass@3** usando la fórmula. Si n < 5, registrar
+   "datos insuficientes" en lugar del porcentaje.
+
+6. **Comparar contra objetivo** de la tabla de objetivos por tipo.
+   Si pass@1 < 60%, anotar "ALERTA" en el campo Estado.
+
+7. **Si Estado = ALERTA o REVISAR**, abrir un issue o nota en ESTADO.md para
+   que `swl:evolucionar` lo procese en la siguiente sesión.
+
+---
+
+## Integración con swl:salud
+
+El comando `swl:salud` puede incluir un resumen de métricas de agentes como
+Paso 6b del diagnóstico. El formato esperado en SALUD.md es:
+
+```markdown
+## Métricas de agentes (pass@1)
+
+| Agente | pass@1 | pass@3 | Estado |
+|--------|--------|--------|--------|
+| planificador-swl | 75% | 92% | OK |
+| backend-python-swl | 63% | 88% | REVISAR |
+
+Agentes en alerta (pass@1 < 60%): ninguno
+Agentes con datos insuficientes (n < 5): 3
+```
+
+Si `.planning/EVALUACION.md` no existe, `swl:salud` reporta:
+"Métricas de agentes: sin datos — ejecutar evaluacion-agentes para iniciar tracking."
+
+---
+
+## Cuándo un agente necesita mejora
+
+Un agente necesita mejora cuando ocurre cualquiera de estas condiciones:
+
+- **pass@1 < 60%** sostenido durante 5 o más ejecuciones consecutivas
+- **El mismo tipo de fallo** aparece en 3 o más registros del historial
+- **pass@3 < 80%** en cualquier tipo de agente
+- Un fallo causó un incidente en producción (independiente del porcentaje)
+
+**Acción**: Invocar `swl:evolucionar` con el nombre del agente y los errores
+frecuentes del historial como contexto. El agente de evolución revisará las
+instrucciones y propondrá cambios específicos.
+
+---
+
+## Evaluación conductual de skills — patrón de 3 brazos
+
+pass@k mide la fiabilidad de agentes. Pero ¿cómo medir si un **skill** realmente
+cambia el comportamiento del modelo, o si el mismo resultado se obtendría con
+cualquier instrucción genérica?
+
+### El problema de la conflación
+
+Si se compara "modelo con skill" vs "modelo sin nada", toda mejora se atribuye
+al skill — incluso si una instrucción mínima como "sé conciso" lograría lo mismo.
+Esto infla el valor percibido de skills que solo repiten conocimiento general.
+
+### Harness de evaluación de 3 brazos
+
+| Brazo | System prompt | Propósito |
+|-------|--------------|-----------|
+| **baseline** | Ninguno | Medir capacidad base del modelo |
+| **control** | Instrucción genérica del dominio (ej: "Escribe código Python limpio y testeado") | Medir el efecto de cualquier instrucción mínima |
+| **tratamiento** | Instrucción genérica + contenido del skill | Medir el delta real del skill |
+
+**La métrica que importa**: tratamiento vs control (no tratamiento vs baseline).
+Si el skill no mejora sobre el control genérico, su contenido no aporta valor
+diferencial — el modelo ya sabía hacerlo con una instrucción mínima.
+
+### Cómo aplicar
+
+1. Definir 5-10 prompts representativos del dominio del skill
+2. Ejecutar cada prompt en los 3 brazos (misma temperatura, mismo modelo)
+3. Evaluar las respuestas con criterios binarios (correcto/incorrecto) o escala
+4. Comparar: ¿el brazo tratamiento supera consistentemente al control?
+
+**Cuándo usar**: Al decidir si un skill candidato justifica su incorporación al
+sistema, o al auditar si un skill existente aporta valor real. No es necesario
+para cada evaluación rutinaria — es una técnica de diagnóstico profundo.
+
+**Resultado esperado**: Si tratamiento > control en >= 60% de los prompts,
+el skill aporta valor. Si no, su contenido es redundante con el conocimiento
+base del modelo y debe reescribirse con foco en gotchas y decisiones no obvias.
+
+---
+
+## Taxonomía de brechas — por qué fallan los agentes
+
+Cuando un agente falla (pass@1 = incorrecto), la causa raíz no siempre es "el agente
+está mal". Clasificar el tipo de brecha antes de proponer correcciones evita aplicar
+la solución incorrecta (ej. reescribir un skill cuando el problema era falta de herramienta).
+
+| Tipo de brecha | Síntoma típico | Acción correctiva |
+|----------------|---------------|-------------------|
+| **Skill faltante** | El agente improvisa donde debería seguir un patrón establecido | Crear o enriquecer el skill del dominio |
+| **Herramienta faltante** | El agente describe lo que haría pero no puede ejecutarlo | Agregar MCP tool, script en `scripts/` o acceso a herramienta |
+| **Permiso faltante** | El agente intenta una acción y recibe denegación | Ajustar permisos en `allowedTools` o configuración de sandbox |
+| **Memoria faltante** | El agente re-pregunta decisiones ya tomadas en sesiones anteriores | Persistir en ESTADO.md, DECISIONS.md o memory del sistema |
+| **Mala descomposición** | El agente produce un resultado parcial o mezcla responsabilidades | Revisar la delegación en el orquestador o el PLAN.md |
+| **Verificación insuficiente** | El agente entrega resultado incorrecto pero confiado | Agregar criterios de éxito explícitos o harness de validación |
+| **Autonomía insegura** | El agente toma decisiones irreversibles sin confirmación | Agregar checkpoint humano o reducir `nivelRiesgo` |
+| **Modelo inadecuado** | El agente produce output superficial para la complejidad de la tarea | Escalar tier del modelo (haiku→sonnet→opus) según tabla Model-Tier |
+| **Sobrecarga de contexto** | El agente olvida instrucciones tempranas o se contradice | Compactar contexto, usar `/swl:compactar`, reducir archivos cargados |
+
+**Proceso**: Al registrar un fallo en el historial de EVALUACION.md, anotar el tipo
+de brecha en la columna "Notas". Cuando un tipo acumula 3+ ocurrencias, la acción
+correctiva correspondiente se convierte en prioridad para `/swl:evolucionar`.
+
+---
+
+## Anti-patrones en evaluación
+
+- **Registrar sin verificar**: marcar como correcto sin correr los criterios
+  de éxito. Contamina las métricas y oculta problemas reales.
+- **No registrar fallos**: solo registrar éxitos infla artificialmente pass@1.
+  Todos los intentos se registran, independiente del resultado.
+- **Evaluar con n < 5**: un porcentaje con 3 ejecuciones no es estadísticamente
+  representativo. Reportar como "datos insuficientes".
+- **Comparar entre tipos**: un revisor con pass@1 = 80% y un implementador con
+  pass@1 = 80% no son equivalentes. Los objetivos por tipo existen por una razón.
+- **Atribuir mejoras sin grupo control**: medir skill vs baseline conflaciona el
+  efecto del skill con el efecto de dar cualquier instrucción. Usar 3 brazos.
+
+## Cuándo NO cargar
+
+- Se quiere mejorar un SKILL.md específico — eso es `autoresearch`, que trabaja sobre el texto del skill, no sobre métricas de ejecución de agente.
+- Se quiere verificar si un artefacto del plan cumple criterios de aceptación — eso es `verificar-trabajo`; este skill opera sobre historial de múltiples corridas, no sobre un entregable puntual.
+- El agente en cuestión tiene menos de 5 ejecuciones registradas en EVALUACION.md — el pass@k sin datos suficientes produce porcentajes que llevan a acciones incorrectas.
+- Se hace revisión puntual de la calidad del código de un agente — cargar `checklist-calidad` o invocar `revisor-codigo-swl`; este skill no evalúa artefactos individuales.
+
+## Gotchas / Errores comunes no obvios
+
+- **pass@3 calculado como promedio de 3 corridas en lugar de con la fórmula binomial**: el resultado aparece como 67% cuando la fórmula correcta `1 - C(n-c, k)/C(n, k)` daría 92%. Causa: usar `c/n` directamente en lugar de aplicar la fórmula pass@k estándar. Solución: usar siempre `pass@k = 1 - C(n-c, k) / C(n, k)`; para los valores típicos (n=12, k=3), la diferencia entre la fórmula correcta y el promedio simple es mayor al 20%.
+- **Brecha de tipo "skill faltante" tratada como "modelo inadecuado"**: el equipo escala a Opus porque el agente improvisa, cuando el problema real es que no existe un skill para ese dominio. Causa: no diagnosticar el tipo de brecha antes de actuar. Solución: antes de escalar modelo, verificar en la taxonomía de brechas si el agente tiene acceso a un skill del dominio — si no existe, crearlo es más efectivo y económico que escalar de Sonnet a Opus.
+- **Evaluación con los mismos 3 prompts en cada sesión**: el pass@1 llega al 100% pero el agente falla en producción con prompts diferentes. Causa: el conjunto de evaluación no es representativo del uso real. Solución: rotar el conjunto de prompts cada 30 días usando casos de uso reales capturados en `.planning/sessions/`; un conjunto estático que siempre pasa deja de ser informativo.
+- **Sesión del harness de 3 brazos comparando baseline vs tratamiento (sin control)**: la mejora del skill se atribuye al contenido del skill cuando parte de la mejora viene de tener cualquier instrucción. Causa: omitir el brazo "control" (instrucción genérica) del harness. Solución: el brazo control es obligatorio — sin él no se puede saber si el contenido del skill supera una instrucción mínima de una línea.

package/habilidades/event-driven/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: event-driven
+description: Arquitectura event-driven. Message brokers RabbitMQ y Kafka, event sourcing, CQRS, pub/sub, event schemas, idempotency, dead letter queues, retry strategies, eventual consistency. Con ejemplos Python.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para pipelines de datos ETL con Kafka como transporte de datos masivos — para ingeniería de datos cargar `datos-etl`."
+  - "No cargar para microservicios sin mensajería (REST, gRPC sincrónico entre servicios) — para microservicios síncronos cargar `microservicios`."
+  - "No cargar para colas de tareas simples (Celery, Bull, RQ) sin patrones de evento — las colas de tareas son un subconjunto; cargar el skill del framework correspondiente."
+  - "No cargar para websockets y notificaciones push en tiempo real al cliente — para realtime client-side cargar el skill del framework frontend."
+---
+# Arquitectura Orientada a Eventos
+
+Los sistemas event-driven desacoplan productores de consumidores, permitiendo escalar
+componentes independientemente y resilir ante fallos.
+
+---
+
+## Cuándo NO cargar
+
+- El uso de Kafka/RabbitMQ es para ingesta masiva de datos ETL, no para eventos de negocio: cargar `datos-etl`.
+- Los microservicios se comunican de forma síncrona (REST, gRPC) sin mensajería: cargar `microservicios`.
+- La cola es de tareas background simples (Celery, Bull, RQ) sin esquemas de evento ni idempotencia: cargar el skill del framework.
+- La funcionalidad es de notificaciones push al cliente via WebSockets: cargar el skill del framework frontend.
+
+## Cuándo Usar Event-Driven
+
+**USAR cuando**:
+- Múltiples consumidores reaccionan al mismo evento
+- El productor no necesita respuesta inmediata
+- Necesitas escalar productores y consumidores independientemente
+- Necesitas auditoría completa de cambios (event log = audit log)
+
+**NO USAR cuando**:
+- Necesitas respuesta síncrona inmediata para el usuario
+- El flujo es simple y lineal (no hay múltiples consumidores)
+- La consistencia eventual no es aceptable para el dominio
+
+---
+
+## Reglas Obligatorias
+
+1. **Schemas de eventos tipados** — SIEMPRE definir con Pydantic. Son el contrato entre servicios.
+2. **Versioning en schemas** — campo `version: "1.0"`. NUNCA romper compatibilidad hacia atrás.
+3. **Idempotency en todos los handlers** — verificar antes de procesar, marcar después.
+4. **Dead Letter Queue** — OBLIGATORIA para cada cola. Mensajes que fallan van a DLQ.
+5. **Retry con backoff exponencial + jitter** — evitar thundering herd.
+6. **Correlation ID** — propagar en todos los eventos para trazabilidad.
+7. **Transactional Outbox** — para garantía de publicación atómica con BD.
+8. **Consumer group names** — descriptivos y estables (no dinámicos).
+
+---
+
+## RabbitMQ vs Kafka — Cuándo Usar Cuál
+
+| Criterio | RabbitMQ | Kafka |
+|----------|----------|-------|
+| Patrón principal | Pub/Sub, work queues | Streaming, event log |
+| Orden de mensajes | Por cola | Por partition |
+| Retención | Hasta consumir | Configurable (días/ilimitado) |
+| Escala | Miles de msgs/seg | Millones de msgs/seg |
+| Complejidad operativa | Menor | Mayor |
+
+---
+
+## Patrón de Evento Base
+
+```python
+from pydantic import BaseModel
+from datetime import datetime, timezone
+import uuid
+
+class EventoBase(BaseModel):
+    id: str = ""
+    timestamp: datetime = None
+    version: str = "1.0"
+    correlation_id: str = ""
+    origen: str
+
+    def model_post_init(self, *args):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc)
+```
+
+---
+
+## Idempotency — Patrón Esencial
+
+```python
+class HandlerConIdempotencia:
+    async def manejar(self, evento) -> None:
+        consumer_id = "mi_handler"
+        # Verificar ANTES de procesar
+        if await self._idempotencia.ya_procesado(evento.id, consumer_id):
+            return
+        # Procesar
+        await self._procesar(evento)
+        # Marcar DESPUÉS del procesamiento exitoso
+        await self._idempotencia.marcar_procesado(evento.id, consumer_id)
+```
+
+---
+
+## Transactional Outbox — Publicación Garantizada
+
+Problema: publicar evento Y hacer commit en BD de forma atómica.
+Solución: escribir evento a tabla "outbox" en misma transacción, worker publica al broker.
+
+```python
+# Mismo commit = garantía de consistencia
+empleado = Empleado(**comando.model_dump())
+db.add(empleado)
+evento_outbox = EventoOutbox(tipo="empleado.creado", payload={...})
+db.add(evento_outbox)
+await db.commit()  # Atómico
+```
+
+---
+
+## Eventual Consistency — Manejo en UI
+
+- Responder con `202 Accepted` + endpoint de polling para verificar estado.
+- El frontend consulta periódicamente hasta que el recurso esté disponible.
+
+---
+
+## Checklist de Sistema Event-Driven
+
+- [ ] Schemas de eventos definidos con Pydantic (tipado fuerte)
+- [ ] Versioning en schemas (campo `version`)
+- [ ] Idempotency en todos los handlers
+- [ ] Dead Letter Queue para cada cola
+- [ ] Retry con backoff exponencial y jitter
+- [ ] Correlation ID propagado
+- [ ] Transactional Outbox para garantía de publicación
+- [ ] Monitoring de DLQ con alertas
+- [ ] Tests de integración con broker real
+- [ ] Schemas backward-compatible (cambios aditivos)
+
+Para implementaciones completas de RabbitMQ, Kafka, CQRS, Outbox y más, ver [recursos/implementaciones-completas.md](recursos/implementaciones-completas.md).
+
+## Gotchas / Errores comunes no obvios
+
+**El handler de idempotencia verifica el `evento.id` pero el mismo evento puede llegar con IDs diferentes desde distintas fuentes**: si el mismo evento lógico se publica dos veces (por reintentos del Outbox o doble procesamiento del productor), y cada publicación genera un UUID diferente, la verificación `ya_procesado(evento.id)` no detecta el duplicado. Causa: la idempotencia basada en ID del evento asume que el productor genera el mismo ID para el mismo evento lógico. Fix: para eventos donde la duplicación puede ocurrir en el productor, usar un ID de negocio determinista como clave de idempotencia: `f"pedido-{pedido_id}-pagado"` en lugar del UUID del evento. El UUID es correcto para los reintentos de entrega del broker, no para prevenir duplicación lógica.
+
+**El Transactional Outbox garantiza que el evento se publica, pero no garantiza el orden de publicación**: si dos operaciones de negocio ocurren en orden A→B pero el worker del Outbox publica B antes que A (por diferencias de timing entre transacciones), los consumidores procesan B antes que A y el estado del sistema queda inconsistente. Causa: el Outbox garantiza publicación eventual, no orden de publicación entre eventos de diferentes transacciones. Fix: para flujos donde el orden importa, incluir un campo `numero_secuencia` o `timestamp` en el evento y que los consumidores validen el orden antes de procesar. Alternativamente, usar particiones de Kafka con la misma clave para el mismo agregado, garantizando orden dentro del agregado.
+
+**`correlation_id` se pierde al cruzar una cola de mensajes asíncrona (Kafka, RabbitMQ)**: el `correlation_id` se propaga correctamente en llamadas HTTP (vía header `X-Correlation-ID`), pero cuando un servicio publica a una cola, el handler del consumidor crea un nuevo contexto de logging sin extraer el `correlation_id` del mensaje. Causa: a diferencia de HTTP donde los middlewares extraen headers automáticamente, los consumidores de Kafka/RabbitMQ requieren código explícito para extraer y bindear el `correlation_id`. Fix: definir un patrón estándar donde todos los handlers de mensajes extraen el campo `correlation_id` del evento antes del primer log: `log = logger.bind(correlation_id=evento.correlation_id)` y usan ese logger vinculado durante todo el procesamiento.
+
+**La Dead Letter Queue se llena silenciosamente y nadie la monitorea hasta que hay un incidente**: los mensajes en DLQ representan operaciones de negocio fallidas (pedidos no procesados, pagos no registrados), pero la DLQ se configura como "red de seguridad" y luego se olvida. Causa: la DLQ previene pérdida de mensajes pero no resuelve el problema subyacente. Sin alertas, los mensajes se acumulan indefinidamente. Fix: configurar alertas en Prometheus/Grafana para `dlq_message_count > 0` con severidad ALTA. Establecer un proceso de revisión de DLQ como parte del runbook de incidentes: inspeccionar el error, corregir la causa raíz, y reprocesar los mensajes desde la DLQ una vez que el sistema está sano.