@saulwade/swl-ses 1.0.0

package/habilidades/meta-skills-estandar/recursos/skills-as-agents.md

@@ -0,0 +1,163 @@
+# Skills as Agents — patrón técnico avanzado
+
+Documenta el patrón Anthropic nativo de ejecutar un skill SWL en su propio
+sub-agente con `agent: true` + `model:` en el frontmatter. Origen: artículo
+"Claude Code's Limits Are Generous. The Problem Is Your Harness." sección 2.3.
+
+## Concepto
+
+Un SKILL.md normal es contenido que se carga al contexto del padre cuando
+se invoca con `Skill("nombre")`. El skill aporta reglas, conocimiento o
+guía al modelo del padre, que las usa al razonar.
+
+Con el patrón skills as agents, el skill se vuelve **invocable como
+sub-agente independiente**: tiene su propio modelo, su propio contexto,
+y solo devuelve un resultado acotado al padre. Útil cuando el skill
+procesa un input grande y debe entregar un resumen.
+
+## Cuándo usar este patrón
+
+- El skill procesa un archivo o input grande y debe devolver solo un
+  resumen al padre (ejemplo: extraer TLDR de un PDF de 50 páginas, sin
+  que el texto completo entre al contexto del padre).
+- El skill ejecuta búsqueda exhaustiva o crawling de un codebase completo
+  y el resultado es un set acotado de findings.
+- El skill necesita un modelo distinto al del padre por costo o latencia
+  (Haiku para trabajo mecánico cuando el padre es Opus).
+- El trabajo del skill es paralelizable y se va a invocar varias veces en
+  la misma sesión.
+
+## Cuándo NO usar
+
+- El skill solo aporta reglas o conocimiento estático que se aplica al
+  razonamiento del padre — esos son skills "passive" normales y NO
+  necesitan `agent: true`. Su valor es justamente que cargan reglas al
+  contexto del padre.
+- El skill es referenciado dentro de otro skill como contenido de apoyo
+  — el contexto del padre lo necesita ver.
+- El skill requiere acceso al contexto activo del padre (decisiones
+  tomadas mid-session, archivos ya leídos) — `agent: true` aísla del
+  padre, así que el sub-agente no vería esa información.
+- El skill es invocado una sola vez en la sesión y su output es pequeño
+  — el overhead de spawn de sub-agente puede dominar.
+
+## Ejemplo de skill como agent
+
+```yaml
+---
+name: tldr-pdf
+description: >
+  Extrae TLDR de 200 palabras de un PDF sin cargar el texto completo en
+  el contexto del padre. Cargar cuando se reciba ruta a un PDF que solo
+  necesita resumen ejecutivo.
+agent: true
+model: claude-haiku-4-5-20251001
+herramientasPermitidas: [Bash, Read]
+---
+
+# tldr-pdf
+
+Recibes la ruta de un PDF como input.
+
+1. Ejecuta `pdftotext "$1" -` para extraer texto.
+2. Lee la salida.
+3. Devuelve SOLO:
+   - 5 bullets de TLDR
+   - 3 quotes que valga la pena conservar
+   - URLs citadas
+
+Nunca devuelvas el texto completo. Nunca expandas más allá de la estructura.
+```
+
+Flujo: el padre invoca `Skill("tldr-pdf")` con la ruta del PDF; el
+sub-agente Haiku ejecuta `pdftotext`, lee la salida (que llena su propio
+contexto, no el del padre), y devuelve ~200 palabras estructuradas. El PDF
+completo nunca toca el contexto del padre.
+
+## Reglas del patrón
+
+### Frontmatter
+
+- `agent: true` activa el modo sub-agente.
+- `model:` debe ser un modelo Anthropic válido. Para skills mecánicos,
+  preferir Haiku (5× más barato que Sonnet, 25× más barato que Opus 4.7).
+- El frontmatter sigue siendo válido SWL: incluir `name`, `description`,
+  `herramientasPermitidas`, `exclusiones` y demás campos obligatorios.
+
+### Cuerpo
+
+- Debe ser **autocontenido**: el sub-agente NO tiene acceso al contexto
+  del padre (CLAUDE.md del proyecto, instintos cargados, sesión activa,
+  archivos previamente leídos). Todo lo que necesite saber tiene que
+  estar en el cuerpo del skill o en lo que reciba como input.
+- El output debe ser **acotado**: si el sub-agente devuelve un dump
+  masivo, se pierde el beneficio (terminamos pasando lo mismo al padre,
+  solo con un round-trip extra). Especificar formato exacto en el
+  cuerpo del skill: número de bullets, longitud máxima, qué incluir y
+  qué no.
+
+### Errores comunes a evitar
+
+- **Usar Opus en `model:` para skills mecánicos**: invalida el ahorro de
+  costo. La mayoría de skills as agents deberían ser Haiku o Sonnet.
+- **Devolver el texto crudo del input**: si el skill recibe un PDF y
+  devuelve el texto completo, no estamos aislando nada. Devuelve siempre
+  la transformación, no el material crudo.
+- **Asumir que el skill verá el CLAUDE.md del proyecto**: no lo verá.
+  Si el skill necesita seguir convenciones del proyecto, hay que
+  explicárselas en el cuerpo.
+
+## Skills SWL candidatos al patrón (no migración masiva)
+
+Evaluación caso por caso. NO aplicar masivamente — el patrón aporta solo
+cuando el skill consume input grande y devuelve output acotado.
+
+| Skill SWL | Por qué encaja | Modelo recomendado |
+|-----------|----------------|--------------------|
+| `extraccion-documentos` | Procesa PDFs/Office grandes | Haiku |
+| `mapear-codebase` | Procesa codebase entero, devuelve reporte | Sonnet |
+| `wiki-conocimiento` (modo query) | Búsqueda en wiki con respuesta acotada | Sonnet |
+
+Skills NO candidatos (son passive, su valor es cargar reglas al contexto del padre):
+
+- `manejo-errores`, `auth-patrones`, `api-rest-diseno`, `accesibilidad-a11y`, etc.
+- Toda regla de estilo o convención por lenguaje.
+- Toda regla SWL en `reglas/`.
+
+## Implicaciones operativas
+
+### Costo
+
+Spawn de sub-agente tiene overhead (system prompt + carga del skill +
+contexto inicial). Para inputs chicos, el overhead supera el ahorro.
+Regla práctica: usar el patrón si el input que el skill procesa es
+≥3,000 tokens (o ≥10K caracteres).
+
+### Latencia
+
+El padre espera al sub-agente antes de continuar. Si el skill demora >10s,
+considerar si la operación cabe en el padre directamente (sin spawn).
+
+### Trazabilidad
+
+Los sub-agentes spawneados aparecen en `claude-usage` (vendor SWL) como
+invocaciones separadas con su propio modelo. Útil para entender qué
+porcentaje del costo viene de sub-agentes vs. trabajo del padre.
+
+### Compatibilidad con SWL
+
+- El skill sigue registrado normalmente en `manifiestos/modulos.json`.
+- El skill se invoca igual: `Skill("nombre")`. La diferencia es interna
+  (el harness Anthropic decide si lo carga al padre o lo ejecuta como
+  sub-agente según el frontmatter).
+- Hooks SWL siguen aplicando: `linea-estado.js`, `monitor-contexto.js`,
+  `audit-trail.js` registran las invocaciones del sub-agente.
+
+## Referencias
+
+- Artículo de origen: "Claude Code's Limits Are Generous. The Problem Is
+  Your Harness." (sección 2.3 — Skills Can Also Be Invoked as Agents).
+- Documentación oficial Anthropic sobre Claude Skills (cuando esté
+  disponible).
+- `Skill("harness-claude-code")` — uso operativo del patrón en sesiones
+  largas, junto con sub-agentes via Task tool y delegación explícita.

