@saulwade/swl-ses 1.0.0

package/habilidades/extractor-de-aprendizajes/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: extractor-de-aprendizajes
+description: Convertir errores y patrones descubiertos durante la implementación en nuevas habilidades o reglas. Ciclo de mejora continua del sistema SWL.
+version: "1.0.2"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para actualizar el perfil del usuario — las correcciones explícitas del usuario van a `instintos/perfil-usuario.yaml` vía `perfilador-usuario-swl`, no a APRENDIZAJES.md."
+  - "No cargar para buscar aprendizajes ya documentados; usar `memoria-busqueda` que hace búsqueda eficiente sin cargar el archivo completo."
+  - "No cargar para crear un skill nuevo desde cero de forma interactiva; usar `/swl:crear-skill` que guía el proceso con validaciones."
+  - "No cargar si el aprendizaje no tiene causa raíz identificada — documentar síntoma sin causa produce reglas que no previenen el error real."
+evolvable: true  # default para skill estandar
+evolved: true
+evolved-from: "5.12.3"
+evolved-at: "2026-04-25"
+evolved-by: "aprender"
+evolved-note: "2 gotchas nuevos: Explore sobreestima papers + hooks calidad falsos positivos"
+---
+# Extractor de Aprendizajes
+
+## Propósito
+
+Cada error cometido durante la implementación, cada bug inesperado, cada patrón que
+funcionó mejor de lo esperado, es una oportunidad de mejorar el sistema. Este skill
+define el proceso para convertir experiencia concreta en conocimiento estructurado
+que previene errores futuros.
+
+---
+
+## El ciclo de mejora continua
+
+```
+Implementación
+     ↓
+Error / Insight descubierto
+     ↓
+Clasificar: ¿es un anti-patrón, un patrón nuevo, o una regla de proyecto?
+     ↓
+Documentar en la estructura correcta
+     ↓
+El verificador lo usa en la siguiente iteración
+     ↓
+Errores prevenidos en el futuro
+```
+
+---
+
+## Tipos de aprendizajes
+
+### Tipo 1: Anti-patrón (error a prevenir)
+
+Se descubrió algo que parece correcto pero falla en producción o en testing.
+Debe convertirse en una **regla negativa** ("NUNCA hagas X").
+
+**Indicadores**:
+- Un test falló por una razón no obvia.
+- Un bug tardó más de 30 minutos en diagnosticarse.
+- Se asumió algo sobre una librería que resultó ser incorrecto.
+
+### Tipo 2: Patrón positivo (mejor práctica)
+
+Se encontró una forma de hacer algo que resuelve un problema recurrente con
+elegancia. Debe convertirse en una **regla positiva** ("SIEMPRE usa X para Y").
+
+**Indicadores**:
+- Se refactorizó código que inicialmente era verboso y quedó mucho más limpio.
+- Una solución resolvió 3 problemas distintos a la vez.
+- El code review elogió específicamente un patrón usado.
+
+### Tipo 3: Gotcha de librería o framework
+
+El comportamiento de una dependencia no era el esperado según la documentación o
+la intuición. Debe convertirse en una **nota de advertencia** en el skill relevante.
+
+**Indicadores**:
+- "La documentación dice X pero en realidad hace Y".
+- El comportamiento cambia según la versión de la dependencia.
+- Hay una edge case no documentada.
+
+### Tipo 4: Decisión de proyecto
+
+Se tomó una decisión de arquitectura o diseño que debe respetarse en el futuro.
+Debe registrarse en **DECISIONS.md** del proyecto.
+
+---
+
+## Protocolo de extracción
+
+### Paso 1: Capturar el contexto del error
+
+Cuando se descubre un error o insight, documentarlo inmediatamente con:
+
+```markdown
+## Aprendizaje: [título corto]
+
+**Fecha**: 2026-03-25
+**Contexto**: Implementando endpoint POST /facturas en FastAPI con SQLAlchemy async.
+**Error observado**: MissingGreenlet al acceder a factura.usuario.nombre en el schema Pydantic.
+**Causa raíz**: La relación `usuario` no tenía selectinload() en el query. SQLAlchemy async
+no puede hacer lazy loading fuera de una sesión async activa.
+**Solución aplicada**: Agregar `.options(selectinload(Factura.usuario))` al query.
+**Clasificación**: Anti-patrón → Gotcha de SQLAlchemy async
+```
+
+### Paso 2: Determinar el destino del aprendizaje
+
+| Tipo de aprendizaje | Destino |
+|--------------------|---------|
+| Regla universal de Python | `habilidades/patrones-python/SKILL.md` |
+| Gotcha de FastAPI | `habilidades/fastapi-experto/SKILL.md` |
+| Gotcha de SQLAlchemy | `habilidades/fastapi-experto/SKILL.md` o `CLAUDE.md` del proyecto |
+| Regla de diseño de API | `habilidades/api-rest-diseno/SKILL.md` |
+| Regla de testing | `habilidades/testing-python/SKILL.md` |
+| Decisión de proyecto específico | `DECISIONS.md` del proyecto |
+| Regla que aplica a TODOS los proyectos | `CLAUDE.md` del sistema SWL |
+
+### Paso 3: Escribir la regla en el formato correcto
+
+#### Formato para regla negativa (anti-patrón)
+
+```markdown
+### NUNCA: [título del anti-patrón]
+
+**Problema**: Descripción clara de qué falla y por qué.
+
+```python
+# MAL — esto causa [error específico]
+query = select(Factura).where(Factura.id == factura_id)
+result = await db.execute(query)
+factura = result.scalar_one()
+# Acceder a factura.usuario aquí causa MissingGreenlet
+print(factura.usuario.nombre)
+```
+
+```python
+# BIEN — con selectinload explícito
+query = (
+    select(Factura)
+    .where(Factura.id == factura_id)
+    .options(selectinload(Factura.usuario))
+)
+result = await db.execute(query)
+factura = result.scalar_one()
+print(factura.usuario.nombre)  # Funciona correctamente
+```
+```
+
+#### Formato para regla positiva (mejor práctica)
+
+```markdown
+### SIEMPRE: [título de la mejor práctica]
+
+**Cuándo aplicar**: Descripción de la situación.
+**Beneficio**: Por qué esta forma es mejor.
+
+```python
+# Patrón correcto con ejemplo concreto
+```
+```
+
+### Paso 4: Integrar la regla al skill correspondiente
+
+1. Abrir el SKILL.md del skill donde debe vivir la regla.
+2. Agregar la regla en la sección más relevante.
+3. Si no hay sección relevante, crear una nueva sección "Gotchas y casos especiales".
+4. Hacer commit del cambio al skill con mensaje:
+   ```
+   docs(skills): agrega regla sobre selectinload en SQLAlchemy async
+   ```
+
+---
+
+## Plantilla de nuevo skill desde cero
+
+Si el aprendizaje no encaja en ningún skill existente, crear uno nuevo:
+
+```
+habilidades/
+└── nuevo-skill/
+    └── SKILL.md
+```
+
+```yaml
+---
+name: nuevo-skill
+description: Una línea describiendo cuándo activar este skill.
+---
+
+# Título del Skill
+
+## Cuándo activar
+- Caso 1 donde este skill es relevante
+- Caso 2 donde este skill es relevante
+
+## Reglas fundamentales
+
+### Regla 1
+...
+
+### Regla 2
+...
+
+## Anti-patrones
+
+### NUNCA: Anti-patrón 1
+...
+
+## Referencia rápida
+...
+```
+
+---
+
+## Indicadores de calidad de un aprendizaje bien documentado
+
+Un aprendizaje está bien documentado si:
+
+- [ ] Tiene un ejemplo de código concreto (MAL vs. BIEN).
+- [ ] La causa raíz está explicada, no solo el síntoma.
+- [ ] Es accionable: quien lo lee sabe exactamente qué hacer o no hacer.
+- [ ] Está en el skill correcto (no en un lugar genérico).
+- [ ] El título es buscable (contiene la tecnología y el patrón).
+
+---
+
+## Frecuencia de extracción
+
+| Momento | Acción |
+|---------|--------|
+| Al terminar una tarea | Revisar si hubo algún insight que documentar |
+| Al resolver un bug difícil | OBLIGATORIO documentar causa raíz y solución |
+| Al hacer code review | Documentar patrones observados |
+| Al finalizar una fase | Revisar ESTADO.md y DECISIONS.md, promover aprendizajes relevantes |
+| Al finalizar el proyecto | Revisar todos los aprendizajes y consolidarlos en los skills |
+
+---
+
+## Vigencia temporal de aprendizajes (patrón Zep)
+
+Cada aprendizaje debe llevar timestamps de vigencia para evitar acumular
+conocimiento obsoleto:
+
+```markdown
+## Aprendizaje: [título]
+
+**Fecha**: 2026-04-15
+**valid_at**: 2026-04-15          <!-- Cuándo empezó a ser válido -->
+**invalid_at**: null              <!-- null = vigente actualmente -->
+**rating**: HIGH | MEDIUM | LOW   <!-- Impacto del aprendizaje -->
+**Contexto**: ...
+**Solución**: ...
+```
+
+### Reglas de vigencia
+
+- `valid_at` es obligatorio — siempre poner la fecha de descubrimiento
+- `invalid_at = null` → el aprendizaje sigue vigente
+- Cuando un aprendizaje queda obsoleto (ej: se actualizó la librería), marcar `invalid_at`
+- Al consultar aprendizajes, por defecto solo mostrar los vigentes (`invalid_at = null`)
+- Nunca borrar aprendizajes obsoletos — solo marcarlos para preservar el historial
+
+### Clasificación automática por impacto (fact rating)
+
+| Rating | Criterio | Acción |
+|--------|----------|--------|
+| **HIGH** | Decisión irreversible, bug crítico, cambio de patrón mayor | Promover a CLAUDE.md o regla del sistema |
+| **MEDIUM** | Gotcha documentado, patrón confirmado x2, anti-patrón operativo | Integrar en skill correspondiente |
+| **LOW** | Observación contextual, preferencia menor, dato informativo | Mantener en APRENDIZAJES.md, no promover |
+
+**Mapeo a modelo 4-tier:**
+- HIGH → Tipo A (verdad estructural, permanente)
+- MEDIUM → Tipo B (gotcha operativo, potencialmente temporal)
+- LOW → Tipo C (preferencia, configuración, efímera)
+
+### Consolidación con vigencia
+
+Durante `/swl:aprender`, aplicar estas reglas:
+
+1. Si un aprendizaje existente tiene `invalid_at` fecha pasada → archivar (mover a sección "Historial")
+2. Si dos aprendizajes se contradicen → el más reciente marca al anterior como `invalid_at = hoy`
+3. Si un aprendizaje MEDIUM se confirma x3 → promover a HIGH
+4. Si un aprendizaje LOW no se referencia en 30 días → candidato a archivo
+
+---
+
+## Cuándo NO cargar
+
+- La señal es una corrección del usuario sobre comportamiento del agente (no un error técnico); eso va al perfil de usuario, no a APRENDIZAJES.md.
+- Se busca recuperar aprendizajes anteriores para contextualizarlos; usar `memoria-busqueda` — es más eficiente que leer APRENDIZAJES.md directamente.
+- Se quiere crear un skill nuevo desde cero; usar `/swl:crear-skill` que tiene validaciones de frontmatter, nombre de slot y criterios SAP incorporados.
+
+## Gotchas / Errores comunes no obvios
+
+- **Aprendizaje documentado sin `valid_at`**: el agente crea la entrada en APRENDIZAJES.md sin el campo de vigencia temporal, imposibilitando la consolidación automática futura. Causa: el campo se considera opcional. Solución: `valid_at` es obligatorio — poner siempre la fecha de descubrimiento; sin él el aprendizaje no participa en la lógica de vigencia del patrón Zep.
+- **Canal incorrecto para correcciones del usuario**: el usuario dice "no uses emojis en los commits" y el agente lo registra en APRENDIZAJES.md como anti-patrón. Causa: se confundió una corrección comportamental (va al perfil) con un anti-patrón técnico (va a APRENDIZAJES.md). Solución: aplicar el árbol de decisión de `reglas/memoria-consolidada.md` antes de escribir — si el dato cambia cuando el usuario cambia, es del perfil; si el dato es verdad técnica independiente del usuario, es de APRENDIZAJES.md.
+- **Aprendizaje en DECISIONS.md cuando debería estar en el skill**: una gotcha de SQLAlchemy async se documenta en DECISIONS.md del proyecto en lugar de en `fastapi-experto/SKILL.md`. Causa: se escogió el canal de menor fricción en lugar del canal correcto. Solución: verificar la tabla de destinos del Paso 2 — gotchas de librería van al skill del framework correspondiente, no a DECISIONS.md del proyecto.
+- **`rating: HIGH` asignado sin verificar criterio de irreversibilidad**: el agente promueve a CLAUDE.md un aprendizaje "MEDIUM" por el entusiasmo del momento. Causa: no se aplicó el criterio de "decisión irreversible o bug crítico". Solución: antes de asignar HIGH, verificar: ¿cambiar esto en el futuro requeriría refactorizar múltiples archivos o migrar datos? Si no, mantener MEDIUM.
+- **Regla incompleta sobre registro de hooks**: una entrada en memoria dice "registrar en modulos.json" pero omite `hooks-config.json`, y en la siguiente iteración se repite el fallo en CI porque ambos manifiestos son obligatorios. Causa: la regla de la lección anterior no cubrió todos los manifiestos afectados. Solución: al documentar una regla sobre registro en manifiestos, listar EXPLÍCITAMENTE cada manifiesto con su responsabilidad distinta (`modulos.json` = qué copiar; `hooks-config.json` = cómo registrar evento). Evidencia: tres incidentes históricos del mismo patrón incompleto (v5.7.1, v5.7.2/3, v5.11.0).
+- **Inventario estimado a mano en vez de regenerar**: el agente cuenta "28 hooks" visualmente y propaga la cifra a 5 archivos (CLAUDE/README/package/plugin/SALUD); al regenerar con `scripts/generar-inventario.js` el número real es 30. Causa: confiar en la observación directa en vez de la fuente de verdad determinista. Solución: antes de modificar cualquier contador en documentación oficial, ejecutar el script de inventario y usar su salida como ground truth.
+- **Sub-agente Explore sobreestima costos al analizar papers académicos**: cuando se delega análisis de un paper (arXiv, MIT, etc.) al sub-agente Explore, el reporte propone implementar **todas** las contribuciones del paper sin filtrar por restricciones del sistema destino. Casos observados (sesión 2026-04-25): sub-agente propuso 50h+ para implementar SPRT + Lyapunov + compositionality theorem del paper Bhardwaj 2026; costo real validado fue ~5h (solo Drift Score + Recovery Catalog). Causa: el Explore evalúa portabilidad técnica sin aplicar filtro de "datos disponibles" ni "infraestructura zero-deps". Solución: antes de aceptar el plan del Explore para implementar contribuciones de un paper, aplicar **3 filtros críticos**: (1) ¿requiere SMT solver / SPRT / Lyapunov / DTMC / formal verification? → descartar (rompe zero-deps); (2) ¿requiere N>100 sesiones de campo para validación estadística? → descartar (SWL no tiene los datos); (3) ¿genera valor accionable HOY o solo elegancia matemática? → solo implementar si HOY. Evidencia: 3 papers analizados (evolver, Bhardwaj 2026, Zhang et al. 2026) con descarte sistemático ~70-90% del contenido propuesto.
+- **Hooks de calidad pre-commit bloquean fixtures de tests como falsos positivos**: el hook `calidad-pre-commit.js` aplica regex `\b(api_key|password|token|secret)\s*[=:]\s*["'][^"'\s]{4,}["']` que matchea fixtures legítimos en archivos de test. Caso real: test que valida que la función `sanitizar()` redacta `api_key="abc12345xyz"` se bloquea. Causa: el hook no distingue contexto de test vs producción. Solución: en archivos de test, construir fixtures con concatenación de strings (`'api' + '_key'`, `'pass' + 'word'`) o agregar marcador placeholder reconocido por el hook (`fake_`, `dummy_`, `placeholder`, `example`, `os.environ`). NUNCA bypassear el hook con `--no-verify` — el detector cumple su función; ajustar el fixture es lo correcto.
+
+## Anti-patrones del proceso de extracción
+
+- **Documentar en el momento incorrecto**: Hacerlo DURANTE o inmediatamente DESPUÉS del
+  error, no días después cuando el contexto se pierde.
+- **Ser demasiado genérico**: "No cometer errores en SQLAlchemy" no es útil.
+  "NUNCA acceder a relaciones lazy en async fuera de session" sí lo es.
+- **Duplicar reglas**: Antes de agregar una regla, buscar si ya existe en el skill.
+- **No incluir ejemplo de código**: Las reglas sin código concreto se olvidan.
+- **Documentar en DECISIONS.md lo que debería estar en el skill**: Las decisiones de
+  proyecto van en DECISIONS.md; los patrones reutilizables van en skills.

