@saulwade/swl-ses 1.0.0

package/habilidades/kotlin-compose/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: kotlin-compose
+description: >
+  Jetpack Compose avanzado: state hoisting, remember vs rememberSaveable,
+  derivedStateOf, Navigation Compose con type-safe routes, LazyColumn con keys,
+  side effects, animaciones y optimización de recomposición con @Stable.
+  Cargar cuando se implementen pantallas Compose, se optimice recomposición,
+  o se configure Navigation Compose en proyectos Android.
+version: "1.0.0"
+herramientasPermitidas: [Read, Glob, Grep]
+exclusiones:
+  - "No cargar para lógica de negocio, ViewModels o coroutines fuera de Compose — para eso cargar `kotlin-experto`."
+  - "No cargar para escribir tests de UI con ComposeTestRule — para testing cargar `kotlin-testing`."
+  - "No cargar para errores de compilación Kotlin o Compose — para build errors cargar `build-errors-kotlin`."
+  - "No cargar para SwiftUI o React Native — Compose es específico de Android/Kotlin; para iOS cargar `swift-patrones`."
+evolvable: true  # default para skill estandar
+---
+# Kotlin Compose — State, Navigation y Performance
+
+## Cuándo NO cargar
+
+- La pregunta es sobre lógica de negocio, ViewModels, coroutines o Hilt fuera de Compose — para eso cargar `kotlin-experto`.
+- La tarea es escribir tests de UI con `ComposeTestRule` — para testing cargar `kotlin-testing`.
+- Los errores son de compilación Kotlin o Compose (generación de código de Hilt, errores de BOM) — cargar `build-errors-kotlin`.
+- La UI es SwiftUI, React Native o Flutter — Compose es específico de Android/Kotlin.
+
+## State Hoisting — Regla fundamental
+
+El estado debe vivir en el nivel más bajo que lo necesita, pero no más abajo.
+Hoistear hacia arriba cuando más de un composable lo necesita.
+
+```kotlin
+// MAL — estado interno, no testeable, no reutilizable
+@Composable
+fun BuscadorFacturas() {
+    var query by remember { mutableStateOf("") }
+    // query solo visible aquí
+}
+
+// BIEN — estado hoisted, el llamador controla
+@Composable
+fun BuscadorFacturas(
+    query: String,
+    onQueryChange: (String) -> Unit,
+    modifier: Modifier = Modifier
+) {
+    OutlinedTextField(
+        value = query,
+        onValueChange = onQueryChange,
+        modifier = modifier
+    )
+}
+
+// Llamador (o ViewModel) posee el estado
+@Composable
+fun FacturasScreen(viewModel: FacturasViewModel = hiltViewModel()) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    BuscadorFacturas(
+        query = uiState.query,
+        onQueryChange = viewModel::onQueryChange
+    )
+}
+```
+
+---
+
+## remember vs rememberSaveable
+
+```kotlin
+// remember — sobrevive recomposición, NO sobrevive rotación de pantalla
+var expandido by remember { mutableStateOf(false) }
+
+// rememberSaveable — sobrevive recomposición Y rotación
+// Usar para estado de UI efímero que el usuario espera que persista
+var seleccionado by rememberSaveable { mutableStateOf("") }
+
+// rememberSaveable con Saver personalizado para objetos complejos
+var filtros by rememberSaveable(stateSaver = FiltrosSaver) {
+    mutableStateOf(FiltrosFactura())
+}
+
+val FiltrosSaver = Saver<FiltrosFactura, Bundle>(
+    save = { filtros ->
+        Bundle().apply {
+            putString("estatus", filtros.estatus)
+            putString("desde", filtros.desde?.toString())
+        }
+    },
+    restore = { bundle ->
+        FiltrosFactura(
+            estatus = bundle.getString("estatus"),
+            desde = bundle.getString("desde")?.let { LocalDate.parse(it) }
+        )
+    }
+)
+```
+
+---
+
+## derivedStateOf — Computaciones derivadas
+
+```kotlin
+// derivedStateOf solo recompone cuando el RESULTADO cambia,
+// no cuando la fuente cambia. Ideal para filtros y búsquedas.
+@Composable
+fun FacturasList(facturas: List<Factura>, query: String) {
+    // Sin derivedStateOf: recompone en CADA keystroke aunque el resultado sea igual
+    // Con derivedStateOf: recompone solo cuando la lista filtrada cambia
+    val facturasFiltradas by remember(facturas) {
+        derivedStateOf {
+            if (query.isBlank()) facturas
+            else facturas.filter {
+                it.folio.contains(query, ignoreCase = true) ||
+                it.cliente.contains(query, ignoreCase = true)
+            }
+        }
+    }
+
+    LazyColumn {
+        items(facturasFiltradas, key = { it.id }) { factura ->
+            FacturaItem(factura)
+        }
+    }
+}
+```
+
+---
+
+## Navigation Compose — Type-safe Routes
+
+```kotlin
+// Definir rutas como objetos serializables (Navigation 2.8+)
+@Serializable object RutaFacturas
+@Serializable data class RutaDetalleFactura(val id: String)
+@Serializable object RutaCrearFactura
+
+@Composable
+fun AppNavGraph(navController: NavHostController = rememberNavController()) {
+    NavHost(navController, startDestination = RutaFacturas) {
+        composable<RutaFacturas> {
+            FacturasScreen(
+                onFacturaClick = { id ->
+                    navController.navigate(RutaDetalleFactura(id))
+                },
+                onCrearClick = { navController.navigate(RutaCrearFactura) }
+            )
+        }
+        composable<RutaDetalleFactura> { backStackEntry ->
+            val ruta = backStackEntry.toRoute<RutaDetalleFactura>()
+            DetalleFacturaScreen(facturaId = ruta.id)
+        }
+        composable<RutaCrearFactura> {
+            CrearFacturaScreen(onGuardado = { navController.popBackStack() })
+        }
+    }
+}
+```
+
+---
+
+## LazyColumn — Keys y Performance
+
+```kotlin
+// SIEMPRE proveer key estable para evitar recomposición completa
+LazyColumn(
+    contentPadding = PaddingValues(16.dp),
+    verticalArrangement = Arrangement.spacedBy(8.dp)
+) {
+    // key debe ser estable y único — usar el ID del dominio
+    items(facturas, key = { factura -> factura.id }) { factura ->
+        FacturaItem(
+            factura = factura,
+            modifier = Modifier.animateItem()  // animación de inserción/eliminación
+        )
+    }
+
+    // Separador sin key — usar índice si no hay ID
+    itemsIndexed(secciones, key = { index, _ -> "seccion_$index" }) { _, seccion ->
+        SeccionHeader(seccion)
+    }
+}
+```
+
+---
+
+## Side Effects
+
+```kotlin
+@Composable
+fun FacturasScreen(viewModel: FacturasViewModel = hiltViewModel()) {
+    val contexto = LocalContext.current
+
+    // LaunchedEffect — efecto async ligado al ciclo de vida del composable
+    // Se re-ejecuta cuando cambia la key
+    LaunchedEffect(Unit) {
+        viewModel.events.collect { evento ->
+            when (evento) {
+                is FacturasEvent.FacturaCreada ->
+                    Toast.makeText(contexto, "Factura creada", Toast.LENGTH_SHORT).show()
+            }
+        }
+    }
+
+    // DisposableEffect — para limpiar recursos (listeners, suscripciones)
+    val lifecycleOwner = LocalLifecycleOwner.current
+    DisposableEffect(lifecycleOwner) {
+        val observer = LifecycleEventObserver { _, event ->
+            if (event == Lifecycle.Event.ON_RESUME) viewModel.recargar()
+        }
+        lifecycleOwner.lifecycle.addObserver(observer)
+        onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }
+    }
+
+    // SideEffect — sincronizar estado a código no-Compose
+    // Se ejecuta en CADA recomposición exitosa
+    SideEffect {
+        analytics.setPantallaActual("facturas")
+    }
+}
+```
+
+---
+
+Para animaciones (AnimatedVisibility, animateContentSize, updateTransition) y
+optimización de performance con @Stable, ImmutableList y lambdas estables, ver
+[recursos/animaciones-performance.md](recursos/animaciones-performance.md).
+
+---
+
+## Anti-patrones
+
+### Leer State en lambda sin capturar correctamente
+
+```kotlin
+// MAL — captura el valor en el momento de creación del composable
+val contador by remember { mutableStateOf(0) }
+Button(onClick = { println(contador) })  // siempre imprime el valor inicial
+
+// BIEN — leer el estado dentro de la lambda (se evalúa al click)
+val contadorState = remember { mutableStateOf(0) }
+Button(onClick = { println(contadorState.value) })
+```
+
+### Función en lugar de computed state
+
+```kotlin
+// MAL — función recalcula y causa recomposición en cada frame
+@Composable
+fun Pantalla(facturas: List<Factura>) {
+    val total = facturas.sumOf { it.total }  // recalcula siempre
+    Text("Total: $total")
+}
+
+// BIEN — derivedStateOf o remember con key
+val total by remember(facturas) { derivedStateOf { facturas.sumOf { it.total } } }
+```
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**`remember { derivedStateOf { ... } }` sin `remember` en la derivación no se recomputa**: `derivedStateOf { lista.filter { it.activo } }` sin envolver en `remember` crea un nuevo objeto `State` en cada recomposición, anulando la optimización. Fix: siempre combinar: `val filtrado by remember { derivedStateOf { lista.filter { it.activo } } }`.
+
+**`LazyColumn` sin `key` causa que los composables se recreen en lugar de reordenarse**: al cambiar el orden de los items, Compose reutiliza los composables por posición, no por identidad — los estados internos de cada item (scroll position, animation state) se mezclan. Fix: siempre especificar `key = { item -> item.id }` en `items()` de `LazyColumn`/`LazyRow`.
+
+**`SideEffect` se ejecuta en cada recomposición, no una sola vez**: `SideEffect { SystemUiController.setStatusBarColor(color) }` cambia el color en cada recomposición del composable, no solo al montar. Causa: `SideEffect` no tiene ciclo de vida — ejecuta en cada render exitoso. Fix: usar `LaunchedEffect(key)` con una clave estable si el efecto solo debe ejecutarse cuando cambia un valor específico.
+
+**`@Stable` en una clase con campos `var` no previene recomposiciones**: marcar una clase como `@Stable` le dice a Compose que las comparaciones de igualdad son confiables, pero si la clase tiene `var` mutables que cambian sin notificar a Compose (no usando `mutableStateOf`), las recomposiciones no se disparan cuando deberían y la UI queda desactualizada. Fix: usar `@Stable` solo en clases verdaderamente inmutables o en clases que usan `State` de Compose para sus campos mutables.
+
+## Checklist Compose
+
+- [ ] Estado hoisted al nivel mínimo necesario
+- [ ] rememberSaveable para estado que debe sobrevivir rotación
+- [ ] derivedStateOf para computaciones sobre listas o búsquedas
+- [ ] LazyColumn siempre con key = { item.id }
+- [ ] Lambdas en items de LazyColumn con remember para evitar recreación
+- [ ] @Stable o ImmutableList para listas en parámetros de composable
+- [ ] Navigation usa type-safe routes (objetos @Serializable)

