Kotlin Code Quality Review

Evaluate Kotlin code across five quality categories and produce structured findings with concrete fixes.

Review Process

Phase 1: Triage

Scan project structure (build.gradle, source tree, imports) to determine which categories apply. SKIP categories only when the skip condition is met.

Phase 2: Parallel Scan

Run all applicable categories in PARALLEL using independent Task agents. Each agent:

1. Grep for the category's anti-patterns (see search guide below)
2. Read matched files to confirm the finding is real
3. Return findings in the output format below

Phase 3: Report

Merge parallel results into a single structured report, grouped by category and sorted by severity.

Output Format

[KT-{CATEGORY}-{NNN}] severity: CRITICAL | HIGH | MEDIUM | LOW
  Finding: <description>
  Location: <file:line>
  Fix: <concrete action>

Reference Guide — Load on Demand

Each reference file contains detailed patterns, code examples, and rationale. Read the relevant file when reviewing that category.

Anti-Pattern Search Guide

Grep-ready patterns per category. Only search categories that passed triage.

Coroutines

Flow

Null Safety

Type Design

Collections

Rules Summary

Coroutines (6 rules)

1. NEVER use GlobalScope — bind to viewModelScope/lifecycleScope/custom scope with cancellation.
2. launch exceptions don't propagate — must handle via try/catch or CoroutineExceptionHandler.
3. async Deferred must be awaited — otherwise exceptions silently lost.
4. runBlocking only in main() and tests — forbidden in production.
5. Match Dispatcher to work type: IO for I/O, Default for CPU, Main for UI only.
6. Use supervisorScope to isolate child coroutine failures.

Flow (5 rules)

1. UI collection must use repeatOnLifecycle or collectAsStateWithLifecycle.
2. MutableStateFlow/MutableSharedFlow must be private, expose as read-only.
3. catch only catches upstream — must precede collect.
4. flowOn only changes upstream Dispatcher — must precede collect.
5. stateIn for UI state (has initial value), shareIn for events (no replay).

Null Safety (5 rules)

1. !! only when compiler can't infer but you can prove non-null — must have comment.
2. Prefer requireNotNull/checkNotNull over !! for meaningful errors.
3. lateinit only for DI and lifecycle — else use lazy or nullable.
4. Flatten null chains: max 2 levels of ?. — use early return or when.
5. Unsafe as only inside when type branches — else use as? + Elvis.

Type Design (5 rules)

1. Sealed when must exhaust all subtypes — no else fallback.
2. 3+ same-type params must be wrapped in data class or use named arguments.
3. Data class fields must all be val.
4. Use value class over typealias for primitive wrappers.
5. No Pair/Triple in public API — use named data class.

Collections (5 rules)

1. No side effects in map/filter/flatMap — use onEach/forEach.
2. Public properties expose immutable collections.
3. 3+ chained operators on large collections use asSequence().
4. Scope function nesting max 1 level.
5. Prefer buildList/buildMap/buildSet over toMutableX pattern.

Checklists

Coroutines

• No GlobalScope usage
• All launch blocks have exception handling
• All async Deferred values are awaited
• No runBlocking in production code
• Dispatcher matches work type (IO/Default/Main)
• CoroutineScope bound to lifecycle or has cancellation
• Child failures isolated with supervisorScope

Flow

• UI collect uses repeatOnLifecycle or collectAsStateWithLifecycle
• MutableStateFlow/MutableSharedFlow are private
• catch precedes collect
• flowOn precedes collect
• stateIn for state, shareIn for events
• No side effects in flow {} builder

Null Safety

• No unjustified !! usage
• lateinit only for DI and lifecycle
• No 3+ level ?. chain nesting
• Unsafe as only in when type branches
• No catch-and-return-null swallowing
• Map/List access uses safe methods (getOrNull/getOrElse)

Type Design

• Sealed when exhausts all subtypes (no else)
• No 3+ same-type primitive parameters
• Data class fields all val
• No Pair/Triple in public API
• No Any as parameter or return type
• Primitive wrappers use value class not typealias

Collections

• No side effects in map/filter
• Public properties expose immutable collections
• Large collection chains use asSequence
• Scope function nesting max 1 level
• Uses buildList/buildMap over toMutableX pattern

For architecture patterns (ViewModel, UseCase, Repository), see the architecture skill. For Compose UI patterns, see the compose-ui skill. For performance optimization, see the performance skill.