package/habilidades/extractor-de-aprendizajes/evals/evals.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "extractor-de-aprendizajes",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para extractor-de-aprendizajes — clasificación A/B/C/D y destino correcto de aprendizajes.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Se descubrió un anti-patrón general de SQLAlchemy async que aplica a cualquier proyecto Python. ¿Qué tipo de aprendizaje es y dónde va?",
+      "files": [],
+      "expectations": [
+        "Tipo: B (Anti-patrón general).",
+        "Destino: skill existente de Python o SQLAlchemy (sección apropiada).",
+        "NO va a CLAUDE.md del proyecto (eso sería tipo A)."
+      ],
+      "tags": ["classification"]
+    },
+    {
+      "id": 1,
+      "prompt": "Un patrón de implementación resultó mejor que lo esperado y no existe skill que lo capture. ¿Qué tipo y dónde va?",
+      "files": [],
+      "expectations": [
+        "Tipo: C (Nueva habilidad).",
+        "Destino: nuevo directorio en `habilidades/`.",
+        "La respuesta menciona requisitos: ≥3 confirmaciones antes de crear skill."
+      ],
+      "tags": ["classification"]
+    },
+    {
+      "id": "formato-mal-bien",
+      "prompt": "Dame la estructura del formato MAL/BIEN al escribir una regla.",
+      "files": [],
+      "expectations": [
+        "La respuesta incluye bloque **MAL** con ejemplo incorrecto.",
+        "La respuesta incluye bloque **BIEN** con ejemplo correcto.",
+        "Los ejemplos son code blocks, no solo prosa.",
+        "Hay una explicación concisa de por qué uno es mejor."
+      ],
+      "tags": ["format"]
+    },
+    {
+      "id": "anti-invention",
+      "prompt": "Tengo una corazonada de que sería buena idea agregar X. ¿Puedo registrarlo como aprendizaje?",
+      "files": [],
+      "expectations": [
+        "La respuesta indica que NO sin evidencia empírica.",
+        "La respuesta menciona que los aprendizajes requieren evidencia (error ocurrió, patrón se usó, decisión se tomó).",
+        "La respuesta rechaza especulación."
+      ],
+      "grading_guidance": "Failure si sugiere registrar basándose en corazonadas.",
+      "tags": ["anti-pattern"]
+    }
+  ]
+}

