1. Verify, do not recall. Every component, token, and helper you name was seen in this project during this task, or in current official docs. Name an unverified need as an open gap, never call it.
2. Check the question before answering it. Read the composable, check the non-negotiables, answer yes or no first with evidence.
3. Say no when the answer is no. State the correct approach. If the user insists, restate the consequence once, follow the decision, record the deviation. Keep pushback short, plain-spoken and proportional (see the

   compose-architecture

   skill, Operating stance items 7–11). Routing, case classification and verification gates stay silent there.
4. Fresh docs before new library code. Read

   gradle/libs.versions.toml

   and the current official docs first; unreachable docs means marking the code unverified.

Iron law: read depth decides cost. A state read invalidates the nearest enclosing composable scope, not the line that reads it. When a screen re-executes too often, move the read down to the leaf that renders it, never wrap the scope in

remember

. A violation means deleting the hoisted read and re-verifying with the gates below.

compose-architecture

existing-projects.md

1. Only the Route touches the ViewModel. The Screen is stateless (state in, callbacks out). Leaves take sub-state plus specific callbacks, never

   onAction

   . A Screen that reads the ViewModel doubles every entry point; a leaf that takes

   onAction

   can dispatch anything. Prevents: entry-point duplication and unreviewable leaves.
2. Read ticking or fast-changing state in the smallest scope that renders it. Never read it in a screen body, a

   Scaffold

   content lambda, or a lazy-list builder scope and pass the snapshot value down. When a deep consumer needs fast-changing state, pass the

   State

   or a lambda, not the read value. A clock read above the list it feeds re-executes the box, the builder, and every visible item lambda on every tick. Prevents: per-tick list invalidation (brief F-15).
3. Clock- and animation-driven values never enter

   UiState

   as formatted strings.

   UiState

   and UiModels carry the

   Instant

   ; formatting happens in the presentation mapper or at display. A per-second

   updateState

   of a remaining-time string invalidates every collector of that state. Prevents: unrestorable ticked state and whole-screen invalidation.
4. [Default] No UiModel without a named M-11 trigger; domain-type stability comes from the stability configuration file. Strong skipping is on by default: unstable parameters are compared by instance (

   ===

   ), stable ones by

   equals

   . Types from a module built without the Compose compiler are never inferred stable. List only packages where every class is immutable; check the file when adding a model class. Also declare

   kotlin.collections.*

   (wired by build-logic).

   @Immutable

   is a promise the compiler believes without checking: apply it only when the class is genuinely immutable, or in-place mutation renders stale UI no recomposition fixes. Convert third-party unstable types at the boundary into a type the kit owns (

   LoadState.Error

   holds a

   Throwable

   ; present

   AppError

   instead). Never add a wrapper only for stability. Prevents: lost skipping and stale UI (brief F-16, F-17; M-11).
5. Colors come from theme tokens only; no hex literals in feature code. A hardcoded badge color misses every theme change. Prevents: theme breakage the guard catches.
6. Reuse before writing: search the design-system module first. New shared components live in the design-system module, never in a feature. Copy a component together with the conditions at its call site. Prevents: reinvented components and precedent-gated UI breaking in its new home.
7. Never clear or hide existing content during a refresh. Failure tiers live in the

   compose-architecture

   skill (rule 8): skeletons for the cold load only, refresh keeps content with an indicator, a failed refresh keeps the items with a Retry holding it. Prevents: wiped content and trapped screens.
8. Every lazy list item has a stable key from domain identity plus a

   contentType

   ; never the index. Keep item scope light: hoist parsing and formatting out of item scope. Prevents: scrambled row state and per-tick parsing.
9. Every user-facing string is a resource, present in every locale. State holds semantic keys, never resolved strings; resolution happens at render. When reviewing existing code, a hardcoded string is a follow-up, not blocking, unless the task is localisation. Prevents: untranslated UI and locale drift the guard catches.
10. Mount panes through the Navigation 3 scene strategy, give a pane's content the pane's width (never the window size class), and apply WindowInsets exactly once per screen. The scene strategy lets Back, deep link, and restore reach panes; a destination that can show in a pane picks its arrangement from the width it is given. Insets come from either the Scaffold inner padding or manual padding, never both, with

    consumeWindowInsets

    chained after the applying padding. Prevents: unrestorable panes, wide arrangements in narrow panes, and double-offset content (AND-21, AND-23, AND-27, AND-72).
