Write idiomatic Kotlin
Kotlin's value is safety made concise: nullability in the type, immutability by default,
structured concurrency that cannot leak. For the builder and the reviewer of a Kotlin diff; the module's config and existing code win over it.
Procedure
- Discover the module's conventions first. Call
search_lore for Kotlin conventions.
Read build.gradle.kts, gradle/libs.versions.toml (Kotlin, coroutines, AGP versions),
jvmToolchain, whether explicitApi() is on, .editorconfig (ktlint reads
ktlint_code_style and rule toggles there), detekt.yml and its baseline, and Android
lint.xml. Identify Android vs server vs multiplatform, the DI framework
(Hilt/Koin/Spring), how dispatchers are injected, and the state pattern (MVVM/MVI with
StateFlow, or a service layer). Copy a sibling class and its test.
- Pin the exact commands from CI (the
run-tests and run-lint skills). Use the
defaults below only when the repo defines none; never add to a detekt baseline to pass.
- Write the change with the idioms below, then walk the concurrency section for every
coroutine, flow, shared value and resource you touched.
- Test each acceptance criterion's own behaviour. One test per AC that fails without
your change, plus its error path, using
runTest with the test dispatcher and Turbine
for flows. If the AC involves shared state or persistence, add a test that launches N
concurrent coroutines on a multi-threaded dispatcher (Dispatchers.Default) and
asserts the invariant.
- Verify, then stop. Done when: ktlint and detekt are clean at the repo's config, the
compiler reports no new warnings where
allWarningsAsErrors is set, tests are green,
and every AC has a test. Record the output with the record-evidence skill; the runner
submits the work.
Commands
- All checks:
./gradlew check (runs tests plus wired-in linters).
- Style:
./gradlew ktlintCheck (ktlint Gradle plugin) or ktlint "src/**/*.kt";
./gradlew detekt.
- Tests:
./gradlew test; one class: ./gradlew test --tests 'pkg.ClassTest'.
- Android:
./gradlew lint testDebugUnitTest (or the repo's variant).
- Dependencies: a new or bumped entry in
libs.versions.toml or the build file is a
blocker: mark_ticket_blocked with the exact command a human should run.
Idioms that matter
- Types:
data class for values, sealed interface for closed state and results,
enum class for fixed sets, @JvmInline value class for ids and units; exhaustive
when over sealed types with no else, so a new case fails to compile.
- Null-safety: non-null by default;
?., ?:, requireNotNull(x) { "why" } at
boundaries; no !! on reachable paths; lateinit only for framework-injected fields.
Java calls return platform types (String!): give them an explicit nullable or
non-null type at the boundary.
- Immutability:
val and read-only List/Map in APIs; build with
buildList { } locally; update data classes with copy(). A data class with var
properties used as a map key or set element breaks lookups when mutated.
- Preconditions with
require (arguments), check (state), error(...) (unreachable).
- Resources:
use { } on every Closeable.
- Coding conventions (kotlinlang.org): expression bodies for one-liners, named
arguments for boolean and same-typed parameters, scope functions (
let/apply/also)
only where they read better than a local.
Concurrency and resource safety
- Structured concurrency: every coroutine runs in a scope that ends
(
viewModelScope, lifecycleScope, a service scope with a SupervisorJob cancelled on
shutdown). No GlobalScope; no runBlocking outside main and tests.
- Cancellation is an exception — do not eat it.
catch (e: Exception) and
runCatching { suspendCall() } also catch CancellationException, so the coroutine
keeps running after it was cancelled. Rethrow it (or catch narrower types); in loops call
ensureActive(); cleanup that must suspend goes in withContext(NonCancellable).
- Dispatchers are injected; blocking I/O uses
withContext(ioDispatcher); never block
Dispatchers.Main or Default.
async without await loses its exception until someone awaits; use launch for
fire-and-forget within a scope, and coroutineScope { } to fan out and fail together.
- Shared mutable state:
MutableStateFlow.value = value + 1 is a lost-update race; use
update { it + 1 }. Guard other state with kotlinx.coroutines.sync.Mutex (a
synchronized block cannot contain a suspension point) and hold it across the whole
read-modify-write; bound fan-out with Semaphore.
- Flows:
flowOn for upstream context, catch for upstream errors, stateIn/shareIn
in a scope that ends; UI collects with collectAsStateWithLifecycle or
repeatOnLifecycle; one-shot events via Channel or SharedFlow(replay = 0).
- Files other requests read (server/JVM): write to
Files.createTempFile(targetDir, …) then Files.move(…, ATOMIC_MOVE, REPLACE_EXISTING);
never a fixed temp name. Cross-process exclusion uses a file lock or the database; a
time-only lease lets a paused holder write late, so writes must check a fencing token or
version.
Review checklist — flag as defects
Walk this against the diff. An item is grounds for CHANGES only when, in changed code, it
causes a concrete failure (wrong result, crash, lost or corrupted data, security hole) or
leaves an AC's own behaviour untested: cite the line and that failure. Otherwise it is an
(optional) note. Formatting the tools would fix, and preferences the repo
does not enforce, are not findings. Do not patch the code under review.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While matching the module you learn the DI framework, how dispatchers are injected and which state-holder pattern the UI uses. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
1---2name: kotlin-conventions3description: Use when a ticket adds or changes Kotlin code — Android, Ktor/Spring services, multiplatform modules — and it must follow the repo's Kotlin conventions — the Kotlin coding conventions, null-safety without !!, immutability by default, coroutines and Flow used with structured concurrency and correct cancellation, sealed hierarchies for state, detekt/ktlint clean — as the language pack for any Kotlin change. Invoke for "write this in Kotlin", "fix the coroutine leak", "remove the !!", or when reviewing a Kotlin diff.4stack: [kotlin, android, jvm]5area: language6metadata:7 source: https://skillmd.com/skills/tmj-90/kotlin-conventions8---910# Write idiomatic Kotlin1112Kotlin's value is safety made concise: nullability in the type, immutability by default,13structured concurrency that cannot leak. For the builder and the reviewer of a Kotlin diff; the module's config and existing code win over it.1415## Procedure16171. **Discover the module's conventions first.** Call `search_lore` for Kotlin conventions.18 Read `build.gradle.kts`, `gradle/libs.versions.toml` (Kotlin, coroutines, AGP versions),19 `jvmToolchain`, whether `explicitApi()` is on, `.editorconfig` (ktlint reads20 `ktlint_code_style` and rule toggles there), `detekt.yml` and its baseline, and Android21 `lint.xml`. Identify Android vs server vs multiplatform, the DI framework22 (Hilt/Koin/Spring), how dispatchers are injected, and the state pattern (MVVM/MVI with23 `StateFlow`, or a service layer). Copy a sibling class and its test.242. **Pin the exact commands** from CI (the `run-tests` and `run-lint` skills). Use the25 defaults below only when the repo defines none; never add to a detekt baseline to pass.263. **Write the change with the idioms below**, then walk the concurrency section for every27 coroutine, flow, shared value and resource you touched.284. **Test each acceptance criterion's own behaviour.** One test per AC that fails without29 your change, plus its error path, using `runTest` with the test dispatcher and Turbine30 for flows. If the AC involves shared state or persistence, add a test that launches N31 concurrent coroutines on a multi-threaded dispatcher (`Dispatchers.Default`) and32 asserts the invariant.335. **Verify, then stop.** Done when: ktlint and detekt are clean at the repo's config, the34 compiler reports no new warnings where `allWarningsAsErrors` is set, tests are green,35 and every AC has a test. Record the output with the `record-evidence` skill; the runner36 submits the work.3738## Commands3940- All checks: `./gradlew check` (runs tests plus wired-in linters).41- Style: `./gradlew ktlintCheck` (ktlint Gradle plugin) or `ktlint "src/**/*.kt"`;42 `./gradlew detekt`.43- Tests: `./gradlew test`; one class: `./gradlew test --tests 'pkg.ClassTest'`.44- Android: `./gradlew lint testDebugUnitTest` (or the repo's variant).45- Dependencies: a new or bumped entry in `libs.versions.toml` or the build file is a46 blocker: `mark_ticket_blocked` with the exact command a human should run.4748## Idioms that matter4950- **Types**: `data class` for values, `sealed interface` for closed state and results,51 `enum class` for fixed sets, `@JvmInline value class` for ids and units; exhaustive52 `when` over sealed types with no `else`, so a new case fails to compile.53- **Null-safety**: non-null by default; `?.`, `?:`, `requireNotNull(x) { "why" }` at54 boundaries; no `!!` on reachable paths; `lateinit` only for framework-injected fields.55 Java calls return platform types (`String!`): give them an explicit nullable or56 non-null type at the boundary.57- **Immutability**: `val` and read-only `List`/`Map` in APIs; build with58 `buildList { }` locally; update data classes with `copy()`. A `data class` with `var`59 properties used as a map key or set element breaks lookups when mutated.60- **Preconditions** with `require` (arguments), `check` (state), `error(...)` (unreachable).61- **Resources**: `use { }` on every `Closeable`.62- **Coding conventions** (kotlinlang.org): expression bodies for one-liners, named63 arguments for boolean and same-typed parameters, scope functions (`let`/`apply`/`also`)64 only where they read better than a local.6566## Concurrency and resource safety6768- **Structured concurrency**: every coroutine runs in a scope that ends69 (`viewModelScope`, `lifecycleScope`, a service scope with a `SupervisorJob` cancelled on70 shutdown). No `GlobalScope`; no `runBlocking` outside `main` and tests.71- **Cancellation is an exception — do not eat it.** `catch (e: Exception)` and72 `runCatching { suspendCall() }` also catch `CancellationException`, so the coroutine73 keeps running after it was cancelled. Rethrow it (or catch narrower types); in loops call74 `ensureActive()`; cleanup that must suspend goes in `withContext(NonCancellable)`.75- **Dispatchers are injected**; blocking I/O uses `withContext(ioDispatcher)`; never block76 `Dispatchers.Main` or `Default`.77- **`async` without `await`** loses its exception until someone awaits; use `launch` for78 fire-and-forget within a scope, and `coroutineScope { }` to fan out and fail together.79- **Shared mutable state**: `MutableStateFlow.value = value + 1` is a lost-update race; use80 `update { it + 1 }`. Guard other state with `kotlinx.coroutines.sync.Mutex` (a81 `synchronized` block cannot contain a suspension point) and hold it across the whole82 read-modify-write; bound fan-out with `Semaphore`.83- **Flows**: `flowOn` for upstream context, `catch` for upstream errors, `stateIn`/`shareIn`84 in a scope that ends; UI collects with `collectAsStateWithLifecycle` or85 `repeatOnLifecycle`; one-shot events via `Channel` or `SharedFlow(replay = 0)`.86- **Files other requests read** (server/JVM): write to87 `Files.createTempFile(targetDir, …)` then `Files.move(…, ATOMIC_MOVE, REPLACE_EXISTING)`;88 never a fixed temp name. Cross-process exclusion uses a file lock or the database; a89 time-only lease lets a paused holder write late, so writes must check a fencing token or90 version.9192## Review checklist — flag as defects9394Walk this against the diff. An item is grounds for CHANGES only when, in changed code, it95causes a concrete failure (wrong result, crash, lost or corrupted data, security hole) or96leaves an AC's own behaviour untested: cite the line and that failure. Otherwise it is an97`(optional)` note. Formatting the tools would fix, and preferences the repo98does not enforce, are not findings. Do not patch the code under review.99100- [ ] `!!` on a reachable path; an unexplained `lateinit`; a Java platform type flowing101 into Kotlin unannotated.102- [ ] `else` on a `when` over a sealed type the module owns.103- [ ] `GlobalScope`, a scope never cancelled, or `runBlocking` in production code.104- [ ] `CancellationException` swallowed by `catch (e: Exception)` or `runCatching` around105 suspend calls.106- [ ] Blocking I/O on Main/Default; a hard-coded dispatcher where the module injects them.107- [ ] A read-modify-write on shared state (`StateFlow.value`, a map, a counter) without108 `update`, a `Mutex` or an atomic; a check-then-act across a suspension point.109- [ ] A `Closeable` not in `use { }`; a flow collected outside a lifecycle-aware scope.110- [ ] A shared file written in place or via a fixed temp name; a time-only lock lease.111- [ ] Mutable collections or `var`s exposed from a public API.112- [ ] A new detekt/ktlint suppression or baseline entry without a reason.113- [ ] An AC has no test, or a coroutine test uses real delays or `Thread.sleep` instead114 of the test dispatcher.115116## Capture lore117118This skill is one of the places durable, reusable knowledge naturally surfaces:119**While matching the module you learn the DI framework, how dispatchers are injected and which state-holder pattern the UI uses.** That kind of fact is *lore*. Capture it via the **lore-capture120protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):121call the Memory MCP `suggest_lore` once at the close of your work — reusable122conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.