package/habilidades/microservicios/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: microservicios
+description: Arquitectura de microservicios. Cuándo usar y cuándo NO. Circuit breakers, service mesh, API gateway, saga pattern, event sourcing, CQRS, distributed tracing, health checks, service discovery. Anti-patrones.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para implementación de APIs REST o GraphQL individuales — para implementación de endpoints cargar `fastapi-experto`, `api-rest-diseno` o `graphql-experto`."
+  - "No cargar para infraestructura de Kubernetes, Docker o Terraform — para infra cargar `cloud-infra`."
+  - "No cargar para messaging/event streaming específico (Kafka, RabbitMQ) — este skill cubre los patrones de arquitectura; para implementación de brokers usar los recursos de infra."
+  - "No cargar para monolitos modulares o arquitectura hexagonal sin distribución — este skill asume distribución de red entre servicios."
+evolvable: true  # default para skill estandar
+---
+# Arquitectura de Microservicios
+
+## Cuándo NO cargar
+
+- La tarea es implementar endpoints REST o GraphQL individuales dentro de un servicio — cargar `fastapi-experto`, `api-rest-diseno` o `graphql-experto`.
+- El trabajo es infraestructura: Kubernetes, Docker Compose, Terraform — cargar `cloud-infra`.
+- La pregunta es sobre configuración específica de un broker de mensajes (Kafka, RabbitMQ, SQS) — este skill cubre los patrones de arquitectura, no la implementación del broker.
+- El sistema es un monolito modular o arquitectura hexagonal sin distribución de red — este skill asume que los servicios se comunican por red.
+
+Microservicios no es la respuesta por defecto — es una decisión de arquitectura con
+costos reales. Este skill cubre cuándo aplicarlos, cómo implementarlos y cuándo evitarlos.
+
+---
+
+## 1. Microservicios o Monolito — Decide primero
+
+### Señales de que el MONOLITO es la respuesta correcta
+
+- Equipo < 10 desarrolladores
+- Dominio de negocio no bien definido aún
+- Producto en fase de descubrimiento (pivots frecuentes)
+- No hay equipos independientes que puedan ser dueños de servicios distintos
+- Sin infraestructura de observabilidad madura
+- SLA de < 99.9%
+
+### Señales de que microservicios SUMAN valor
+
+- Equipos independientes que necesitan deployar sin coordinación
+- Módulos con requerimientos de escalado MUY distintos
+- Diferentes requerimientos de seguridad o cumplimiento por módulo
+- Módulos que necesitan tecnologías distintas (Python para ML, Go para performance)
+- Más de 100 deploys por mes
+
+---
+
+## 2. Principios de Diseño de Servicios
+
+### Bounded Context — Límites claros entre servicios
+
+```
+MONOLITO MODULAR (recomendado para empezar):
++-- modulo: empleados/
++-- modulo: nomina/
++-- modulo: asistencia/
++-- modulo: reportes/
+
+MICROSERVICIOS (cuando los módulos necesitan escalar independientemente):
++-- servicio-empleados     — equipo A, escala: bajo
++-- servicio-nomina        — equipo B, escala: muy alto en quincena
++-- servicio-asistencia    — equipo C, escala: alto en horario laboral
++-- servicio-reportes      — equipo D, escala: bajo, alto en auditorías
+```
+
+### High Cohesion, Loose Coupling
+
+```python
+# MAL: servicio que hace demasiado (god service)
+class ServicioRRHH:
+    def crear_empleado(self): ...
+    def calcular_nomina(self): ...
+    def registrar_asistencia(self): ...
+
+# BIEN: servicios con responsabilidad única
+class ServicioEmpleados:
+    def crear(self): ...
+    def actualizar(self): ...
+    def buscar(self): ...
+```
+
+---
+
+## 3. Reglas Obligatorias
+
+1. **Cada servicio tiene su propia BD** — NUNCA compartir esquemas entre servicios.
+2. **SIEMPRE implementar circuit breaker** para llamadas a otros servicios.
+3. **SIEMPRE propagar `X-Correlation-ID`** en todas las llamadas salientes.
+4. **SIEMPRE poner timeout** en TODAS las llamadas HTTP salientes.
+5. **SIEMPRE implementar idempotency** en operaciones de escritura.
+6. **Exponer health checks**: `/health/live`, `/health/ready`, `/health/startup`.
+7. **Logs estructurados (JSON)** con nivel, servicio y correlationId.
+
+---
+
+## 4. Anti-patrones Críticos
+
+### Monolito Distribuido (el peor anti-patrón)
+
+```
+Síntomas:
+- Los servicios se llaman síncronamente en cadena para cada request
+- Deploy de un servicio requiere deploy de otros (acoplamiento)
+- Un fallo en el servicio A causa fallo en cascada a B, C, D
+- La "base de datos compartida" entre servicios
+
+MAL:
+Request -> API Gateway -> ServicioA -> ServicioB -> ServicioC -> BD compartida
+
+BIEN:
+Request -> API Gateway -> ServicioA (BD propia)
+                       -> (evento async) -> ServicioB (BD propia)
+```
+
+### Otros Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|-------------|---------|---------|
+| Chatty services (100s de llamadas síncronas) | Latencia acumulada | Agregar datos en el servicio o usar eventos |
+| Compartir BD entre servicios | Acoplamiento fuerte | Una BD por servicio |
+| Servicios demasiado pequeños (nanoservices) | Overhead operativo excesivo | Bounded context adecuado |
+| Sin contrato de API versionado | Romper clientes al actualizar | Versioning en URL (/v1/, /v2/) |
+| Logging sin correlation ID | Imposible tracing | `X-Correlation-ID` en headers |
+| Sin idempotency en APIs | Doble procesamiento en reintentos | Idempotency keys en mutaciones |
+
+---
+
+## 5. Checklist de Microservicio Nuevo
+
+- [ ] Tiene su propia BD (sin compartir esquemas con otros servicios)
+- [ ] Expone `/health/live`, `/health/ready`, `/health/startup`
+- [ ] Implementa circuit breaker para llamadas a otros servicios
+- [ ] Propaga `X-Correlation-ID` en todas las llamadas salientes
+- [ ] Tiene contrato de API documentado (OpenAPI spec)
+- [ ] Versioning en URL (`/api/v1/...`)
+- [ ] Idempotency implementada en operaciones de escritura
+- [ ] Rate limiting configurado en el API Gateway
+- [ ] Timeout configurado en TODAS las llamadas HTTP salientes
+- [ ] Logs estructurados (JSON) con nivel, servicio, correlationId
+- [ ] Métricas de negocio expuestas (Prometheus)
+- [ ] Fallback o degradación elegante cuando dependencias fallan
+
+---
+
+Para ejemplos completos de API Gateway (NGINX), Circuit Breaker, Saga Pattern, Distributed Tracing (OpenTelemetry), Health Checks y Service Discovery (Consul), ver [recursos/patrones-y-ejemplos-completos.md](recursos/patrones-y-ejemplos-completos.md).
+
+## Gotchas / Errores comunes no obvios
+
+**Circuit breaker con estado en memoria del proceso no funciona en entornos multi-instancia**: si el circuit breaker abre en una instancia del servicio (por fallos detectados localmente), las otras instancias siguen enviando tráfico al servicio caído. Causa: el estado del circuit breaker en memoria es local al proceso. Fix: usar un circuit breaker respaldado por Redis o un service mesh (Istio, Linkerd) que administra el estado de circuit breaking a nivel de red, compartido entre todas las instancias.
+
+**Saga con compensación no es equivalente a rollback de base de datos — los efectos secundarios ya ocurrieron**: en una Saga coreografada donde el paso 3 (envío de email) falla, la compensación no "no envía el email" — el email ya se envió en paso 1. La compensación solo puede enviar otro email que diga "la operación fue cancelada". Causa: la Saga es eventual y los pasos intermedios son commits locales irreversibles. Fix: diseñar las compensaciones como acciones de negocio válidas (no rollbacks), documentar explícitamente qué efectos no son compensables (emails enviados, notificaciones push) y diseñar el flujo de negocio para tolerar esos efectos.
+
+**`X-Correlation-ID` propagado solo en llamadas HTTP se pierde cuando el flujo pasa por un queue (RabbitMQ, Kafka)**: si el servicio A llama al servicio B por HTTP con correlation ID y B publica un evento en Kafka sin incluir el correlation ID en el header del mensaje, el servicio C que consume el evento no puede correlacionar la traza. Causa: los mensajes async no propagan headers HTTP automáticamente. Fix: incluir el correlation ID en el payload del mensaje (o en los headers del mensaje de Kafka/RabbitMQ) como parte del contrato del evento, y extraerlo al crear el span de OpenTelemetry al consumir.
+
+**El health check `/health/ready` que verifica la conexión a la BD puede causar restart en cascada**: si `/health/ready` falla cuando la BD tiene alta latencia (no caída), Kubernetes puede marcar el pod como unhealthy y reiniciarlo — pero el restart no resuelve el problema de latencia de BD y puede generar una cascada de reinicios. Causa: usar el health check de readiness para métricas de performance, no solo de disponibilidad. Fix: `/health/ready` debe verificar solo si el servicio puede aceptar tráfico (conexión básica a BD disponible), no la latencia — las métricas de performance van en el health de Prometheus/métricas, no en el readiness probe.

