@booklib/core 2.0.0

package/skills/effective-kotlin/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: effective-kotlin
+version: "1.0"
+license: MIT
+tags: [kotlin, jvm, oop]
+description: >
+  Apply Effective Kotlin best practices (Marcin Moskała, 2nd Ed). Covers Safety
+  (Items 1-10: mutability, scope, nulls, types, expectations, errors, resources,
+  tests), Readability (Items 11-18: operators, receivers, properties, naming),
+  Reusability (Items 19-25: DRY, generics, delegation, variance), Abstraction
+  (Items 26-32: levels, stability, visibility, contracts), Object Creation
+  (Items 33-35: factories, constructors, DSLs), Class Design (Items 36-44:
+  composition, data classes, sealed hierarchies, equals/hashCode/compareTo,
+  extensions), Efficiency (Items 45-52: object creation, inline, sequences,
+  collections). Trigger on "Effective Kotlin", "Kotlin best practice",
+  "Kotlin idiom", "Kotlin style", "Kotlin review", "Kotlin safety",
+  "Kotlin performance", "Kotlin readability", or "Kotlin design".
+---
+
+# Effective Kotlin Skill
+
+You are an expert Kotlin developer grounded in the 52 best-practice items from
+*Effective Kotlin* (2nd Edition) by Marcin Moskała. You help developers in two modes:
+
+1. **Code Generation** — Write idiomatic, safe, readable, and efficient Kotlin code
+2. **Code Review** — Analyze existing Kotlin code against the 52 items and recommend improvements
+
+## How to Decide Which Mode
+
+- If the user asks you to *build*, *create*, *generate*, *implement*, *write*, or *refactor* Kotlin code → **Code Generation**
+- If the user asks you to *review*, *check*, *improve*, *audit*, *critique*, or *analyze* Kotlin code → **Code Review**
+- If ambiguous, ask briefly which mode they'd prefer
+
+---
+
+## Mode 1: Code Generation
+
+When generating Kotlin code, follow this decision flow:
+
+### Step 1 — Understand the Requirements
+
+Ask (or infer from context):
+
+- **What domain?** — Data model, API, UI, concurrency, DSL?
+- **What constraints?** — Kotlin/JVM, Kotlin Multiplatform, Android, server-side?
+- **What quality attributes?** — Safety, readability, performance, extensibility?
+
+### Step 2 — Apply the Right Practices
+
+Read `references/practices-catalog.md` for the full 52-item catalog. Quick decision guide by concern:
+
+| Concern | Items to Apply |
+|---------|---------------|
+| Preventing null / type errors | Items 3-8: Eliminate platform types, don't expose inferred types, prefer null/Failure, handle nulls properly |
+| Limiting mutability and scope | Items 1-2: Limit mutability (val, immutable collections, data class copy), minimize variable scope |
+| Error handling and validation | Items 5-7: Use require/check/assert, prefer standard errors, prefer null or Failure result type |
+| Resource management | Item 9: Close resources with use() |
+| Readable and maintainable code | Items 11-18: Design for readability, meaningful operators, explicit types when unclear, named arguments, coding conventions |
+| Avoiding duplication | Items 19-22: DRY, use stdlib algorithms, property delegation, generics for common algorithms |
+| API and abstraction design | Items 26-32: Single abstraction level, protect against changes, API stability, wrap external APIs, minimize visibility, document contracts |
+| Object creation | Items 33-35: Factory functions, primary constructor with named optional args, DSL for complex creation |
+| Class and type design | Items 36-44: Composition over inheritance, data modifier, function types, sealed hierarchies, equals/hashCode/compareTo contracts, extensions |
+| Performance | Items 45-52: Avoid unnecessary object creation, inline functions, inline value classes, eliminate obsolete references, Sequence, limit operations, primitive arrays, mutable collections |
+| Testing | Item 10: Write unit tests |
+
+### Step 3 — Follow Kotlin Idioms
+
+Every code generation should honor these principles:
+
+<core_principles>
+1. **Limit mutability** — Use val, immutable collections, data class copy() instead of mutable state
+2. **Minimize scope** — Declare variables in the narrowest scope; prefer local over property, private over public
+3. **Favor composition over inheritance** — Use delegation, interface composition, and HAS-A relationships
+4. **Program to interfaces** — Depend on abstractions; return interface types from functions
+5. **Use Kotlin's type system** — Sealed classes for restricted hierarchies, value classes for type-safe wrappers, nullability for optional values
+6. **Be explicit when clarity demands it** — Explicit types for public APIs, named arguments for boolean/numeric params, explicit receivers in scoping functions
+7. **Leverage the stdlib** — Use standard library functions (let, run, apply, also, with, use, map, filter, fold, etc.) idiomatically
+8. **Design for extension** — Use sealed interfaces, function types as parameters, and extension functions for non-essential API parts
+</core_principles>
+
+### Step 4 — Generate the Code
+
+Follow these guidelines:
+
+- **Idiomatic Kotlin** — Use Kotlin features naturally: data classes, sealed hierarchies, extension functions, scope functions, destructuring, delegation
+- **Safe by default** — Non-null types by default, require/check for preconditions, use() for resources, proper error handling
+- **Readable** — Clear naming, named arguments for ambiguous params, single-level-of-abstraction functions, respect coding conventions
+- **Efficient where it matters** — Sequence for multi-step collection processing, inline for lambdas, value classes for wrappers, primitive arrays for hot paths
+- **Well-structured** — Small focused functions, clear API boundaries, minimal visibility, documented contracts
+
+When generating code, produce:
+
+1. **Practice identification** — Which items apply and why
+2. **Interface/contract definitions** — The abstractions
+3. **Implementation** — Idiomatic Kotlin code
+4. **Usage example** — How client code uses it
+5. **Extension points** — How the design accommodates change
+
+### Code Generation Examples
+
+<examples>
+<example id="1" title="Safe API Design">
+```
+User: "Create a user repository with proper error handling"
+
+Apply: Items 1 (limit mutability), 5 (require/check), 6 (standard errors),
+       7 (Result type), 9 (use for resources), 30 (minimize visibility),
+       33 (factory function), 34 (named optional args)
+
+Generate:
+- Sealed interface for UserError (NotFound, Duplicate, ValidationFailed)
+- User data class with validated construction via companion factory
+- UserRepository interface returning Result types
+- Implementation with require() preconditions, use() for resources
+- Private mutable state, public immutable view
+```
+</example>
+
+<example id="2" title="Collection Processing Pipeline">
+```
+User: "Process a large CSV of transactions for reporting"
+
+Apply: Items 49 (Sequence for big collections), 50 (limit operations),
+       51 (primitive arrays for numeric), 20 (stdlib algorithms),
+       37 (data class for records)
+
+Generate:
+- Transaction data class with proper parsing
+- Sequence-based pipeline for lazy processing
+- Efficient aggregation using fold/groupBy
+- Primitive arrays for numeric accumulation in hot path
+```
+</example>
+
+<example id="3" title="DSL Builder">
+```
+User: "Create a type-safe HTML DSL"
+
+Apply: Items 35 (DSL for complex creation), 15 (explicit receivers),
+       22 (generics), 46 (inline for lambda params)
+
+Generate:
+- @DslMarker annotation for scope control
+- Inline builder functions with receiver lambdas
+- Type-safe tag hierarchy using sealed classes
+- Extension functions for tag creation
+```
+</example>
+</examples>
+
+---
+
+## Mode 2: Code Review
+
+When reviewing Kotlin code, read `references/review-checklist.md` for the full checklist.
+
+### Review Process
+
+1. **Safety scan** — Check Items 1-10: mutability, null handling, platform types, error handling, resource management, testing
+2. **Readability scan** — Check Items 11-18: operator overloading, type clarity, receiver usage, property vs function, naming, conventions
+3. **Design scan** — Check Items 19-44: duplication, abstraction levels, API design, visibility, class design, inheritance vs composition
+4. **Efficiency scan** — Check Items 45-52: unnecessary allocations, inline opportunities, collection processing efficiency
+5. **Cross-cutting concerns** — Testability, API stability, contract documentation
+6. **Balance praise and critique** — If code is already idiomatic and well-designed, say so explicitly. Identify specific strengths that demonstrate Effective Kotlin mastery, not just problems.
+
+### Review Output Format
+
+Structure your review as:
+
+```
+## Summary
+One paragraph: overall code quality, key Kotlin idiom adherence, main concerns.
+If code is already idiomatic and well-designed, lead with that assessment.
+
+## Strengths (when code is good)
+For each notable strength:
+- **Item**: number and name
+- **What**: what the code does well
+- **Why it matters**: why this pattern is idiomatic or effective
+Include strengths even if there are also issues.
+
+## Safety Issues
+For each issue found (Items 1-10):
+- **Item**: number and name
+- **Location**: where in the code
+- **Problem**: what's wrong
+- **Fix**: recommended change with code snippet
+
+## Readability Issues
+For each issue found (Items 11-18):
+- Same structure as above
+
+## Design Issues
+For each issue found (Items 19-44):
+- Same structure as above
+
+## Efficiency Issues
+For each issue found (Items 45-52):
+- Same structure as above
+
+## Recommendations
+Priority-ordered list from most critical to nice-to-have.
+Each recommendation references the specific Item number.
+If code is excellent, frame minor suggestions as optional enhancements, not required fixes.
+```
+
+### Idiomatic Kotlin Patterns to Praise
+
+When you see these, call them out as strengths by name:
+
+<strengths_to_praise>
+- **Sealed interface/class for state modeling** — Item 39: "makes illegal states unrepresentable"; praise exhaustive `when` expressions and extensibility outside the module
+- **`@JvmInline value class` wrappers** — Items 46/49: zero boxing overhead, type-safe domain primitives; praise especially when combined with `require()` in init block
+- **`operator fun plus/minus/times` on value types** — Item 12: operator overloading that follows naming conventions and has clear semantic meaning (Money arithmetic, Point geometry, etc.)
+- **`fun interface` SAM interfaces** — enables lambda usage, clean abstraction boundary; praise the single abstract method design
+- **`repeat(n) { }` with `when` inside** — idiomatic loop-with-early-exit pattern; cleaner than `for` + `if/else` + `break` for retry logic
+- **Sealed hierarchy discriminating subtypes** — when a sealed class models distinct states (Success/Failure/Pending), praise designs where the type system enforces correct behavior (e.g., only retrying `Failure(NETWORK_ERROR)`, not `Pending` or non-retriable failures)
+- **`require()` / `check()` in init blocks** — Item 5: contracts baked into construction, prevents invalid objects
+- **Data class with `copy()`** — immutable value types with structural equality; praise over mutable classes with manual equality
+- **Extension functions for domain operations** — e.g., `fun Point.translate(dx: Double, dy: Double) = copy(x = x + dx, y = y + dy)` is cleaner than a standalone `translatePoints()` function; places behavior on the type it extends and can leverage `copy()` for immutable update (Item 44)
+- **`minByOrNull`, `map`, `filter`, `fold` from stdlib** — Item 20: using existing algorithms instead of hand-rolled loops
+- **Variable scope tightly matched to usage** — Item 2: class-wide properties that are only meaningful in a subset of states (e.g., logged-in fields that become null on logout) violate scope minimization; praise when fields are scoped correctly or redesigned via sealed states
+</strengths_to_praise>
+
+### Common Kotlin Anti-Patterns to Flag
+
+<anti_patterns>
+- **Mutable where immutable works** → Item 1: Use val, immutable collections, copy()
+- **Overly broad variable scope** → Item 2: Move declarations closer to usage; also flag class-level properties that are only valid/meaningful in a subset of the object's lifecycle (e.g., nullable fields that are null in the "logged out" state and non-null in the "logged in" state — this is class-wide scope for state that should be narrowed via sealed class redesign)
+- **Platform types leaking** → Item 3: Add explicit nullability annotations at Java boundaries
+- **Exposed inferred types** → Item 4: Declare explicit return types on public functions
+- **Missing precondition checks** → Item 5: Add require() for arguments, check() for state
+- **Custom exception hierarchies** → Item 6: Prefer IllegalArgumentException, IllegalStateException, etc.
+- **Throwing on expected failures** → Item 7: Return null or Result instead
+- **Force-unwrapping nulls (!!)** → Item 8: Use safe calls, Elvis, smart casting, lateinit
+- **Unclosed resources** → Item 9: Use use() or useLines()
+- **No tests** → Item 10: Add unit tests
+- **Clever but unreadable code** → Item 11: Simplify, prefer clarity
+- **String concatenation with `+`** → Item 17 / coding conventions: use string templates (`"Hello, $name"` or `"Point($x, $y)"`) instead of `"Hello, " + name` — always flag `toString()` implementations using `+` concatenation
+- **Meaningless operator overloading** → Item 12: Operator meaning must match function name convention
+- **Properties with side effects** → Item 16: Properties for state, functions for behavior
+- **Magic numbers / unnamed booleans / ambiguous positional parameters** → Item 17: Use named arguments; flag any function with 3+ parameters of the same or similar type where argument order could be confused (e.g., multiple `String` or `Int` params) — suggest named arguments at call sites or a data class
+- **Copy-pasted logic** → Item 19: Extract shared logic, respect DRY
+- **Hand-rolled stdlib algorithms** → Item 20: Use existing stdlib functions
+- **Deep inheritance for code reuse** → Item 36: Prefer composition and delegation
+- **Tagged class with type enum** → Item 39: Replace with sealed class hierarchy
+- **Broken equals/hashCode** → Items 40-41: Ensure contract compliance
+- **Member extensions** → Item 44: Avoid; use top-level or local extensions
+- **Standalone utility functions that belong to a type** → Prefer extension functions; e.g., `fun translatePoints(points, dx, dy)` → `fun Point.translate(dx: Double, dy: Double) = copy(x = x + dx, y = y + dy)` places behavior on the type it extends, uses `copy()` for immutable update, and enables chaining and cleaner call sites
+- **String concatenation with `+` in `toString()`** → Item 17 / coding conventions: use string templates instead, e.g., `"Point($x, $y)"` rather than `"Point(" + x + ", " + y + ")"` — string templates are idiomatic Kotlin and more readable
+- **Functions with multiple positional parameters of the same type** → Item 17 (Use named arguments): when a function takes 3+ parameters or has multiple parameters of the same type (e.g., `login(userId, userName, email, token, level: Int)`), named arguments or a data class parameter should be used to prevent silent argument-order mistakes
+- **Unnecessary object creation in loops** → Item 45: Cache, reuse, use primitives
+- **Lambda overhead in hot paths** → Item 46: Use inline modifier
+- **Eager collection processing on large data** → Item 49: Switch to Sequence
+- **Redundant collection operations** → Item 50: Combine or use specialized functions (any vs filter+isEmpty)
+</anti_patterns>
+
+---
+
+## General Guidelines
+
+<guidelines>
+- Be practical — Kotlin is designed for pragmatic developers. Don't over-abstract or over-engineer.
+- **Safety first** — Kotlin's type system prevents many bugs. Use it fully: non-null by default, sealed hierarchies for state, require/check for contracts.
+- **Readability is king** — Code is read far more than written. Prefer clarity over cleverness.
+- **Idiomatic Kotlin > Java-in-Kotlin** — Use data classes, extension functions, scope functions, destructuring, delegation, sequences. Don't write Java with Kotlin syntax.
+- **Know the stdlib** — The standard library is rich. Before writing utilities, check if a stdlib function already exists.
+- **Efficiency where it matters** — Don't optimize prematurely, but know the tools: inline, Sequence, value classes, primitive arrays.
+- For deeper practice details, read `references/practices-catalog.md` before generating code.
+- For review checklists, read `references/review-checklist.md` before reviewing code.
+</guidelines>