package/habilidades/kotlin-compose/recursos/animaciones-performance.md

@@ -0,0 +1,93 @@
+# Compose — Animaciones y Performance
+
+## Animaciones
+
+```kotlin
+// AnimatedVisibility — mostrar/ocultar con transición
+AnimatedVisibility(
+    visible = mostrarFiltros,
+    enter = slideInVertically() + fadeIn(),
+    exit = slideOutVertically() + fadeOut()
+) {
+    PanelFiltros()
+}
+
+// animateContentSize — tamaño cambia suavemente
+Card(
+    modifier = Modifier
+        .animateContentSize(
+            animationSpec = spring(dampingRatio = Spring.DampingRatioMediumBouncy)
+        )
+) {
+    Column {
+        FacturasHeader(expandido = expandido, onClick = { expandido = !expandido })
+        if (expandido) FacturasDetalle()
+    }
+}
+
+// updateTransition — múltiples propiedades animadas juntas
+val transicion = updateTransition(targetState = estado, label = "estado")
+val color by transicion.animateColor(label = "color") { s ->
+    when (s) {
+        Estado.Activo -> MaterialTheme.colorScheme.primary
+        Estado.Inactivo -> MaterialTheme.colorScheme.surfaceVariant
+    }
+}
+
+// Animate*AsState — animación de valor único
+val opacidad by animateFloatAsState(
+    targetValue = if (visible) 1f else 0f,
+    animationSpec = tween(durationMillis = 300),
+    label = "opacidad"
+)
+```
+
+---
+
+## Performance — @Stable y Skippability
+
+### Reglas de estabilidad
+
+Compose puede saltarse la recomposición de un composable solo si todos sus
+parámetros son estables. Un tipo es estable cuando:
+- Es primitivo (Int, Boolean, String, etc.)
+- Es un data class donde todos los campos son estables
+- Está anotado con `@Stable` o `@Immutable`
+
+```kotlin
+// @Stable: el compilador confía en que equals() detecta cambios
+@Stable
+class FacturasState(
+    val facturas: List<Factura>,
+    val cargando: Boolean
+) {
+    override fun equals(other: Any?) = other is FacturasState &&
+        facturas == other.facturas && cargando == other.cargando
+}
+
+// ImmutableList de kotlinx.collections.immutable
+// La List<T> estándar NO es @Stable — causa recomposición innecesaria
+@Composable
+fun FacturasList(facturas: ImmutableList<Factura>) {
+    LazyColumn {
+        items(facturas, key = { it.id }) { FacturaItem(it) }
+    }
+}
+
+// Lambdas estables en items de lista
+// MAL — nueva lambda en cada recomposición del padre
+items(facturas) { factura ->
+    FacturaItem(onClic = { viewModel.seleccionar(factura.id) })
+}
+
+// BIEN — lambda estable con remember
+items(facturas) { factura ->
+    val onClic = remember(factura.id) { { viewModel.seleccionar(factura.id) } }
+    FacturaItem(onClic = onClic)
+}
+```
+
+### Diagnóstico con Layout Inspector
+
+Activar "Recomposition counts" en Layout Inspector de Android Studio para
+identificar composables que recomponen más veces de lo esperado.

