From e692a2886cb0d212a94791b0ccee2aed850bb3e9 Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Thu, 12 Mar 2026 23:47:17 -0700
Subject: [PATCH] fix: address kotlin doc review feedback

---
 .cursor/rules/kotlin-coding-style.md |  9 ++++++---
 commands/kotlin-build.md             | 10 ++++++----
 skills/kotlin-testing/SKILL.md       | 26 +++++++++++++-------------
 3 files changed, 25 insertions(+), 20 deletions(-)

diff --git a/.cursor/rules/kotlin-coding-style.md b/.cursor/rules/kotlin-coding-style.md
index e63a1bc7..ee7cd1f6 100644
--- a/.cursor/rules/kotlin-coding-style.md
+++ b/.cursor/rules/kotlin-coding-style.md
@@ -9,13 +9,16 @@ alwaysApply: false
 
 ## Formatting
 
-- **ktfmt** or **ktlint** are mandatory for consistent formatting
+- Auto-formatting via **ktfmt** or **ktlint** (configured in `kotlin-hooks.md`)
 - Use trailing commas in multiline declarations
 
 ## Immutability
 
-- `val` over `var` always
-- Immutable collections by default (`List`, `Map`, `Set`)
+The global immutability requirement is enforced in the common coding style rule.
+For Kotlin specifically:
+
+- Prefer `val` over `var`
+- Use immutable collection types (`List`, `Map`, `Set`)
 - Use `data class` with `copy()` for immutable updates
 
 ## Null Safety
diff --git a/commands/kotlin-build.md b/commands/kotlin-build.md
index bb9f5de1..01c75ccb 100644
--- a/commands/kotlin-build.md
+++ b/commands/kotlin-build.md
@@ -27,14 +27,16 @@ Use `/kotlin-build` when:
 
 ```bash
 # Primary build check
-./gradlew build
+./gradlew build 2>&1
 
 # Static analysis
-./gradlew detekt
-./gradlew ktlintCheck
+./gradlew detekt 2>&1 || echo "detekt not configured"
+./gradlew ktlintCheck 2>&1 || echo "ktlint not configured"
 
 # Dependency issues
-./gradlew dependencies --configuration runtimeClasspath
+./gradlew dependencies --configuration runtimeClasspath 2>/dev/null | head -100
+
+# Optional deep refresh when caches or dependency metadata are suspect
 ./gradlew build --refresh-dependencies
 ```
 
diff --git a/skills/kotlin-testing/SKILL.md b/skills/kotlin-testing/SKILL.md
index bfc2772f..ae326216 100644
--- a/skills/kotlin-testing/SKILL.md
+++ b/skills/kotlin-testing/SKILL.md
@@ -38,7 +38,7 @@ The following sections contain detailed, runnable examples for each testing patt
 - **Coverage** — Kover configuration and commands in [Kover Coverage](#kover-coverage)
 - **Ktor testing** — testApplication setup in [Ktor testApplication Testing](#ktor-testapplication-testing)
 
-## TDD Workflow for Kotlin
+### TDD Workflow for Kotlin
 
 ### The RED-GREEN-REFACTOR Cycle
 
@@ -105,7 +105,7 @@ fun validateEmail(email: String): Result<String> {
 // Step 6: Refactor if needed, verify tests still pass
 ```
 
-## Kotest Spec Styles
+### Kotest Spec Styles
 
 ### StringSpec (Simplest)
 
@@ -222,7 +222,7 @@ class UserValidatorTest : DescribeSpec({
 })
 ```
 
-## Kotest Matchers
+### Kotest Matchers
 
 ### Core Matchers
 
@@ -287,7 +287,7 @@ fun beActiveUser() = object : Matcher<User> {
 user should beActiveUser()
 ```
 
-## MockK
+### MockK
 
 ### Basic Mocking
 
@@ -380,7 +380,7 @@ test("spy on real object") {
 }
 ```
 
-## Coroutine Testing
+### Coroutine Testing
 
 ### runTest for Suspend Functions
 
@@ -485,7 +485,7 @@ class DispatcherTest : FunSpec({
 })
 ```
 
-## Property-Based Testing
+### Property-Based Testing
 
 ### Kotest Property Testing
 
@@ -551,7 +551,7 @@ val moneyArb: Arb<Money> = Arb.bind(
 }
 ```
 
-## Data-Driven Testing
+### Data-Driven Testing
 
 ### withData in Kotest
 
@@ -583,7 +583,7 @@ class ParserTest : FunSpec({
 })
 ```
 
-## Test Lifecycle and Fixtures
+### Test Lifecycle and Fixtures
 
 ### BeforeTest / AfterTest
 
@@ -654,7 +654,7 @@ class UserRepositoryTest : FunSpec({
 })
 ```
 
-## Kover Coverage
+### Kover Coverage
 
 ### Gradle Configuration
 
@@ -711,7 +711,7 @@ kover {
 | General code | 80%+ |
 | Generated / config code | Exclude |
 
-## Ktor testApplication Testing
+### Ktor testApplication Testing
 
 ```kotlin
 class ApiRoutesTest : FunSpec({
@@ -748,7 +748,7 @@ class ApiRoutesTest : FunSpec({
 })
 ```
 
-## Testing Commands
+### Testing Commands
 
 ```bash
 # Run all tests
@@ -776,7 +776,7 @@ class ApiRoutesTest : FunSpec({
 ./gradlew test --continuous
 ```
 
-## Best Practices
+### Best Practices
 
 **DO:**
 - Write tests FIRST (TDD)
@@ -795,7 +795,7 @@ class ApiRoutesTest : FunSpec({
 - Test private functions directly
 - Ignore flaky tests
 
-## Integration with CI/CD
+### Integration with CI/CD
 
 ```yaml
 # GitHub Actions example