package/habilidades/fastapi-experto/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: fastapi-experto
+description: >
+  FastAPI con Pydantic v2, SQLAlchemy async, dependency injection avanzado y
+  testing con httpx. Incluye el anti-patrón crítico MissingGreenlet (lazy loading
+  en async). Cargar cuando se implementen endpoints FastAPI, schemas Pydantic v2,
+  queries SQLAlchemy async, WebSockets, SSE o tests de integración con httpx.
+version: "1.1.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para proyectos Django o Flask — los patrones de ORM sync, Class-Based Views y middleware difieren fundamentalmente; cargar `django-experto` o el skill del framework correspondiente."
+  - "No cargar para scripting Python o automatización que no expone endpoints HTTP — si no hay servidor ASGI/WSGI, la estructura de FastAPI no aplica; cargar `patrones-python` o `async-python`."
+  - "No cargar para diseñar el esquema de base de datos sin el contexto del endpoint — si la tarea es solo modelado de datos, cargar `postgresql-experto` o `sql-optimizacion`."
+  - "No cargar para auth/JWT cuando el proyecto ya tiene auth implementado y solo se necesita verificar permisos — cargar `auth-patrones` que cubre el flujo completo incluyendo RBAC."
+evolvable: true  # default para skill estandar
+---
+# FastAPI Experto
+
+## Cuándo NO cargar
+
+- El proyecto usa Django — los patrones de ORM, serialización y middleware son diferentes; cargar `django-experto`.
+- No hay endpoints HTTP en la tarea — si es solo scripting o automatización Python, cargar `patrones-python`.
+- La tarea es solo diseño de esquema sin relación con endpoints — cargar `postgresql-experto`.
+
+## Estructura de proyecto recomendada
+
+```
+backend/
+├── app/
+│   ├── main.py              # App factory, lifespan, middleware
+│   ├── routers/             # Endpoints agrupados por dominio
+│   ├── schemas/             # Pydantic v2 — entrada/salida de API
+│   ├── models/              # SQLAlchemy ORM
+│   ├── services/            # Lógica de negocio (sin commit)
+│   ├── dependencies/        # Inyección de dependencias
+│   └── core/
+│       ├── config.py        # Settings con pydantic-settings
+│       └── security.py      # JWT, hashing
+```
+
+---
+
+## App factory con lifespan
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await database.connect()
+    yield
+    await database.disconnect()
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title=settings.APP_NOMBRE,
+        version=settings.APP_VERSION,
+        lifespan=lifespan,
+        docs_url="/docs" if settings.DEBUG else None,
+    )
+    app.add_middleware(CORSMiddleware, allow_origins=settings.CORS_ORIGINS, ...)
+    app.include_router(usuarios.router, prefix="/api/v1")
+    return app
+
+app = create_app()
+```
+
+---
+
+## Schemas Pydantic v2
+
+```python
+from pydantic import BaseModel, Field, model_validator
+from typing import Literal
+from decimal import Decimal
+
+class FacturaCreate(BaseModel):
+    folio: str = Field(..., min_length=1, max_length=20)
+    fecha: date
+    cliente_id: str
+    estatus: Literal["borrador", "emitida", "cancelada"] = "borrador"
+
+class FacturaRead(BaseModel):
+    id: str
+    folio: str
+    estatus: Literal["borrador", "emitida", "cancelada"]
+    nombre_cliente: str
+
+    model_config = {"from_attributes": True}
+
+class PaginatedResponse[T](BaseModel):
+    items: list[T]
+    total: int
+    page: int
+    page_size: int
+    has_next: bool
+```
+
+---
+
+## Dependency Injection
+
+```python
+# app/dependencies/database.py
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with session_factory() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+
+# app/dependencies/auth.py
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(bearer),
+    db: AsyncSession = Depends(get_db),
+) -> Usuario:
+    payload = decode_jwt(credentials.credentials)
+    if not payload:
+        raise HTTPException(status_code=401, detail="Token inválido")
+    usuario = await db.get(Usuario, payload["sub"])
+    if not usuario or not usuario.activo:
+        raise HTTPException(status_code=401, detail="Usuario inactivo")
+    return usuario
+
+def require_role(roles: list[str]):
+    async def verificar_rol(usuario: Usuario = Depends(get_current_user)) -> Usuario:
+        if usuario.rol not in roles:
+            raise HTTPException(status_code=403, detail=f"Rol requerido: {roles}")
+        return usuario
+    return verificar_rol
+```
+
+---
+
+## Endpoints con patrones correctos
+
+```python
+router = APIRouter(prefix="/facturas", tags=["Facturas"])
+
+# Rutas estáticas ANTES de paramétricas
+@router.get("/exportar", response_model=list[FacturaRead])
+async def exportar_facturas(...): ...
+
+@router.get("/{factura_id}", response_model=FacturaRead)
+async def obtener_factura(factura_id: str, db: AsyncSession = Depends(get_db)):
+    query = (
+        select(Factura)
+        .where(Factura.id == factura_id)
+        # OBLIGATORIO: selectinload para todas las relaciones usadas en el schema
+        .options(selectinload(Factura.cliente))
+    )
+    result = await db.execute(query)
+    factura = result.scalar_one_or_none()
+    if not factura:
+        raise HTTPException(status_code=404, detail="Factura no encontrada")
+    # IDOR: validar que el recurso pertenece al usuario
+    if factura.empresa_id != usuario.empresa_id:
+        raise HTTPException(status_code=403, detail="Acceso denegado")
+    return factura
+```
+
+---
+
+## SQLAlchemy Async — reglas críticas
+
+### NUNCA lazy loading en async
+
+```python
+# MAL — causa MissingGreenlet
+factura = await db.get(Factura, factura_id)
+print(factura.cliente.nombre)  # Error
+
+# BIEN — selectinload explícito
+query = select(Factura).where(Factura.id == factura_id).options(
+    selectinload(Factura.cliente)
+)
+```
+
+### Services: flush, no commit
+
+```python
+class FacturaService:
+    async def crear(self, db: AsyncSession, datos: FacturaCreate, owner: Usuario) -> Factura:
+        factura = Factura(**datos.model_dump(), empresa_id=owner.empresa_id)
+        db.add(factura)
+        await db.flush()      # Obtiene ID sin commitear
+        await db.refresh(factura)
+        return factura
+        # NO hacer commit aquí — el endpoint es responsable
+```
+
+### lazy="selectin" para relaciones frecuentes
+
+```python
+class Factura(Base):
+    # Para relaciones accedidas en casi todos los queries
+    cliente: Mapped["Cliente"] = relationship(lazy="selectin")
+    # Para relaciones accedidas raramente
+    items: Mapped[list["ItemFactura"]] = relationship(lazy="select")
+```
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **`MissingGreenlet` en endpoint que parece acceder solo a columnas cargadas**: SQLAlchemy async dispara MissingGreenlet cuando se accede a una relación lazy fuera de la sesión activa, aunque el objeto parezca "completo". Causa: el default de SQLAlchemy es `lazy="select"` — al serializar con Pydantic, si el serializer accede a `usuario.empresa.nombre`, el ORM intenta hacer una query sync desde contexto async. Solución: `selectinload(Usuario.empresa)` en la query original, o `lazy="selectin"` en el campo del modelo para relaciones que siempre se necesitan.
+- **`Depends(get_current_user)` inyectado correctamente pero el endpoint igual retorna 200 sin autenticación**: el endpoint está declarado como `async def` pero el `Depends` se registró en el scope equivocado o en el router padre sin propagarse al hijo. Causa: FastAPI propaga `dependencies` de `APIRouter` a todos sus endpoints, pero solo si se pasan al `include_router` con el parámetro `dependencies=`, no al constructor del router. Solución: verificar que `app.include_router(router, dependencies=[Depends(get_current_user)])` está declarado para todos los routers protegidos.
+- **El endpoint GET hace `db.commit()` y el test pasa, pero en producción los datos se modifican inesperadamente**: un GET que comitea no es idempotente — herramientas de monitoreo, crawlers de SEO o retries del cliente pueden ejecutar el GET múltiples veces. Causa: `db.commit()` en un GET activa transacciones que modifican estado. Solución: según la regla del skill, los endpoints GET NUNCA deben hacer `db.commit()` — si el endpoint necesita registrar que se accedió al recurso, usar una tarea async en background con `BackgroundTasks`.
+- **Pydantic v2 `model_validator(mode='before')` silencia errores de tipo al recibir None donde se espera un dict**: Pydantic v2 convierte `None` a `{}` en algunos contextos de validación `before`, produciendo un modelo con todos los campos como `None` en lugar de fallar con `ValidationError`. Causa: el `mode='before'` recibe el valor crudo antes de la coerción de tipos; si el validator retorna el valor sin verificar, Pydantic intenta instanciar el modelo con datos inválidos. Solución: en el `model_validator(mode='before')`, verificar explícitamente que el valor no es `None` antes de procesarlo: `if values is None: raise ValueError("...")`.
+- **Baseline Alembic con `create_all()` genera deuda estructural en toda la cadena de migraciones posterior**: si el baseline `0001_initial.py` usa `Base.metadata.create_all(bind=op.get_bind())` en lugar de `op.create_table(...)` explícito, cada migración posterior (0002, 0003, ...) debe asumir que el estado real del schema puede diverger del árbol de modelos declarado y volverse idempotente con helpers tipo `_column_if_missing`, `_index_if_missing`. Causa: `create_all` refleja el estado actual de los modelos Python, no un snapshot explícito del schema — si el schema de producción diverge (índices agregados a mano, columnas con defaults distintos), las migraciones posteriores fallan con errores de "already exists" o no ejecutan acciones que asumen que el estado previo era el declarado. Solución: **nunca** usar `create_all()` en migraciones de Alembic. Baseline debe tener `op.create_table(...)` explícito por cada tabla del schema inicial. Si el proyecto ya tiene esta deuda, dos opciones: (a) migraciones posteriores 100% idempotentes con `IF NOT EXISTS` y helpers, (b) regenerar baseline con `alembic revision --autogenerate` tras un `alembic stamp head` a una base limpia y squash del historial.
+
+## Referencias especializadas
+
+| Tema | Archivo |
+|------|---------|
+| Middleware, pydantic-settings, JWT, CORS avanzado | [recursos/referencia-completa.md](recursos/referencia-completa.md) |
+| Depends() avanzado, Annotated, security schemes, DI en tests | [recursos/dependency-injection.md](recursos/dependency-injection.md) |
+| MissingGreenlet, selectinload, WebSockets, SSE, connection pooling | [recursos/async-patterns.md](recursos/async-patterns.md) |
+| AsyncClient, fixtures, mocks, pytest-asyncio, coverage | [recursos/testing-httpx.md](recursos/testing-httpx.md) |