Use when writing a new ViewModel or modifying an existing one in the Alkaa project. Triggers on tasks like "add a ViewModel", "create VM for X screen", "implement state handling", or "connect use case to UI".
ViewModels in Alkaa bridge domain use cases and Compose UI via cold flows and sealed state classes. They contain no business logic — only orchestration, mapping, and scope management.
data object for stateless states, data class for states with data, ImmutableList for list payloads → see references/CODE_PATTERNS.mdFlow<ViewState> by default; hot StateFlow only when multiple collectors share the same stream → see references/CODE_PATTERNS.mdreferences/CODE_PATTERNS.mdapplicationScope for DB mutations that survive ViewModel destruction; viewModelScope for UI-bound work → see references/CODE_PATTERNS.mdreferences/CODE_PATTERNS.mdFor unit test setup and fake patterns → see references/CODE_PATTERNS.md and the write-unit-tests skill.
| Situation | Scope |
|---|---|
| DB insert / update / delete | applicationScope.launch { } |
| Network call that should persist | applicationScope.launch { } |
| Debounced UI updates | viewModelScope |
| Short-lived UI-bound work | viewModelScope |
| Mistake | Fix |
|---|---|
| Calling repository directly | Wrap in a use case first |
Exposing StateFlow for a screen-scoped stream | Return cold Flow<ViewState> |
| Mapping models inline in ViewModel | Create a XxxMapper class |
Using viewModelScope for DB writes | Use applicationScope.launch { } |
| Depending on another ViewModel | Extract shared logic into a use case |
| Testing with mocks | Write a XxxFake that implements the use case interface |
write-unit-tests skillwrite-composable skill