santimattius/structured-coroutines/kotlin-coroutines-skill

Kotlin Coroutines

Overview

This skill provides expert guidance on Kotlin Coroutines, covering structured concurrency, scopes, Dispatchers (including main-safe suspend and dispatcher injection), cancellation (including withTimeout semantics), exception handling (CoroutineExceptionHandler, launch vs async), Channels, Flow (cold vs hot, collectLatest, SharedFlow configuration, blocking in flow {}), lifecycle-aware collection on Android, and testing (virtual time, setMain/resetMain). Use this skill to help developers write safe, maintainable concurrent code aligned with Kotlin 1.9+/2.0+ conventions and official best practices.

Agent Behavior Contract (Follow These Rules)

1. Identify the practice or error from the user's code or question (e.g. GlobalScope,

runBlocking in suspend, swallowing CancellationException) and open the corresponding reference from the Triage table in references/.

1. Apply the strict rules below in every response. Do not suggest or leave code that violates

them.

1. Respond in the required format: Analysis → Erroneous code → Optimized code → Explanation. If

the user only asks a conceptual question (no code), skip erroneous/optimized snippets and focus on analysis and explanation.

1. Do not recommend GlobalScope in production. Use framework scopes (viewModelScope,

lifecycleScope, rememberCoroutineScope), injected scopes, or local scopes ( coroutineScope { }, withContext { }). If an external scope is required, justify and document it.

1. Use async only when a return value is needed; if await() is never called, use launch.

Preserve structured concurrency: inside suspend functions use coroutineScope { } + async/ launch; do not launch in an external scope from suspend unless work must outlive the flow, and then document it.

1. Never use runBlocking inside suspend functions or coroutine-based code. Avoid ending a suspend

function with coroutineScope { launch { } } as the last line when the intent is fire-and-forget — coroutineScope waits for all children and blocks the caller; use an explicit external scope and document it if the work must truly run in the background beyond the caller's lifetime.

1. Use explicit Dispatchers: Dispatchers.Default for CPU-bound work, Dispatchers.Main/

Main.immediate for UI, withContext(Dispatchers.IO) for blocking I/O. Never perform blocking I/O on Default or Main. Do not use Dispatchers.Unconfined in production unless for a rare, documented case. Make suspend functions main-safe: move blocking work into withContext(Dispatchers.IO) so callers on Main are never blocked. Inject CoroutineDispatcher as a constructor parameter (default to real dispatcher; replace with TestDispatcher in tests).

1. Never pass Job() or SupervisorJob() directly to builders (e.g. launch(Job()) { }). Use

supervisorScope { } or a scope defined with SupervisorJob() for supervisor semantics. When running independent tasks with awaitAll, use supervisorScope instead of coroutineScope so one failure does not cancel sibling deferreds.

1. Cancellation handling (apply all):

• Never swallow CancellationException; rethrow it in catch blocks.
• Do not use CancellationException for domain errors; use normal exceptions instead.
• In long loops and repeating/polling work, add yield(), ensureActive(), or while (isActive)

with delay(interval) so the coroutine responds to cancellation.

• For suspend calls in finally, use withContext(NonCancellable) { }.
• Do not reuse a scope after scope.cancel(); use coroutineContext.job.cancelChildren() to

stop only children while keeping the scope alive.

• Prefer withTimeoutOrNull over withTimeout to avoid unintentionally cancelling the parent

scope. If using withTimeout, catch TimeoutCancellationException explicitly. Always ensure resources opened inside withTimeout are cleaned up in finally.

1. Exception handling:

• Uncaught exceptions in launch propagate to CoroutineExceptionHandler; in async, the

exception is stored in the Deferred and only thrown on await(). Always call await() on async blocks to avoid silently losing exceptions.

• Use CoroutineExceptionHandler at scope level for launch uncaught exceptions.
• Do not wrap await()/join() in try/catch inside the same coroutineScope { } as the child:

the failure still cancels the scope. Catch around the whole coroutineScope, inside the child, or use supervisorScope.

1. In tests use kotlinx-coroutines-test: runTest, virtual time, advanceTimeBy,

advanceUntilIdle, and inject TestDispatcher/StandardTestDispatcher; avoid real delay() with runBlocking. Replace Dispatchers.Main using Dispatchers.setMain(TestDispatcher()) in @Before and Dispatchers.resetMain() in @After.

1. Prefer produce { } for channels so they close when the coroutine ends. Do not share

consumeEach across multiple consumers; use for (x in channel) per consumer.

1. Flow best practices:

• Keep flow { } builder non-blocking; use flowOn(Dispatchers.IO) or suspend APIs.
• Use StateFlow for shared UI state (replays last value); use SharedFlow for events with

explicit replay, extraBufferCapacity, and onBufferOverflow configuration.

• Use collectLatest only when cancelling in-progress work is intentional (e.g. search); use

collect when each item must be processed to completion.

• On Android, collect flows with repeatOnLifecycle(Lifecycle.State.STARTED) or

flowWithLifecycle to stop collection when the UI goes to background.

1. When several practices apply (e.g. GlobalScope + wrong Dispatchers), use each relevant reference

and combine the fixes in one optimized snippet.

Recommended Tools for Analysis

When analyzing Kotlin projects for coroutine issues:

1. Project settings

• Use Read on build.gradle.kts / build.gradle for Kotlin version, kotlinx-coroutines-*

dependencies, and kotlinx-coroutines-test.

• Use Grep for CoroutineScope, GlobalScope, runBlocking, Dispatchers,

viewModelScope, lifecycleScope to locate usage patterns.

1. Scope and lifecycle

• Identify whether code runs on Android (viewModelScope, lifecycleScope), KMP, or plain JVM to

recommend the right scope.

Triage-First Playbook (Topic / Error → Reference)

Each references/ref-*.md file is self-contained (Bad Practice, Recommended, Why, Quick fix). Open the linked file directly — no dependency on repo docs when the skill is installed standalone.