package/habilidades/microservicios/recursos/patrones-y-ejemplos-completos.md

@@ -0,0 +1,325 @@
+# Microservicios — Patrones y Ejemplos Completos
+
+Referencia extendida de la skill `microservicios`. Contiene ejemplos de implementación
+completos para API Gateway, Circuit Breaker, Saga Pattern, Distributed Tracing,
+Health Checks y Service Discovery.
+
+---
+
+## API Gateway — Configuración NGINX
+
+```python
+# Kong, AWS API Gateway, o NGINX como gateway
+# Responsabilidades del gateway:
+# 1. Autenticación/autorización centralizada
+# 2. Rate limiting
+# 3. Request routing
+# 4. SSL termination
+# 5. Logging y métricas
+# 6. Transformación de requests (versioning)
+
+# Configuración NGINX como API Gateway básico
+# nginx.conf
+upstream servicio_empleados {
+    server empleados-svc:8001;
+    keepalive 32;
+}
+
+upstream servicio_nomina {
+    server nomina-svc:8002;
+    keepalive 32;
+}
+
+server {
+    listen 443 ssl;
+    server_name api.empresa.com.mx;
+
+    # Autenticación JWT en el gateway (todas las rutas protegidas)
+    auth_jwt "API RRHH";
+    auth_jwt_key_file /etc/nginx/jwt_public_key.pem;
+
+    location /api/v1/empleados/ {
+        proxy_pass http://servicio_empleados/;
+        proxy_set_header X-User-ID $jwt_claim_sub;
+        proxy_set_header X-User-Roles $jwt_claim_roles;
+    }
+
+    location /api/v1/nomina/ {
+        proxy_pass http://servicio_nomina/;
+        limit_req zone=nomina_zone burst=20 nodelay;   # Rate limiting
+    }
+}
+```
+
+---
+
+## Circuit Breaker — Implementación completa
+
+```python
+# pip install circuitbreaker
+from circuitbreaker import circuit, CircuitBreakerError
+import httpx
+import asyncio
+
+class ClienteServicioEmpleados:
+    def __init__(self, base_url: str):
+        self.base_url = base_url
+        self._client = httpx.AsyncClient(timeout=5.0)
+
+    @circuit(
+        failure_threshold=5,      # Abrir después de 5 fallos consecutivos
+        recovery_timeout=30,      # Intentar recuperar después de 30s
+        expected_exception=httpx.RequestError,
+    )
+    async def obtener_empleado(self, empleado_id: str) -> dict:
+        """
+        Estados del circuit breaker:
+        - CLOSED: tráfico normal
+        - OPEN: rechaza requests (fallback inmediato)
+        - HALF-OPEN: prueba un request para ver si el servicio se recuperó
+        """
+        response = await self._client.get(
+            f"{self.base_url}/empleados/{empleado_id}"
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def obtener_empleado_con_fallback(self, empleado_id: str) -> dict:
+        try:
+            return await self.obtener_empleado(empleado_id)
+        except CircuitBreakerError:
+            return await self._obtener_de_cache(empleado_id)
+        except httpx.RequestError as e:
+            raise ServicioNoDisponible(f"Servicio de empleados inaccesible: {e}")
+
+    async def _obtener_de_cache(self, empleado_id: str) -> dict:
+        datos = await redis.get(f"empleado:{empleado_id}")
+        if datos:
+            return json.loads(datos)
+        raise DatosNoEnCache(f"Empleado {empleado_id} no en caché")
+```
+
+---
+
+## Saga Pattern — Transacciones distribuidas (Orquestación)
+
+```python
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable, Awaitable
+
+class EstadoSaga(str, Enum):
+    INICIADA = "INICIADA"
+    COMPLETADA = "COMPLETADA"
+    FALLIDA = "FALLIDA"
+    COMPENSANDO = "COMPENSANDO"
+
+@dataclass
+class PasoSaga:
+    nombre: str
+    ejecutar: Callable[..., Awaitable[dict]]
+    compensar: Callable[..., Awaitable[None]]
+
+class SagaAltaDeEmpleado:
+    """
+    Saga para el alta de un nuevo empleado.
+    Pasos:
+    1. Crear expediente en BD central
+    2. Configurar nómina en SAP
+    3. Crear cuenta en Active Directory
+    4. Enviar correo de bienvenida
+    """
+
+    def __init__(
+        self,
+        svc_expedientes,
+        svc_nomina,
+        svc_directorio,
+        svc_notificaciones,
+    ):
+        self._pasos = [
+            PasoSaga(
+                nombre="crear_expediente",
+                ejecutar=svc_expedientes.crear,
+                compensar=svc_expedientes.eliminar,
+            ),
+            PasoSaga(
+                nombre="configurar_nomina",
+                ejecutar=svc_nomina.configurar_empleado,
+                compensar=svc_nomina.eliminar_empleado,
+            ),
+            PasoSaga(
+                nombre="crear_cuenta_directorio",
+                ejecutar=svc_directorio.crear_cuenta,
+                compensar=svc_directorio.desactivar_cuenta,
+            ),
+            PasoSaga(
+                nombre="enviar_bienvenida",
+                ejecutar=svc_notificaciones.enviar_bienvenida,
+                compensar=lambda **_: None,
+            ),
+        ]
+
+    async def ejecutar(self, datos_empleado: dict) -> dict:
+        resultados: list[dict] = []
+        ejecutados: list[tuple[PasoSaga, dict]] = []
+
+        for paso in self._pasos:
+            try:
+                resultado = await paso.ejecutar(**datos_empleado, **{
+                    f"resultado_{p.nombre}": r for p, r in ejecutados
+                })
+                resultados.append(resultado)
+                ejecutados.append((paso, resultado))
+            except Exception as e:
+                await self._compensar(ejecutados[::-1], datos_empleado)
+                raise SagaFallida(
+                    f"Saga falló en paso '{paso.nombre}': {e}"
+                ) from e
+
+        return {"resultados": resultados}
+
+    async def _compensar(
+        self,
+        pasos_ejecutados: list[tuple[PasoSaga, dict]],
+        datos: dict,
+    ) -> None:
+        for paso, resultado in pasos_ejecutados:
+            try:
+                await paso.compensar(**datos, resultado_previo=resultado)
+            except Exception as e:
+                logger.error("Error compensando %s: %s", paso.nombre, e)
+```
+
+---
+
+## Distributed Tracing — OpenTelemetry
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.jaeger.thrift import JaegerExporter
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
+
+def configurar_tracing(servicio: str, jaeger_host: str = "jaeger") -> None:
+    provider = TracerProvider()
+    jaeger_exporter = JaegerExporter(
+        agent_host_name=jaeger_host,
+        agent_port=6831,
+    )
+    provider.add_span_processor(BatchSpanProcessor(jaeger_exporter))
+    trace.set_tracer_provider(provider)
+
+    FastAPIInstrumentor.instrument()
+    HTTPXClientInstrumentor.instrument()
+    SQLAlchemyInstrumentor.instrument()
+
+tracer = trace.get_tracer(__name__)
+
+async def calcular_nomina_quincenal(periodo_id: str) -> dict:
+    with tracer.start_as_current_span("calcular_nomina_quincenal") as span:
+        span.set_attribute("periodo.id", periodo_id)
+
+        with tracer.start_as_current_span("obtener_empleados_activos"):
+            empleados = await repo.obtener_empleados_activos()
+            span.set_attribute("empleados.count", len(empleados))
+
+        with tracer.start_as_current_span("calcular_percepciones"):
+            percepciones = await calcular_percepciones(empleados)
+
+        span.set_attribute("nomina.total", sum(p["total"] for p in percepciones))
+        return {"periodo_id": periodo_id, "percepciones": percepciones}
+```
+
+---
+
+## Health Checks — 3 endpoints estándar
+
+```python
+from fastapi import APIRouter
+from sqlalchemy.ext.asyncio import AsyncSession
+
+router = APIRouter()
+
+@router.get("/health/live")
+async def liveness():
+    """
+    Kubernetes liveness probe.
+    Responde 200 si el proceso está vivo.
+    NUNCA verificar dependencias externas aquí.
+    """
+    return {"status": "alive"}
+
+@router.get("/health/ready")
+async def readiness(db: AsyncSession = Depends(get_db)):
+    """
+    Kubernetes readiness probe.
+    Verifica dependencias críticas.
+    """
+    checks = {}
+    try:
+        await db.execute(text("SELECT 1"))
+        checks["database"] = "ok"
+    except Exception as e:
+        checks["database"] = f"error: {e}"
+
+    try:
+        await redis.ping()
+        checks["cache"] = "ok"
+    except Exception as e:
+        checks["cache"] = f"error: {e}"
+
+    todo_ok = all(v == "ok" for v in checks.values())
+    return JSONResponse(
+        content={"status": "ready" if todo_ok else "not_ready", "checks": checks},
+        status_code=200 if todo_ok else 503,
+    )
+
+@router.get("/health/startup")
+async def startup_probe():
+    """
+    Kubernetes startup probe.
+    Permite más tiempo para servicios con arranque lento.
+    """
+    head_revision = await obtener_revision_actual_db()
+    expected_revision = get_alembic_head()
+    if head_revision != expected_revision:
+        raise HTTPException(503, "Migraciones pendientes")
+    return {"status": "started", "revision": head_revision}
+```
+
+---
+
+## Service Discovery — Consul
+
+```python
+import consul
+
+class RegistroServicios:
+    def __init__(self):
+        self._consul = consul.aio.Consul(host="consul", port=8500)
+
+    async def registrar(self, nombre: str, puerto: int, tags: list[str]) -> None:
+        await self._consul.agent.service.register(
+            name=nombre,
+            service_id=f"{nombre}-{os.environ['HOSTNAME']}",
+            address=os.environ["POD_IP"],
+            port=puerto,
+            tags=tags,
+            check=consul.Check.http(
+                f"http://{os.environ['POD_IP']}:{puerto}/health/ready",
+                interval="10s",
+                deregister="30s",
+            ),
+        )
+
+    async def descubrir(self, nombre: str) -> str:
+        _, servicios = await self._consul.health.service(nombre, passing=True)
+        if not servicios:
+            raise ServicioNoDisponible(f"No hay instancias de '{nombre}'")
+        servicio = servicios[0]["Service"]
+        return f"http://{servicio['Address']}:{servicio['Port']}"
+```