Compose state authoring

• rememberCoroutineScope / rememberUpdatedState → compose-side-effects
• rememberLazyListState / rememberScrollState used for frame-rate reads → compose-state-deferred-reads
• Focus navigation, focus state, FocusRequester ownership, behavior → compose-focus-navigation

Core principle

1. Mutable local state — does my var survive recomposition and trigger it? If not, it silently resets on every recompose and writes are invisible.
2. What kind of composable is this? — do I mutate composition (place layout nodes, allocate slots, remember) or only read it? If only read, @ReadOnlyComposable lets the runtime skip work.

When to use this skill

• var x = … inside a @Composable fun or any composable lambda (Column { var x = … })
• A @Composable fun (or @Composable get() property accessor) whose body never lays anything out
• @ReadOnlyComposable on a function that calls Text, Box, Column, remember, …
• A composable whose visible state mysteriously resets on rotation, theme change, or recomposition

1. var in a composable must be State-backed

// ❌ BAD — counter resets on every recomposition; clicks never update the UI
@Composable
fun Counter() {
    var count = 0
    Button(onClick = { count++ }) { Text("$count") }
}

// ❌ ALSO BAD — same rule applies inside composable content lambdas
@Composable
fun Wrapper() {
    Row {
        var count = 0         // Row's content lambda is @Composable too
        // …
    }
}

// ✅ GOOD — `remember` survives recomposition, `mutableStateOf` triggers it
@Composable
fun Counter() {
    var count by remember { mutableStateOf(0) }
    Button(onClick = { count++ }) { Text("$count") }
}

• remember { … } — survives recomposition. Without it the value is re-created each time.
• mutableStateOf(…) — triggers recomposition. Without it, mutations are invisible to the runtime.

Back-writing snapshot state during composition

// ❌ BAD — clear + putAll on every composition
val merged = remember { mutableStateMapOf<Key, ViewState>() }
merged.clear()
merged.putAll(parent)
merged.putAll(overlay)

// ✅ GOOD — immutable snapshot remembered from inputs
val merged = remember(parent, overlay) {
    if (overlay.isEmpty()) parent else parent + overlay
}

When this rule does NOT apply

• Inside remember { … }'s producer block. That runs once per key change, not on every recompose. A local var there is fine: val builder = remember { mutableListOf<X>().apply { var n = 0; … } }.
• In non-@Composable lambdas passed out of a composable. onClick = { var a = 0; … } is a plain () -> Unit. Local vars there are normal Kotlin.
• In plain (non-@Composable) helper functions. Only composable scopes are affected.

2. The @ReadOnlyComposable contract

• Add @ReadOnlyComposable when every composable call your body makes is itself @ReadOnlyComposable (or there are no composable calls at all — for example a function that only reads LocalFoo.current and returns a value).
• Don't add it if you call any non-read-only composable. The optimization assumes you don't participate in composition; violating that produces incorrect recomposition behaviour for callers.

// ✅ GOOD — only reads composition locals, no layout, no remember
@Composable
@ReadOnlyComposable
fun appSpacing(): Dp = LocalDimensions.current.spacing

// ✅ GOOD — composable property getter; same rule
val accent: Color
    @Composable @ReadOnlyComposable
    get() = MaterialTheme.colorScheme.tertiary

// ❌ BAD — annotated read-only but lays out a Box; contract violated
@Composable
@ReadOnlyComposable
fun Header(): Int {
    Box {}                  // ← non-read-only composable call
    return 42
}

// ❌ BAD — calls a normal composable from a read-only one
@Composable
@ReadOnlyComposable
fun computed(): Int = nonReadOnlyHelper()

Heuristic for "should I add it"

• A layout call: Box, Column, Row, LazyColumn, Text, anything from androidx.compose.foundation.layout or androidx.compose.material*.
• A side-effect call: LaunchedEffect, DisposableEffect, SideEffect, produceState.
• remember { … } — positional memoization is composition state.
• A @Composable lambda invocation (content()).
• An invocation of a non-@ReadOnlyComposable composable function.

When this rule does NOT apply

• override fun declarations. The annotation is part of the contract; if the base isn't @ReadOnlyComposable, you can't make an override one. Refactor the base, or accept the override pays the group-creation cost.
• Abstract declarations. No body to check.

Related: side effects live in their own skill

Quick reference

When NOT to apply

• Tests with composeTestRule.setContent { … } follow the same rules — they're production composables.
• produceState has its own producer block that runs in a coroutine; you don't need LaunchedEffect inside it.
• derivedStateOf has its own concerns around stability and equality — out of scope here; it's about preventing recomposition, not authoring state.
• overrides of read-only-composable declarations: the annotation is fixed by the base; you can't add or remove it locally.

Red flags during review