package/habilidades/kotlin-experto/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: kotlin-experto
+description: >
+  Kotlin moderno: coroutines, Flow con stateIn/shareIn, ViewModel con
+  SavedStateHandle, Hilt DI, Room con Flow, Ktor server, kotlinx.serialization
+  y sealed classes para estados UI. Cargar cuando se implementen features
+  Android/Kotlin, ViewModels, repositorios Room, o servicios backend Ktor.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para implementar pantallas Jetpack Compose — para Compose cargar `kotlin-compose`."
+  - "No cargar para escribir tests Kotlin (MockK, Turbine, runTest) — para testing cargar `kotlin-testing`."
+  - "No cargar para errores de compilación Kotlin o Gradle — para build errors cargar `build-errors-kotlin`."
+  - "No cargar para servicios Java Spring Boot sin Kotlin — Java tiene su propio modelo de concurrencia; cargar `java-experto`."
+evolvable: true  # default para skill estandar
+---
+# Kotlin Experto — Coroutines, Flow y Android
+
+## Cuándo NO cargar
+
+- La tarea es implementar pantallas Jetpack Compose (composables, state hoisting, Navigation Compose) — cargar `kotlin-compose`.
+- La tarea es escribir tests Kotlin con MockK, Turbine o runTest — cargar `kotlin-testing`.
+- Los errores son de compilación Kotlin, Hilt o Gradle — cargar `build-errors-kotlin`.
+- El proyecto es Java Spring Boot sin Kotlin — Java tiene su propio modelo de concurrencia y DI; cargar `java-experto`.
+
+## Coroutines — Scopes y Dispatchers
+
+```kotlin
+// Regla: usar el dispatcher correcto según el trabajo
+class FacturasViewModel(
+    private val repo: IFacturasRepository,
+    savedState: SavedStateHandle
+) : ViewModel() {
+
+    // SavedStateHandle sobrevive a process death
+    private val empresaId = savedState.get<String>("empresaId")
+        ?: throw IllegalArgumentException("empresaId requerido")
+
+    // StateFlow para UI state — nunca MutableStateFlow público
+    private val _uiState = MutableStateFlow<FacturasUiState>(FacturasUiState.Cargando)
+    val uiState: StateFlow<FacturasUiState> = _uiState.asStateFlow()
+
+    init {
+        cargarFacturas()
+    }
+
+    private fun cargarFacturas() {
+        viewModelScope.launch {  // se cancela con el ViewModel
+            _uiState.value = FacturasUiState.Cargando
+            repo.observarFacturas(empresaId)
+                .catch { e ->
+                    _uiState.value = FacturasUiState.Error(e.message ?: "Error desconocido")
+                }
+                .collect { facturas ->
+                    _uiState.value = FacturasUiState.Exito(facturas)
+                }
+        }
+    }
+}
+
+// withContext para cambiar dispatcher
+suspend fun cargarDesdeRed(): List<Factura> = withContext(Dispatchers.IO) {
+    api.obtenerFacturas()   // IO: red, disco
+}
+
+// async/await para paralelismo
+suspend fun cargarDashboard(): Dashboard = coroutineScope {
+    val facturasDeferred = async { api.obtenerFacturas() }
+    val clientesDeferred = async { api.obtenerClientes() }
+    Dashboard(facturas = facturasDeferred.await(), clientes = clientesDeferred.await())
+}
+```
+
+---
+
+## Flow — stateIn, shareIn, conflate
+
+```kotlin
+class FacturasRepository(private val dao: FacturasDao) : IFacturasRepository {
+
+    // stateIn: convierte Flow frío en StateFlow caliente
+    // SharingStarted.WhileSubscribed(5000): mantiene 5s luego del último suscriptor
+    // (sobrevive rotación de pantalla)
+    override fun observarFacturas(empresaId: String): StateFlow<List<Factura>> =
+        dao.observarPorEmpresa(empresaId)
+            .map { entities -> entities.map { it.toDomain() } }
+            .stateIn(
+                scope = externalScope,          // scope del Application, no del ViewModel
+                started = SharingStarted.WhileSubscribed(5_000),
+                initialValue = emptyList()
+            )
+
+    // conflate: descarta intermedios cuando el consumidor es lento
+    fun observarProgreso(): Flow<Int> = producirProgreso().conflate()
+}
+
+// Room DAO retorna Flow — se re-emite en cada cambio de BD
+@Dao
+interface FacturasDao {
+    @Query("SELECT * FROM facturas WHERE empresa_id = :empresaId ORDER BY fecha DESC")
+    fun observarPorEmpresa(empresaId: String): Flow<List<FacturaEntity>>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertar(factura: FacturaEntity)
+}
+```
+
+---
+
+## Hilt — Módulos e Inyección
+
+```kotlin
+// Módulo para dependencias externas / interfaces
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    fun provideHttpClient(): HttpClient = HttpClient(Android) {
+        install(ContentNegotiation) { json() }
+        install(HttpTimeout) { requestTimeoutMillis = 30_000 }
+    }
+
+    @Provides
+    @Singleton
+    fun provideFacturasApi(client: HttpClient): IFacturasApi =
+        FacturasApiImpl(client)
+}
+
+// Bind: implementación de interfaz en el mismo módulo
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class RepositoryModule {
+    @Binds
+    @Singleton
+    abstract fun bindFacturasRepo(
+        impl: FacturasRepositoryImpl
+    ): IFacturasRepository
+}
+
+// ViewModel con Hilt
+@HiltViewModel
+class FacturasViewModel @Inject constructor(
+    private val repo: IFacturasRepository,
+    savedState: SavedStateHandle
+) : ViewModel()
+```
+
+---
+
+## Sealed Classes para Estados UI
+
+```kotlin
+sealed interface FacturasUiState {
+    data object Cargando : FacturasUiState
+    data class Exito(val facturas: List<Factura>) : FacturasUiState
+    data class Error(val mensaje: String) : FacturasUiState
+}
+
+// Uso exhaustivo en Compose — el compilador fuerza todos los casos
+@Composable
+fun FacturasScreen(uiState: FacturasUiState) {
+    when (uiState) {
+        is FacturasUiState.Cargando -> CircularProgressIndicator()
+        is FacturasUiState.Error -> ErrorView(uiState.mensaje)
+        is FacturasUiState.Exito -> FacturasList(uiState.facturas)
+    }
+}
+```
+
+---
+
+## Ktor — Routing y Plugins
+
+```kotlin
+fun Application.configurarRouting() {
+    install(ContentNegotiation) { json() }
+    install(RequestValidation) {
+        validate<CrearFacturaRequest> { req ->
+            if (req.folio.isBlank()) ValidationResult.Invalid("folio requerido")
+            else ValidationResult.Valid
+        }
+    }
+    install(StatusPages) {
+        exception<Throwable> { call, cause ->
+            call.respond(HttpStatusCode.InternalServerError,
+                mapOf("error" to (cause.message ?: "Error interno")))
+        }
+    }
+
+    routing {
+        route("/api/v1") {
+            authenticate("jwt") {
+                facturaRoutes()
+            }
+        }
+    }
+}
+
+fun Route.facturaRoutes() {
+    route("/facturas") {
+        get {
+            val empresaId = call.principal<JWTPrincipal>()!!
+                .payload.getClaim("empresa_id").asString()
+            val facturas = facturasService.obtenerTodas(empresaId)
+            call.respond(facturas)
+        }
+        post {
+            val req = call.receive<CrearFacturaRequest>()
+            val factura = facturasService.crear(req)
+            call.respond(HttpStatusCode.Created, factura)
+        }
+    }
+}
+```
+
+---
+
+## kotlinx.serialization
+
+```kotlin
+@Serializable
+data class FacturaDto(
+    val id: String,
+    val folio: String,
+    val total: Double,
+    @SerialName("fecha_emision") val fechaEmision: String,
+    val estatus: EstatusFactura = EstatusFactura.BORRADOR
+)
+
+@Serializable
+enum class EstatusFactura { BORRADOR, EMITIDA, CANCELADA }
+
+// Configuración global de JSON
+val jsonConfig = Json {
+    ignoreUnknownKeys = true    // tolerante a campos extras de API
+    isLenient = false
+    encodeDefaults = false       // no serializar campos con valor default
+    prettyPrint = false
+}
+```
+
+---
+
+## Extension Functions útiles
+
+```kotlin
+// Result como alternativa a excepciones
+suspend fun <T> safeApiCall(block: suspend () -> T): Result<T> =
+    try { Result.success(block()) }
+    catch (e: CancellationException) { throw e }   // NUNCA atrapar CancellationException
+    catch (e: Exception) { Result.failure(e) }
+
+// Flow de paginación
+fun <T> Flow<List<T>>.paginar(pagina: Int, tamanoPagina: Int): Flow<List<T>> =
+    map { it.drop(pagina * tamanoPagina).take(tamanoPagina) }
+```
+
+---
+
+## Anti-patrones
+
+### GlobalScope — NUNCA
+
+```kotlin
+// MAL — no tiene lifecycle, las coroutines se filtran
+GlobalScope.launch { api.obtenerFacturas() }
+
+// BIEN — scope ligado al lifecycle
+viewModelScope.launch { ... }    // ViewModel
+lifecycleScope.launch { ... }    // Activity/Fragment
+```
+
+### Atrapar CancellationException — NUNCA
+
+```kotlin
+// MAL — rompe la cooperación de coroutines
+try { ... } catch (e: Exception) { /* atrapa CancellationException */ }
+
+// BIEN — re-lanzar siempre
+try { ... } catch (e: Exception) {
+    if (e is CancellationException) throw e
+    // manejar otros errores
+}
+```
+
+### MutableStateFlow público — NUNCA
+
+```kotlin
+// MAL — UI puede modificar el estado desde afuera
+val uiState = MutableStateFlow<Estado>(Estado.Cargando)
+
+// BIEN — privado con backing property
+private val _uiState = MutableStateFlow<Estado>(Estado.Cargando)
+val uiState: StateFlow<Estado> = _uiState.asStateFlow()
+```
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**`CancellationException` atrapada en un `catch(e: Exception)` rompe la cooperación de coroutines**: un bloque `catch (e: Exception) { /* ignorar */ }` captura `CancellationException` porque es subclase de `Exception`, lo que impide que la coroutine cancele correctamente. La coroutine sigue ejecutando después de que su scope fue cancelado. Fix: siempre hacer `catch (e: CancellationException) { throw e }` o usar `catch (e: Exception) { if (e is CancellationException) throw e }`.
+
+**`stateIn(scope, SharingStarted.Eagerly, ...)` inicia el Flow aunque no haya suscriptores y consume recursos en background**: usar `Eagerly` en un ViewModel que se crea pero no se observa inmediatamente mantiene el Flow activo y puede generar requests innecesarios a la BD. Fix: usar `SharingStarted.WhileSubscribed(5000)` para activar el Flow solo cuando hay colectores activos, con 5 segundos de gracia para rotaciones de pantalla.
+
+**`viewModelScope.launch` sobrevive a la destrucción del ViewModel si usa `withContext(Dispatchers.IO)`**: el coroutine scope del ViewModel se cancela en `onCleared()`, pero si hay trabajo en `Dispatchers.IO` en progreso, ese trabajo puede seguir ejecutando hasta que termine porque `Dispatchers.IO` no respeta automáticamente la cancelación del scope si el código no verifica `isActive`. Fix: asegurar que el código I/O usa operaciones cancelables o verifica `coroutineContext.isActive` periódicamente en loops.
+
+**`@HiltViewModel` con parámetros que no son `SavedStateHandle` rompe la inyección en runtime**: si se agrega un parámetro no provisto por Hilt al constructor del ViewModel (como un ID de entidad), Hilt no puede crear el ViewModel y lanza `RuntimeException` al navegar a la pantalla. Fix: pasar datos iniciales siempre a través de `SavedStateHandle` desde los argumentos de navegación, nunca como constructor directo del ViewModel.
+
+## Checklist
+
+- [ ] No hay GlobalScope.launch en código de producción
+- [ ] CancellationException siempre se re-lanza
+- [ ] MutableStateFlow siempre privado con backing property
+- [ ] Room DAO retorna Flow para observabilidad reactiva
+- [ ] stateIn usa WhileSubscribed(5000) para sobrevivir rotaciones
+- [ ] Hilt: repositorios en SingletonComponent, ViewModels con @HiltViewModel