Kotlin

User preferences and memory live in ~/Clawic/data/kotlin/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/kotlin/ or ~/clawic/kotlin/), move it to ~/Clawic/data/kotlin/.

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/kotlin/config.yaml.

Preference areas to record as the user reveals them:

• tooling — DI (Hilt, Koin, manual), networking client (Retrofit, Ktor client), persistence (Room, SQLDelight, Exposed, JPA), test stack (JUnit4/5, MockK, flow-testing library, Kotest) — affects which examples and setup snippets are offered
• conventions — package layout (feature vs layer), formatter/linter (ktlint, ktfmt, detekt), trailing commas, explicit types on public API, naming of sealed state hierarchies — affects generated code and review verdicts
• platform — JVM toolchain version, Android min SDK, KMP target list, whether Java sources coexist in the module — affects which floors and interop rules apply
• safety posture — tolerance for !!, experimental/opt-in APIs, warning suppression, allWarningsAsErrors — affects how hard to push back in review
• legacy bridges — RxJava, LiveData, callback APIs still in the codebase — affects whether answers stay pure-coroutine or include adapters
• output format — KDoc density, tests emitted alongside code, snippet vs full file — affects the shape of every deliverable

When To Use

• Writing or reviewing Kotlin for correctness: nullability, coroutines, collections, sealed hierarchies, equality
• Debugging Kotlin runtime surprises: NPE on a non-null type, coroutine that never finishes or never cancels, flow that stops emitting, recomposition storm, test that hangs
• Java interop and Java→Kotlin migration, including making Kotlin APIs pleasant to call from Java
• Build and compiler problems that are Kotlin's, not Gradle's: kapt/KSP, JVM-target mismatch, opt-in, K2 migration
• Sharing code across Android, iOS, JVM, or web with Kotlin Multiplatform, or writing server-side Kotlin
• Not for Java-only codebases (→ java), Android release configuration, signing and distribution (→ android), or IDE workflow (→ android-studio)

Quick Reference

Core Rules

1. Nullability is a boundary problem. Non-null Kotlin types are only as true as the code that fills them: Java, reflection-based JSON, and framework callbacks can all put null into a String. Validate at the boundary — parse into a nullable DTO, then map into a non-null domain type. An NPE thrown at the boundary names the field; one thrown three layers later names nothing.
2. !! requires an alternative to have been rejected. Decision order: value arrives later on one thread → lateinit var; computed once on first use → by lazy; legitimately absent → nullable + ?:; caller broke a contract → requireNotNull(x) { "id missing" } (throws IllegalArgumentException) or checkNotNull (IllegalStateException). Each of those produces a message; !! produces a line number and nothing else.
3. Every coroutine belongs to a scope whose lifetime is ≥ the work's. GlobalScope, and a CoroutineScope(Dispatchers.IO) stored in a field with no cancellation, are leaks by construction: an abandoned screen keeps its network call, its callbacks, and everything they captured. Structured concurrency is the guarantee that "the caller returned" means "the work is over" (→ coroutines.md).
4. Cancellation is cooperative. A cancelled coroutine keeps burning CPU until it reaches a suspension point: while (true) { transform(chunk) } with no suspend call inside never stops. Add ensureActive() (or yield()) per iteration. Cleanup that suspends after cancellation must run inside withContext(NonCancellable), or it is cancelled before it does anything.
5. Never swallow CancellationException. catch (e: Exception), catch (t: Throwable) and runCatching all capture it, converting "the parent cancelled me" into "I failed" — and the parent then waits on a child that reported success. Shape: catch (e: CancellationException) { throw e } catch (e: IOException) { … } — cancellation first, specific types after (→ errors.md).
6. StateFlow conflates by equals. Emitting a value equal to the current one runs no collector. Mutate a list in place and re-assign the same reference and nothing is emitted (the new value equals the old one), so the UI "stops updating" with no error anywhere. Publish a new immutable value: _state.update { it.copy(items = it.items + new) }.
7. Choose the dispatcher by what the code blocks on. CPU work → Dispatchers.Default (parallelism = CPU cores, minimum 2). Blocking calls, JDBC, file I/O, legacy SDKs → Dispatchers.IO (64 threads by default, property kotlinx.coroutines.io.parallelism). UI → Dispatchers.Main. For a bounded resource, size the slice to the resource: a 10-connection pool wants Dispatchers.IO.limitedParallelism(10), not 64 threads queueing for 10 connections.
8. equals, hashCode and copy see only the constructor properties. A property declared in the class body is invisible to all three: two objects differing only there are equal, collide in a HashSet, and copy() silently resets it to its initializer. copy() is also shallow — the copy shares every mutable object the original held.
9. Make when an expression. Assigned or returned, a when over a sealed type is checked for exhaustiveness, so adding a subclass breaks the build at every decision point that must change. As a bare statement it has only been an error since Kotlin >=1.7, and an else branch over a sealed hierarchy silently absorbs every case you add later.

