engsys 1.0.0

package/stacks/lang/kotlin/skills/jetpack-compose/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: jetpack-compose
+description: "Build Android UIs with Jetpack Compose: composition, state hoisting, remember/rememberSaveable/derivedStateOf, recomposition correctness and performance, side-effect APIs (LaunchedEffect/DisposableEffect/rememberCoroutineScope/produceState/snapshotFlow), Material 3 theming, and Compose navigation. Use when writing or reviewing @Composable functions, fixing recomposition or state bugs, hoisting state, choosing a side-effect API, applying Material 3, or improving Compose performance and stability."
+---
+
+# Jetpack Compose
+
+Build and review Android UIs with Jetpack Compose targeting the current Compose
+BOM (2025.x) and Material 3. Composables are pure descriptions of UI for a given
+state; the runtime re-invokes them (recomposes) when the state they read
+changes. Treat composition as a function of state, keep composables side-effect
+free except through the official effect APIs, and hoist state so UI is testable
+and reusable. This is Android's analogue of declarative SwiftUI.
+
+## Contents
+
+- [Composition Model](#composition-model)
+- [State and remember](#state-and-remember)
+- [State Hoisting](#state-hoisting)
+- [derivedStateOf](#derivedstateof)
+- [Recomposition Pitfalls](#recomposition-pitfalls)
+- [Side-Effect APIs](#side-effect-apis)
+- [Collecting Flows](#collecting-flows)
+- [Stability and Performance](#stability-and-performance)
+- [Material 3](#material-3)
+- [ViewModel Integration](#viewmodel-integration)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+
+## Composition Model
+
+- A `@Composable` function emits UI. It may run often, in any order, in parallel,
+  and be skipped. **It must be idempotent and free of side effects.**
+- Never mutate external state, perform IO, or launch work directly in the body of
+  a composable. Use the effect APIs for anything that must happen *as a result*
+  of composition.
+- Recomposition is driven by reads of *snapshot state* (`State<T>` /
+  `MutableState<T>`). Reading a state value subscribes that composition scope to
+  it; when it changes, only scopes that read it recompose.
+
+## State and remember
+
+| API | Use for |
+|---|---|
+| `remember { }` | Keep an object across recompositions (not config changes). |
+| `rememberSaveable { }` | Survive config changes and process death (Bundle-able). |
+| `mutableStateOf(x)` | Observable state that triggers recomposition on change. |
+| `derivedStateOf { }` | Computed state derived from other state (see below). |
+| `produceState` | Convert non-Compose async source into `State`. |
+
+```kotlin
+@Composable
+fun Counter() {
+    var count by rememberSaveable { mutableStateOf(0) }   // survives rotation
+    Button(onClick = { count++ }) { Text("Count: $count") }
+}
+```
+
+- Use `by` delegation (`var x by remember { mutableStateOf(...) }`) for ergonomic
+  reads/writes.
+- `remember(key1, key2) { ... }` recomputes when a key changes — use keys to
+  reset remembered state when inputs change.
+- Prefer `rememberSaveable` for anything the user would be annoyed to lose on
+  rotation (text input, scroll selection, expanded state).
+
+## State Hoisting
+
+Make composables **stateless** by lifting state up to the caller. A hoisted
+composable takes the value as a parameter and exposes changes via a callback —
+the "state down, events up" pattern.
+
+```kotlin
+// Stateless, reusable, testable
+@Composable
+fun SearchField(query: String, onQueryChange: (String) -> Unit) {
+    TextField(value = query, onValueChange = onQueryChange)
+}
+
+// Stateful caller owns the state
+@Composable
+fun SearchScreen(viewModel: SearchViewModel) {
+    val state by viewModel.uiState.collectAsStateWithLifecycle()
+    SearchField(query = state.query, onQueryChange = viewModel::onQueryChange)
+}
+```
+
+Hoist to the lowest common ancestor that needs the state. State that belongs to
+the screen's logic lives in the `ViewModel`; ephemeral UI state (animations,
+focus, scroll) can stay local with `remember`.
+
+## derivedStateOf
+
+Use `derivedStateOf` when state should be *computed* from other state and you
+want to recompute only when the **result** changes, not on every read of the
+inputs. The classic case: deriving a boolean from a frequently changing value.
+
+```kotlin
+val listState = rememberLazyListState()
+// Recomposes only when the boolean flips, not on every scroll pixel.
+val showButton by remember {
+    derivedStateOf { listState.firstVisibleItemIndex > 0 }
+}
+```
+
+Do **not** use `derivedStateOf` for a plain transformation of a single state that
+changes at the same rate as the result (e.g. `val upper = text.uppercase()`) —
+that is just a normal calculation and the extra machinery is wasteful.
+
+## Recomposition Pitfalls
+
+- **Reading state too high** hurts performance; read it as deep as possible so
+  fewer composables recompose. Defer reads with lambdas (e.g. pass
+  `{ offset }` rather than `offset`) for high-frequency values like scroll/drag.
+- **Unstable lambdas** allocated in the body cause child recomposition — prefer
+  stable method references (`viewModel::onClick`) where possible.
+- **Backwards writes** — writing to state you already read in the same
+  composition causes an infinite recomposition loop. Never do it.
+- **Side effects in the body** (logging, mutation, IO) run on every recomposition
+  and in undefined order. Move them into effects.
+- **`Modifier` ordering matters** — order changes layout and draw; it is not
+  commutative.
+- Always supply a stable `key` in `LazyColumn`/`LazyRow` `items(list, key = {...})`
+  so items keep identity across data changes (analogous to a stable
+  `Identifiable` id).
+
+## Side-Effect APIs
+
+Choose the narrowest effect that fits:
+
+| API | When |
+|---|---|
+| `LaunchedEffect(key)` | Run a suspend function when entering composition / when `key` changes; cancelled on leave. |
+| `rememberCoroutineScope()` | Launch coroutines from **event callbacks** (button clicks), not composition. |
+| `DisposableEffect(key)` | Register/unregister non-suspend resources; `onDispose { }` cleans up. |
+| `SideEffect { }` | Publish Compose state to non-Compose code after every successful recomposition. |
+| `produceState` | Turn a callback/Flow source into observable `State`. |
+| `snapshotFlow { }` | Convert reads of snapshot state into a cold `Flow`. |
+| `rememberUpdatedState` | Capture the latest value inside a long-lived effect without restarting it. |
+
+```kotlin
+// Run once on enter (key = Unit), re-run when userId changes:
+LaunchedEffect(userId) {
+    viewModel.load(userId)            // suspend; auto-cancelled on leave/key change
+}
+
+// Observe a lifecycle/listener and clean it up:
+DisposableEffect(lifecycleOwner) {
+    val observer = LifecycleEventObserver { _, e -> handle(e) }
+    lifecycleOwner.lifecycle.addObserver(observer)
+    onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }
+}
+
+// React to snapshot state as a flow:
+LaunchedEffect(listState) {
+    snapshotFlow { listState.firstVisibleItemIndex }
+        .distinctUntilChanged()
+        .collect { analytics.logScroll(it) }
+}
+```
+
+Rules:
+- The `key` of `LaunchedEffect`/`DisposableEffect` controls restart. Use a stable,
+  meaningful key — never `Unit` if the work depends on a changing input.
+- Don't launch coroutines in the composable body; use `LaunchedEffect` (tied to
+  composition) or `rememberCoroutineScope` (tied to events).
+- Use `rememberUpdatedState` to read the freshest callback inside a
+  `LaunchedEffect(Unit)` that should not restart.
+
+## Collecting Flows
+
+Always collect with lifecycle awareness so collection stops in the background:
+
+```kotlin
+val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+```
+
+`collectAsStateWithLifecycle()` (from `lifecycle-runtime-compose`) is preferred
+over `collectAsState()` on Android — it stops collecting when the lifecycle drops
+below `STARTED`, avoiding wasted work and leaks.
+
+## Stability and Performance
+
+- The compiler skips recomposition of a composable when all its parameters are
+  **stable** and unchanged. Prefer stable types: immutable `data class`es,
+  primitives, and `@Immutable`/`@Stable`-annotated types.
+- `List<T>` is treated as unstable. Prefer `kotlinx.collections.immutable`
+  (`ImmutableList`/`PersistentList`) for list parameters, or wrap in a `@Immutable`
+  holder.
+- The **Compose Compiler reports / strong-skipping** help find unstable params.
+  Strong skipping (default in recent compilers) skips even some unstable params by
+  comparing instances, but stable types remain the reliable path.
+- Use `LazyColumn`/`LazyRow`/`LazyVerticalGrid` for large/scrolling collections;
+  never render large lists with a `Column` inside a `verticalScroll`.
+- Defer high-frequency state reads (scroll offset, drag) into draw/layout lambdas
+  to avoid recomposing on every frame.
+- Avoid `Modifier.composed { }` for new code; prefer `Modifier.Node` based
+  modifiers for custom modifiers.
+
+## Material 3
+
+Use `androidx.compose.material3` (Material 3 / Material You) for new UIs.
+
+```kotlin
+@Composable
+fun AppTheme(content: @Composable () -> Unit) {
+    val dark = isSystemInDarkTheme()
+    val colors = if (supportsDynamicColor() && dark) {
+        dynamicDarkColorScheme(LocalContext.current)      // Material You, Android 12+
+    } else if (dark) darkColorScheme() else lightColorScheme()
+
+    MaterialTheme(colorScheme = colors, typography = AppTypography, content = content)
+}
+```
+
+- Theme through `MaterialTheme` (`colorScheme`, `typography`, `shapes`); read
+  values via `MaterialTheme.colorScheme.*` rather than hardcoding colors.
+- Support **dynamic color** on Android 12+ via `dynamicLightColorScheme` /
+  `dynamicDarkColorScheme` where the product wants Material You.
+- Use Material 3 components (`Scaffold`, `TopAppBar`, `NavigationBar`,
+  `FilledTonalButton`, etc.) and honor `WindowInsets` / edge-to-edge.
+- Respect the platform: this is Material, not iOS — don't port HIG idioms wholesale.
+
+## ViewModel Integration
+
+- Obtain the screen `ViewModel` with `viewModel()` (or Hilt's `hiltViewModel()`).
+- Expose a single immutable UI-state object as `StateFlow`; collect with
+  `collectAsStateWithLifecycle()`.
+- Pass state down and events up (method references to the `ViewModel`). Keep
+  composables free of business logic.
+- Use Compose Navigation (`NavHost`/`NavController`) or Navigation 3 if the
+  project has adopted it; hoist the `NavController` to the app root.
+
+## Common Mistakes
+
+1. **Side effects in the composable body** — IO, mutation, logging. Use effects.
+2. **`collectAsState()` instead of `collectAsStateWithLifecycle()`** on Android.
+3. **No `key` in lazy list `items`** — breaks item identity and animations.
+4. **`derivedStateOf` for a 1:1 transform** — unnecessary; just compute it.
+5. **`remember` where `rememberSaveable` is needed** — state lost on rotation.
+6. **Launching coroutines in the body** — use `LaunchedEffect`/event scope.
+7. **`LaunchedEffect(Unit)` that depends on a changing value** — stale captures;
+   key it properly or use `rememberUpdatedState`.
+8. **Unstable parameters** (`List`, lambdas allocated inline) defeating skipping.
+9. **Reading high-frequency state too high** in the tree — recomposes too much.
+10. **Backwards writes** — writing state already read this composition (infinite
+    loop).
+11. **Big scrollable `Column`** instead of `LazyColumn`.
+12. **Hoisting nothing** — monolithic stateful composables that can't be tested
+    or previewed.
+
+## Review Checklist
+
+- [ ] Composables are side-effect free; effects use the proper effect API
+- [ ] State hoisted appropriately (stateless leaf composables, state in ViewModel)
+- [ ] `rememberSaveable` used for state that must survive config changes
+- [ ] `derivedStateOf` used only for derived state that changes less than inputs
+- [ ] Flows collected with `collectAsStateWithLifecycle()`
+- [ ] `LaunchedEffect`/`DisposableEffect` keyed correctly; resources disposed
+- [ ] Coroutines launched from events via `rememberCoroutineScope`, not body
+- [ ] Lazy lists use stable `key`s
+- [ ] Parameters are stable (immutable data classes / ImmutableList)
+- [ ] Material 3 theming via `MaterialTheme`; dynamic color where wanted
+- [ ] No backwards writes; no IO/mutation in composition
+- [ ] High-frequency reads deferred (lambdas) to limit recomposition

package/stacks/lang/kotlin/skills/kotlin-coroutines/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: kotlin-coroutines
+description: "Write data-safe asynchronous Kotlin with coroutines, Flow, and structured concurrency on Android. Use when fixing coroutine cancellation or leak bugs, choosing dispatchers (Default/IO/Main), designing suspend functions, modeling streams with Flow/StateFlow/SharedFlow, scoping work to viewModelScope/lifecycleScope, handling exceptions with CoroutineExceptionHandler/supervisorScope, or converting callback/RxJava APIs to coroutines. Covers Kotlin 2.x, kotlinx.coroutines structured concurrency discipline, and the Android main-safety contract."
+---
+
+# Kotlin Coroutines
+
+Review, fix, and write concurrent Kotlin targeting Kotlin 2.1+ and
+kotlinx.coroutines 1.9+. Apply structured concurrency, correct dispatcher
+choice, and cooperative cancellation with minimal behavior changes. This is the
+Kotlin equivalent of Swift's structured-concurrency discipline: scopes are the
+unit of lifetime, cancellation is cooperative, and main-safety is non-negotiable.
+
+## Contents
+
+- [Triage Workflow](#triage-workflow)
+- [Structured Concurrency](#structured-concurrency)
+- [Coroutine Scopes](#coroutine-scopes)
+- [Dispatchers and Main-Safety](#dispatchers-and-main-safety)
+- [Cancellation](#cancellation)
+- [Exception Handling](#exception-handling)
+- [Flow](#flow)
+- [StateFlow and SharedFlow](#stateflow-and-sharedflow)
+- [Bridging Callback APIs](#bridging-callback-apis)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+
+## Triage Workflow
+
+When diagnosing a coroutine issue, follow this sequence:
+
+### Step 1: Capture context
+
+- Identify the scope the coroutine runs in (`viewModelScope`, `lifecycleScope`,
+  a custom `CoroutineScope`, or an unscoped `GlobalScope` — a red flag).
+- Identify the dispatcher in effect and whether the work is CPU-bound,
+  IO-bound, or UI-bound.
+- Determine whether the work must survive configuration changes / navigation, or
+  should be cancelled with the screen.
+- Copy any stack trace; note whether it is a `CancellationException` (normal) or
+  a real failure.
+
+### Step 2: Apply the smallest safe fix
+
+| Situation | Recommended fix |
+|---|---|
+| Work tied to a screen | Launch in `viewModelScope`; never `GlobalScope`. |
+| Blocking IO (disk, network, DB) | `withContext(Dispatchers.IO) { ... }`. |
+| Heavy CPU work (parse, sort, image) | `withContext(Dispatchers.Default) { ... }`. |
+| UI / state update | Stay on `Dispatchers.Main` (the default for `viewModelScope`). |
+| One child failure must not kill siblings | Use `supervisorScope` / `SupervisorJob`. |
+| Long loop never cancels | Add `ensureActive()` / `yield()` or use cancellable APIs. |
+| Callback API | Wrap with `suspendCancellableCoroutine` or `callbackFlow`. |
+
+### Step 3: Verify
+
+- Confirm cancellation propagates (the work stops when the scope is cancelled).
+- Confirm no work runs on the main thread that blocks it.
+- Confirm exceptions surface (not silently swallowed) and `CancellationException`
+  is never caught-and-ignored.
+
+## Structured Concurrency
+
+Every coroutine has a parent. A parent does not complete until all children
+complete; cancelling a parent cancels all children. This is the core safety
+guarantee — never break out of it.
+
+- Prefer `coroutineScope { }` to launch concurrent children that all must finish
+  before the function returns.
+- Use `async`/`await` for concurrent work that produces values.
+- Use `launch` for fire-and-forget work *within a scope* (not detached).
+
+```kotlin
+suspend fun loadDashboard(): Dashboard = coroutineScope {
+    val profile = async { repo.profile() }      // runs concurrently
+    val feed = async { repo.feed() }            // runs concurrently
+    Dashboard(profile.await(), feed.await())    // both joined here
+}
+```
+
+If either child throws, the scope cancels the sibling and rethrows — no leaks.
+
+**Never** use `GlobalScope.launch`. It has no parent, no lifecycle, no
+cancellation. It is the coroutine equivalent of a detached, unowned thread.
+
+## Coroutine Scopes
+
+| Scope | Lifecycle | Use for |
+|---|---|---|
+| `viewModelScope` | Cleared when the `ViewModel` clears | All ViewModel async work |
+| `lifecycleScope` | Tied to a `Lifecycle` (Activity/Fragment) | UI-layer work bound to a screen |
+| `rememberCoroutineScope()` | Tied to a composable's lifetime | Launching from Compose event callbacks |
+| custom `CoroutineScope` | You manage `cancel()` | Long-lived components (cancel explicitly) |
+
+For a custom scope, always pair a `SupervisorJob` with a dispatcher and cancel it
+when the owner is destroyed:
+
+```kotlin
+class Connection {
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+    fun close() = scope.cancel()   // cancels all children — no leaks
+}
+```
+
+In Compose, collect with `collectAsStateWithLifecycle()` (not `collectAsState()`)
+so collection stops when the app is in the background.
+
+## Dispatchers and Main-Safety
+
+A suspend function should be **main-safe**: callable from the main thread without
+blocking it. Push the thread switch *down* into the function, not up to callers.
+
+- `Dispatchers.Main` — UI updates. The default for `viewModelScope`.
+- `Dispatchers.Default` — CPU-bound work (parsing, sorting, image processing).
+  Backed by a pool sized to CPU cores.
+- `Dispatchers.IO` — blocking IO (disk, network sockets, JDBC, file). Backed by
+  a large elastic pool.
+- `Dispatchers.Main.immediate` — runs inline if already on the main thread,
+  avoiding an unnecessary re-dispatch (use for state emission).
+
+```kotlin
+// Main-safe: caller can invoke from the main thread.
+suspend fun parseLargeJson(raw: String): Model = withContext(Dispatchers.Default) {
+    json.decodeFromString(raw)
+}
+```
+
+Rules:
+1. Never block the main thread (`Thread.sleep`, blocking network, `runBlocking`).
+2. Use `withContext`, not `launch`, to switch dispatchers for a value-returning
+   step — `withContext` returns to the original dispatcher when done.
+3. Don't hardcode dispatchers in the call site you want to test; inject a
+   dispatcher (or a `CoroutineDispatcher` provider) so tests can substitute
+   `StandardTestDispatcher`.
+
+## Cancellation
+
+Cancellation is cooperative. A coroutine only stops at a suspension point or when
+it checks cooperatively.
+
+```kotlin
+suspend fun process(items: List<Item>) {
+    for (item in items) {
+        ensureActive()          // throws CancellationException if cancelled
+        heavyWork(item)         // CPU loops won't cancel on their own
+    }
+}
+```
+
+- Suspending functions from kotlinx.coroutines (`delay`, `withContext`, Flow
+  operators) are cancellable automatically.
+- Tight CPU loops are **not** — insert `ensureActive()` or `yield()`.
+- `CancellationException` is special: it signals normal cancellation. Never catch
+  it and swallow it. If you catch `Exception` broadly, rethrow it:
+
+```kotlin
+try {
+    risky()
+} catch (e: CancellationException) {
+    throw e                      // must rethrow — never swallow
+} catch (e: Exception) {
+    handle(e)
+}
+```
+
+- For cleanup that must run even after cancellation, use
+  `withContext(NonCancellable) { ... }` inside a `finally`.
+
+## Exception Handling
+
+- In `coroutineScope` / `async`, exceptions propagate to the awaiting caller —
+  handle with `try/catch` around `await()`.
+- In `launch`, an uncaught exception propagates up and cancels the scope. Install
+  a `CoroutineExceptionHandler` on the **root** scope for last-resort handling.
+- `supervisorScope` / `SupervisorJob` isolate child failures so one failing child
+  does not cancel its siblings:
+
+```kotlin
+supervisorScope {
+    launch { mightFail() }       // failure here does NOT cancel the sibling
+    launch { mustSucceed() }
+}
+```
+
+- A `CoroutineExceptionHandler` only works on root `launch` coroutines, never on
+  `async` (whose exception surfaces at `await`).
+
+## Flow
+
+`Flow<T>` is a cold asynchronous stream — it does nothing until collected, and
+re-runs its producer for each collector. It is the Kotlin analogue of an
+`AsyncSequence`.
+
+```kotlin
+fun searchResults(query: String): Flow<List<Result>> = flow {
+    emit(emptyList())                       // initial
+    emit(repo.search(query))                // suspends, emits result
+}
+```
+
+Key operators:
+- Transform: `map`, `filter`, `transform`, `flatMapLatest` (cancel-previous —
+  ideal for search-as-you-type), `flatMapConcat`, `flatMapMerge`.
+- Combine: `combine`, `zip`, `merge`.
+- Lifecycle: `onStart`, `onEach`, `onCompletion`, `catch` (upstream errors only),
+  `retry`.
+- Backpressure/threading: `flowOn(Dispatchers.IO)` changes the **upstream**
+  dispatcher; `buffer`, `conflate`, `debounce`, `sample`.
+
+```kotlin
+fun results(query: Flow<String>): Flow<UiState> = query
+    .debounce(300)
+    .distinctUntilChanged()
+    .flatMapLatest { q -> repo.search(q) }   // cancels stale searches
+    .map(UiState::Loaded)
+    .catch { emit(UiState.Error(it)) }
+    .flowOn(Dispatchers.Default)
+```
+
+Rules:
+- Use `flowOn` to set the producer dispatcher; never call `withContext` inside a
+  `flow { }` builder (it breaks context preservation — the builder enforces this).
+- Put `catch` *downstream* of the operators whose errors you want to handle;
+  collector-side errors are not caught by `catch`.
+
+## StateFlow and SharedFlow
+
+These are **hot** flows for UI state and events.
+
+- `StateFlow<T>` — holds a single current value, conflates, always has a value.
+  The standard holder for screen UI state. Emit via `MutableStateFlow`.
+- `SharedFlow<T>` — broadcasts events to multiple collectors; configurable
+  replay. Use for one-shot events (navigation, snackbars) with `replay = 0`.
+
+```kotlin
+class FeedViewModel(private val repo: FeedRepository) : ViewModel() {
+    private val _state = MutableStateFlow<FeedUiState>(FeedUiState.Loading)
+    val state: StateFlow<FeedUiState> = _state.asStateFlow()
+
+    init {
+        viewModelScope.launch {
+            _state.value = try {
+                FeedUiState.Loaded(repo.feed())
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                FeedUiState.Error(e.message)
+            }
+        }
+    }
+}
+```
+
+Convert a cold flow to a lifecycle-aware hot `StateFlow` with `stateIn`:
+
+```kotlin
+val items: StateFlow<List<Item>> = repo.observeItems()
+    .stateIn(
+        scope = viewModelScope,
+        started = SharingStarted.WhileSubscribed(5_000),  // stop 5s after last collector
+        initialValue = emptyList()
+    )
+```
+
+`WhileSubscribed(5_000)` keeps the upstream alive briefly across configuration
+changes while still stopping when nothing observes — the standard choice.
+
+For one-shot events prefer a `Channel` consumed as a flow, or a `SharedFlow` with
+`replay = 0`; do **not** model events as `StateFlow` (state is re-delivered on
+recomposition and replays stale events).
+
+## Bridging Callback APIs
+
+Single value:
+
+```kotlin
+suspend fun awaitLocation(): Location = suspendCancellableCoroutine { cont ->
+    val cb = LocationCallback { loc -> cont.resume(loc) }
+    locationManager.request(cb)
+    cont.invokeOnCancellation { locationManager.remove(cb) }   // clean up
+}
+```
+
+Stream of values:
+
+```kotlin
+fun locationUpdates(): Flow<Location> = callbackFlow {
+    val cb = LocationCallback { loc -> trySend(loc) }
+    locationManager.request(cb)
+    awaitClose { locationManager.remove(cb) }   // required — cleans up on cancel
+}
+```
+
+## Common Mistakes
+
+1. **`GlobalScope.launch`** — no lifecycle, leaks. Use a real scope.
+2. **`runBlocking` in production code** — blocks the thread; it is for `main()`
+   and tests only.
+3. **Swallowing `CancellationException`** — breaks structured cancellation;
+   always rethrow it.
+4. **Blocking the main thread** — `Thread.sleep`, blocking IO, or heavy CPU on
+   `Dispatchers.Main`.
+5. **`withContext` inside a `flow { }` builder** — use `flowOn` instead.
+6. **Collecting flows with `collectAsState()` in Compose** — use
+   `collectAsStateWithLifecycle()` so collection pauses in the background.
+7. **Hardcoded dispatchers** — inject them so tests can swap in test
+   dispatchers.
+8. **Modeling one-shot events as `StateFlow`** — they replay stale events; use a
+   `Channel`/`SharedFlow(replay = 0)`.
+9. **Launching independent work that should be concurrent sequentially** — use
+   `async`/`await` in a `coroutineScope`.
+10. **Catching exceptions on `async` with a `CoroutineExceptionHandler`** — it
+    does not fire for `async`; catch at `await`.
+11. **Forgetting `awaitClose` in `callbackFlow`** — leaks the callback.
+
+## Review Checklist
+
+- [ ] No `GlobalScope`; work runs in `viewModelScope`/`lifecycleScope`/owned scope
+- [ ] No `runBlocking` outside `main`/tests
+- [ ] Suspend functions are main-safe (`withContext` pushes the switch down)
+- [ ] CPU loops check cancellation (`ensureActive`/`yield`)
+- [ ] `CancellationException` is rethrown, never swallowed
+- [ ] Child-failure isolation uses `supervisorScope`/`SupervisorJob` where needed
+- [ ] `flowOn` sets upstream dispatcher; no `withContext` inside `flow {}`
+- [ ] UI state exposed as immutable `StateFlow` (backed by `MutableStateFlow`)
+- [ ] `stateIn` uses `WhileSubscribed(5_000)` for screen state
+- [ ] One-shot events are not modeled as `StateFlow`
+- [ ] `callbackFlow`/`suspendCancellableCoroutine` clean up on cancellation
+- [ ] Dispatchers injected for testability

package/stacks/lang/python/skills/python-conventions/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: python-conventions
+description: Python coding conventions for this repo (Python 3.12+, type hints, PEP 257/8). Use when writing, reviewing, or editing any *.py file. Covers type hints, docstrings, formatting, exception handling, async I/O, virtualenv discipline, and test expectations.
+---
+
+# Python Coding Conventions
+
+Applies to: any `*.py` file in this repo. Target: Python 3.12+.
+
+> Naturalize: confirm the venv location, package manager (uv / pip / poetry), and test runner in `CLAUDE.md`. The defaults below assume a `uv`-managed `.venv/` and `pytest`.
+
+## Function-level expectations
+
+- Descriptive function names; type hints on parameters and returns (use builtin generics on modern targets, e.g. `list[str]`, `dict[str, int]`; fall back to `typing.List` / `typing.Dict` only on older runtimes).
+- PEP 257 docstrings placed immediately after `def` / `class`.
+- Break complex functions into smaller, single-purpose helpers.
+- Handle edge cases explicitly; raise or return meaningful errors rather than silently swallowing.
+
+## General
+
+- Readability and clarity over cleverness.
+- For non-obvious algorithms, include a short comment explaining the approach.
+- Mention third-party library usage and purpose at the import site if non-obvious.
+- Consistent naming; follow language idioms.
+
+## Style
+
+- **PEP 8.** 4-space indents. Keep lines reasonable (the classic guideline is 79; many repos tolerate longer for clarity — match surrounding code and any configured formatter, e.g. `ruff`/`black`).
+- Blank lines to separate functions, classes, and logical blocks.
+
+## Async I/O
+
+- For async code, use `async def` / `await` end-to-end; don't block the event loop with sync I/O.
+- Prefer async-native drivers (e.g. an async DB/HTTP client) over wrapping sync calls in threads.
+- Use `asyncio.Lock` / structured task management for shared mutable state; guard caches against concurrent rebuilds.
+
+## Environment & dependencies
+
+- Use the project venv (commonly `.venv/`, often `uv`-managed). If a stale top-level `venv/` exists, prefer the project-documented one — check `CLAUDE.md`.
+- Load config from the environment (e.g. `python-dotenv`); quote `.env` values containing spaces so `source .env` doesn't break in zsh.
+
+## Edge cases and testing
+
+- Cover critical paths with tests; include empty inputs, invalid types, and large-input cases where relevant.
+- Prefer `pytest`. Run from the project venv.
+
+## Example
+
+```python
+def calculate_area(radius: float) -> float:
+    """Calculate the area of a circle given the radius.
+
+    Parameters:
+        radius: The radius of the circle.
+
+    Returns:
+        The area, computed as pi * radius**2.
+    """
+    import math
+    return math.pi * radius ** 2
+```