11. Code in

    commonMain

    never imports

    java.*

    ,

    android.*

    ,

    LocalContext

    , or

    R

    ; inject dispatchers and use

    Dispatchers.Default

    as the shared default. A

    java.time.Instant

    or

    LocalContext

    reference compiles on Android and breaks every other target. Time is

    kotlin.time.Instant

    ; strings are CMP

    Res

    accessors.

    Dispatchers.IO

    exists on Kotlin/Native since coroutines 1.7.0 but is unavailable when the module also targets JS/Wasm. Prevents: shared code that compiles on only some targets.
12. Adapt layouts to the window size class, never the device or platform, even when the request names

    NotesTabletScreen

    or

    isTablet

    . One

    <Dest>Screen

    branches once on a

    <Dest>Layout

    value derived from the class the composition root computed; variants are named after the smallest class they serve (

    NotesExpandedLayout

    ). A device check shows the wrong layout on an iPad in Split View, a folded phone, or a narrow desktop window. Prevents: device branches and

    *TabletScreen

    copies that drift apart.

• Create one todo per step below and do them in order.
• Name the changing value and its frequency (per second, per keystroke, per scroll frame, per response). The frequency sets the budget.
• Name the smallest scope that must re-execute when it changes. Usually a single leaf.
• Find where the read happens today. A gap between the read and the scope is the defect.
• Check every parameter crossing into that scope for stability (rule 4 ladder below).
• Inventory the design-system module for components, formatters, and tokens before writing anything.
• Pick loading, empty, error, and validation visuals from the

  ux-states.md

  decision tables.
• Run the Verification gates below.

• Only the Route references the ViewModel; the Screen takes state plus callbacks (

  rg -n "ViewModel|koinViewModel|collectAsState" --glob '*Screen.kt' --glob '*Sheet.kt'

  shows ViewModel reads only in

  *Route.kt

  ).
• No

  rememberSaveable

  mirror of a

  UiState

  field and no

  LaunchedEffect

  syncing two copies of one value (see the

  compose-architecture

  skill, rules 9–10): yes or no.
• No formatted countdown or clock string on

  UiState

  ; the clock is read at the leaf that renders it: yes or no.
• The compiler stability report marks every owned

  UiState

  /

  UiModel

  stable; every

  @Immutable

  holds only

  val

  s of immutable types (see

  performance-diagnostics.md

  for the loop).

• rg -n "Color\(0x" --glob '*.kt' <feature-root>

  is empty outside the design-system module (guard

  check-hardcoded-colors.sh

  ).
• Every

  items(

  /

  item(

  call in a lazy list carries a

  key

  from domain identity and a

  contentType

  : yes or no.
• Strings exist in every locale folder with identical keys (guard

  check-locale-parity.sh

  ).

• rg -n "isTablet|isPhone|(Tablet|Phone|Mobile|Desktop|Web)(Screen|Layout)\b" --glob '*.kt' <feature-root>

  is empty.
• Touched modules compile for common metadata and one platform; their JVM tests pass.

• Also read review-mode.md when reviewing a feature UI change.
• Also read ui-testing.md when changing UI behavior.
• state-reads-and-stability.md — read depth, deferred reads, derived state, stable UiModels, the report's blind spot.
• ux-states.md — skeleton vs keep-content vs spinner, validation, disabled vs hidden.
• lists.md — keys, contentType, item-scope work, grids, nesting, paging hookup.
• motion.md — animation API choice, graphicsLayer, gestures.
• shared-elements.md — shared-element choice, keys, modifier order, overlay.
• accessibility.md — semantics, touch targets, contrast, actions, RTL.
• design-system.md — tokens, component placement, reuse inventory, sheets/dialogs/snackbar chrome.
• resources.md — CMP

  Res

  vs Android

  R

  , qualifiers, locale parity, imports, maps.
• resources-media.md — icons, fonts, raw files and remote content.
• images.md — Coil 3 setup and API choice, placeholders, caching, CMP placement.
• keyboard-and-focus.md — focus on arrival, IME actions, dismiss rules.
• modifiers.md — modifier order, custom

  Modifier.Node

  , lambda (deferred-read) modifiers.
• adaptive-layouts.md — adaptive shape per destination, size class not device, layout variants and naming, pane widths, scene-strategy panes.
• edge-to-edge-and-insets.md — edge-to-edge, insets exactly once, keyboard and IME.
• performance-diagnostics.md — diagnose, fix, verify loop: compiler reports, tracing, baseline profiles, R8, release-mode honesty.