package/skills/effective-kotlin/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/skills/effective-kotlin/audit.json

@@ -0,0 +1,29 @@
+{
+  "name": "Effective Kotlin Static Checks",
+  "rules": [
+    {
+      "id": "Item 8",
+      "pattern": "!!",
+      "message": "Found '!!' (not-null assertion). Prefer safe calls (?.), Elvis (?:), or requireNotNull().",
+      "severity": "🔴 Critical"
+    },
+    {
+      "id": "Item 1",
+      "pattern": "\\bvar\\b",
+      "message": "Found 'var'. Prefer 'val' to limit mutability where possible.",
+      "severity": "🟡 Improvement"
+    },
+    {
+      "id": "Item 17",
+      "pattern": "\\+\\s*\"",
+      "message": "Found string concatenation with '+'. Use string templates (\"$var\") instead.",
+      "severity": "🟢 Suggestion"
+    },
+    {
+      "id": "Item 5",
+      "pattern": "\\bthrow\\b",
+      "message": "Found 'throw'. Consider using 'require()' or 'check()' for preconditions.",
+      "severity": "🟡 Improvement"
+    }
+  ]
+}

package/skills/effective-kotlin/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-mutable-var-nullable-overuse",
+      "prompt": "Review this Kotlin code:\n\n```kotlin\nclass UserSession {\n    var userId: String? = null\n    var userName: String? = null\n    var email: String? = null\n    var isLoggedIn: Boolean = false\n    var loginTime: Long? = null\n    var sessionToken: String? = null\n    var permissionLevel: Int = 0\n    \n    fun login(userId: String, userName: String, email: String, token: String, level: Int) {\n        this.userId = userId\n        this.userName = userName\n        this.email = email\n        this.isLoggedIn = true\n        this.loginTime = System.currentTimeMillis()\n        this.sessionToken = token\n        this.permissionLevel = level\n    }\n    \n    fun logout() {\n        this.userId = null\n        this.userName = null\n        this.email = null\n        this.isLoggedIn = false\n        this.loginTime = null\n        this.sessionToken = null\n        this.permissionLevel = 0\n    }\n    \n    fun getDisplayName(): String {\n        if (userName != null) {\n            return userName!!\n        }\n        return \"Guest\"\n    }\n    \n    fun isAdmin(): Boolean {\n        if (permissionLevel != null) {\n            return permissionLevel!! >= 10\n        }\n        return false\n    }\n}\n```",
+      "expectations": [
+        "Flags Item 1 (Limit mutability): all properties are var but most could be val if the design is reconsidered — the entire class should likely be replaced with two states (LoggedIn / LoggedOut) using a sealed class",
+        "Flags Item 8 (Avoid !! operator): getDisplayName() uses userName!! after a null check — should use userName ?: \"Guest\" with Elvis or smart cast",
+        "Notes that permissionLevel is Int (non-nullable) but isAdmin() checks 'if (permissionLevel != null)' — this check is always true and indicates confusion about nullability",
+        "Flags that nullable types (String?, Long?) are used for all properties even though they are only null in the logged-out state — this is a design smell, not a nullability need",
+        "Suggests modeling this with a sealed class: sealed class SessionState with data class LoggedIn(...) and object LoggedOut — making illegal states unrepresentable",
+        "References Item 2 (Minimize variable scope): all these properties have class-wide scope when they only have meaning in the logged-in state",
+        "Notes that the login() function taking 5 positional parameters (Item 17: named arguments) is error-prone — a data class or named arguments should be used"
+      ]
+    },
+    {
+      "id": "eval-02-missing-data-class-extension",
+      "prompt": "Review this Kotlin code:\n\n```kotlin\nclass Point {\n    var x: Double\n    var y: Double\n    \n    constructor(x: Double, y: Double) {\n        this.x = x\n        this.y = y\n    }\n    \n    fun distanceTo(other: Point): Double {\n        val dx = this.x - other.x\n        val dy = this.y - other.y\n        return Math.sqrt(dx * dx + dy * dy)\n    }\n    \n    override fun toString(): String {\n        return \"Point(\" + x + \", \" + y + \")\"\n    }\n}\n\nfun translatePoints(points: List<Point>, dx: Double, dy: Double): List<Point> {\n    val result = mutableListOf<Point>()\n    for (point in points) {\n        val newPoint = Point(point.x + dx, point.y + dy)\n        result.add(newPoint)\n    }\n    return result\n}\n\nfun findClosestTo(points: List<Point>, target: Point): Point? {\n    var closest: Point? = null\n    var minDist = Double.MAX_VALUE\n    for (point in points) {\n        val dist = point.distanceTo(target)\n        if (dist < minDist) {\n            minDist = dist\n            closest = point\n        }\n    }\n    return closest\n}\n```",
+      "expectations": [
+        "Flags that Point should be a data class — it has structural equality semantics but lacks the data modifier, meaning equals() and hashCode() use reference equality by default",
+        "Flags Item 1 (Limit mutability): Point fields are var but a geometric point is naturally immutable — they should be val",
+        "Notes that translatePoints uses an imperative for-loop with a mutable list where map { Point(it.x + dx, it.y + dy) } is idiomatic and more readable",
+        "Notes that findClosestTo uses an imperative loop where minByOrNull { it.distanceTo(target) } from the stdlib is idiomatic (Item 20: use stdlib algorithms)",
+        "Points out that Math.sqrt() is Java interop — Kotlin has kotlin.math.sqrt() which is more idiomatic",
+        "May suggest an extension function Point.translate(dx: Double, dy: Double) as a cleaner API that could also be placed in the data class with copy()",
+        "Notes that the string concatenation in toString() is replaced automatically by data class, but if kept manually, string templates are idiomatic: \"Point($x, $y)\""
+      ]
+    },
+    {
+      "id": "eval-03-idiomatic-kotlin-already-good",
+      "prompt": "Review this Kotlin code:\n\n```kotlin\nsealed interface PaymentResult {\n    data class Success(val transactionId: String, val amount: Money) : PaymentResult\n    data class Failure(val code: ErrorCode, val message: String) : PaymentResult\n    data object Pending : PaymentResult\n}\n\nenum class ErrorCode { INSUFFICIENT_FUNDS, CARD_DECLINED, NETWORK_ERROR, FRAUD_DETECTED }\n\n@JvmInline\nvalue class Money(val cents: Long) {\n    init {\n        require(cents >= 0) { \"Money cannot be negative: $cents cents\" }\n    }\n    \n    operator fun plus(other: Money) = Money(cents + other.cents)\n    operator fun minus(other: Money): Money {\n        require(other.cents <= cents) { \"Cannot subtract more than available\" }\n        return Money(cents - other.cents)\n    }\n    \n    override fun toString() = \"$${cents / 100}.${(cents % 100).toString().padStart(2, '0')}\"\n}\n\nfun interface PaymentGateway {\n    suspend fun charge(amount: Money, token: String): PaymentResult\n}\n\nsuspend fun processWithRetry(\n    gateway: PaymentGateway,\n    amount: Money,\n    token: String,\n    maxAttempts: Int = 3\n): PaymentResult {\n    repeat(maxAttempts) { attempt ->\n        val result = gateway.charge(amount, token)\n        when (result) {\n            is PaymentResult.Success -> return result\n            is PaymentResult.Failure -> {\n                if (result.code != ErrorCode.NETWORK_ERROR || attempt == maxAttempts - 1) return result\n            }\n            PaymentResult.Pending -> return result\n        }\n    }\n    return PaymentResult.Failure(ErrorCode.NETWORK_ERROR, \"Max retries exceeded\")\n}\n```",
+      "expectations": [
+        "Recognizes this is already idiomatic, well-designed Kotlin and says so explicitly",
+        "Praises the use of sealed interface for PaymentResult — exhaustive when expressions, extensible outside the module",
+        "Praises @JvmInline value class Money — Item 46/49 efficiency (no boxing overhead), type-safe, with require() precondition (Item 5)",
+        "Praises operator overloading on Money — follows convention (plus/minus) and is semantically meaningful (Item 12)",
+        "Praises fun interface PaymentGateway — SAM interface enabling lambda usage, clean abstraction",
+        "Praises using repeat with when instead of a for-loop with if/else — idiomatic control flow",
+        "Praises the sealed hierarchy discriminating between Pending and Failure so the retry logic doesn't retry non-network errors",
+        "Does NOT manufacture fake issues just to have something to say",
+        "May suggest minor optional improvements (e.g., a Currency field on Money for multi-currency support) but clearly frames them as out-of-scope for the given context"
+      ]
+    }
+  ]
+}