Nullability Decision Table

Generic caveat: an unbounded T includes T?, so fun firstOr(x: T): T happily accepts null. Write `` when the parameter must be non-null.

Concurrency Primitive Selection

Equality, Copy, And Identity

• == calls equals (structural); === compares references. This is the opposite convention to Java — a Java-trained reviewer reads == as identity and approves a real bug.
• Floating point has two behaviours. With a static type of Double/Float, == is IEEE 754: Double.NaN == Double.NaN is false and 0.0 == -0.0 is true. Once the values go through a boxed or generic path (listOf(Double.NaN).contains(Double.NaN), sortedBy, distinct), Kotlin switches to total order: NaN equals itself and -0.0 < 0.0. Same values, two answers, chosen by the static type.
• hashCode must follow equals: a hand-written equals with no hashCode produces objects that are equal to each other and never found in a HashMap.
• A data class holding an Array compares by reference, because Array.equals is identity. Use List, or write equals/hashCode with contentEquals/contentHashCode.
• Value classes (@JvmInline value class) are the underlying type at runtime until they are used as a generic argument, made nullable, or passed through an implemented interface — then they box (→ performance.md).

Traps

Output Gates

Before emitting Kotlin code or a review verdict, verify:

• No !! that rule 2's decision order could have replaced?
• Every coroutine started in a scope something cancels, and every long CPU loop cooperating with cancellation?
• No catch (Exception) or runCatching around suspend code without re-throwing CancellationException?
• Every blocking call inside withContext on a dispatcher sized for the resource, and never on Main?
• Every when over a sealed type used as an expression, with no else covering future subclasses?
• Library module: explicit visibility and return types if explicit_api is on, plus @Jvm* annotations wherever Java calls in?
• State published as a new immutable value, not a mutated collection re-emitted through the same reference?

Where Experts Disagree

• Typed failures vs exceptions. Return a typed failure for expected outcomes (validation, not-found, offline); throw for broken invariants and unrecoverable I/O. The test that settles most arguments: if every caller writes try/catch around it, it was never exceptional. The contested part is kotlin.Result as a public return type — it boxes, it cannot be matched exhaustively, and it hides which failures exist, while a sealed hierarchy enumerates them (→ errors.md).
• One-shot events: Channel vs state. A Channel delivers exactly once to one consumer and survives a gap between subscribers; modelling the event as a field of the UI state with an explicit "consumed" acknowledgement survives process death but costs a round trip. Both are defensible. SharedFlow(replay = 0) is the option that quietly drops events while nobody is collecting.
• Mocks vs fakes. Kotlin classes are final by default, so mocking frameworks need bytecode tricks that make brittle tests brittler; a hand-written fake implementing the interface survives refactors. Mocks earn their keep for verifying interactions with something you do not own (→ testing.md).
• Scope-function density. One camp reads apply/also/run chains as idiomatic Kotlin, the other as write-only code. The neutral line: a scope function that removes a temporary variable is a win; nesting beyond one level is a named function waiting to be extracted.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/kotlin (install if the user confirms):

• java — the language on the other side of every interop boundary
• android — Android build system, release configuration, and deployment
• android-studio — IDE workflow: debugging, profiling, refactoring
• swift — the Swift side when Kotlin Multiplatform ships an iOS framework

Feedback

• If useful, star it: https://clawic.com/skills/kotlin
• Latest version: https://clawic.com/skills/kotlin

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/kotlin.