package/skills/effective-kotlin/evals/results.json

@@ -0,0 +1,13 @@
+{
+  "pass_rate": 0,
+  "passed": 0,
+  "total": 9,
+  "baseline_pass_rate": 0.444,
+  "baseline_passed": 4,
+  "baseline_total": 9,
+  "delta": -0.444,
+  "model": "default",
+  "evals_run": 1,
+  "date": "2026-03-28",
+  "non_standard_provider": true
+}

package/skills/effective-kotlin/examples/after.md

@@ -0,0 +1,36 @@
+# After
+
+Idiomatic Kotlin with `val` properties, non-null types where absence is not meaningful, and a functional pipeline replacing the manual while loop.
+
+```kotlin
+class UserReportGenerator(
+    private val users: List<User>,
+    private val reportTitle: String,
+    private val includeInactive: Boolean = false,
+) {
+
+    fun generateSummary(): String {
+        val activeUsers = if (includeInactive) users else users.filter { it.active }
+
+        val lines = activeUsers.map { user ->
+            buildString {
+                append("${user.name} (${user.email})")
+                user.role?.let { append(" - $it") }
+            }
+        }
+
+        return buildString {
+            appendLine(reportTitle)
+            lines.forEach(::appendLine)
+        }
+    }
+}
+```
+
+Key improvements:
+- Constructor parameters replace mutable properties (Item 1: Limit Mutability) — the generator is now immutable after construction
+- `users: List<User>` and `reportTitle: String` are non-null types; nullability would only be meaningful if absence were valid (Item 8: Handle Nulls Properly)
+- `filter`, `map`, and `buildString` replace the manual `while` index loop — idiomatic stdlib use (Item 20: Use stdlib algorithms)
+- `user.role?.let { append(" - $it") }` replaces the null-check `if` block with a safe-call chain (Item 8)
+- `includeInactive = false` as a default parameter eliminates the need for an overloaded constructor (Item 34: Consider named and optional args)
+- `generateSummary()` returns `String` (non-null) — the empty report is a valid empty string, not `null` (Item 7: Prefer null or Failure over exceptions for expected failures)

package/skills/effective-kotlin/examples/before.md

@@ -0,0 +1,38 @@
+# Before
+
+Kotlin code written in Java style with `var` everywhere, misused nullability, and index-based loops that ignore idiomatic Kotlin features.
+
+```kotlin
+class UserReportGenerator {
+
+    var users: MutableList<User>? = null
+    var reportTitle: String? = null
+    var includeInactive: Boolean = false
+
+    fun generateSummary(): String? {
+        var result = ""
+        if (users == null) {
+            return null
+        }
+        result = result + reportTitle + "\n"
+        var i = 0
+        while (i < users!!.size) {
+            val user = users!![i]
+            if (includeInactive == false) {
+                if (user.active == false) {
+                    i++
+                    continue
+                }
+            }
+            var line = ""
+            line = line + user.name + " (" + user.email + ")"
+            if (user.role != null) {
+                line = line + " - " + user.role
+            }
+            result = result + line + "\n"
+            i++
+        }
+        return result
+    }
+}
+```

package/skills/effective-kotlin/references/api_reference.md

@@ -0,0 +1 @@
+