android-sdd 1.0.0

package/skills/Networking/WebSocket/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: websocket
+description: >
+  WebSocket communication in Android using OkHttp or Ktor.
+  Load this skill when implementing real-time bidirectional communication,
+  managing WebSocket connection lifecycle, handling reconnection,
+  or processing incoming message streams as Flow.
+---
+
+# WebSocket
+
+## Overview
+WebSockets provide full-duplex communication over a persistent TCP connection. On Android, OkHttp's `WebSocket` API is the standard for Retrofit-based projects, while Ktor provides native WebSocket support for KMP. Incoming messages are best modeled as a `Flow` to integrate naturally with the reactive architecture.
+
+---
+
+## Core Principles
+
+- Model the WebSocket connection state explicitly — never assume it's always open
+- Expose incoming messages as `Flow` — not callbacks
+- Handle reconnection with exponential backoff — connections drop unexpectedly
+- Close the WebSocket when the lifecycle owner is destroyed
+- Never send messages when the connection is not in `OPEN` state
+
+---
+
+## Connection State Model
+
+```kotlin
+sealed interface WebSocketState {
+    data object Connecting : WebSocketState
+    data object Connected : WebSocketState
+    data class Message(val data: String) : WebSocketState
+    data class Error(val throwable: Throwable) : WebSocketState
+    data object Disconnected : WebSocketState
+}
+```
+
+---
+
+## OkHttp WebSocket
+
+```kotlin
+// ✅ WebSocket manager wrapping OkHttp
+class WebSocketManager @Inject constructor(
+    private val okHttpClient: OkHttpClient,
+    private val json: Json
+) {
+    private var webSocket: WebSocket? = null
+
+    private val _state = MutableSharedFlow<WebSocketState>(
+        extraBufferCapacity = 64,
+        onBufferOverflow = BufferOverflow.DROP_OLDEST
+    )
+    val state: SharedFlow<WebSocketState> = _state.asSharedFlow()
+
+    fun connect(url: String) {
+        val request = Request.Builder().url(url).build()
+        webSocket = okHttpClient.newWebSocket(request, object : WebSocketListener() {
+
+            override fun onOpen(webSocket: WebSocket, response: Response) {
+                _state.tryEmit(WebSocketState.Connected)
+            }
+
+            override fun onMessage(webSocket: WebSocket, text: String) {
+                _state.tryEmit(WebSocketState.Message(text))
+            }
+
+            override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
+                _state.tryEmit(WebSocketState.Error(t))
+            }
+
+            override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
+                _state.tryEmit(WebSocketState.Disconnected)
+            }
+        })
+        _state.tryEmit(WebSocketState.Connecting)
+    }
+
+    fun send(message: String): Boolean {
+        return webSocket?.send(message) ?: false
+    }
+
+    fun disconnect() {
+        webSocket?.close(1000, "Client disconnect")
+        webSocket = null
+    }
+}
+```
+
+---
+
+## Ktor WebSocket (KMP)
+
+```kotlin
+// ✅ Ktor WebSocket session as Flow
+class KtorWebSocketManager @Inject constructor(
+    private val client: HttpClient
+) {
+    fun connect(url: String): Flow<WebSocketState> = callbackFlow {
+        try {
+            client.webSocket(url) {
+                trySend(WebSocketState.Connected)
+                for (frame in incoming) {
+                    when (frame) {
+                        is Frame.Text -> trySend(WebSocketState.Message(frame.readText()))
+                        is Frame.Close -> trySend(WebSocketState.Disconnected)
+                        else -> Unit
+                    }
+                }
+            }
+        } catch (e: Exception) {
+            trySend(WebSocketState.Error(e))
+        } finally {
+            trySend(WebSocketState.Disconnected)
+            close()
+        }
+        awaitClose()
+    }
+}
+```
+
+---
+
+## Reconnection with Backoff
+
+```kotlin
+// ✅ Auto-reconnect with exponential backoff
+class ReconnectingWebSocket @Inject constructor(
+    private val manager: WebSocketManager
+) {
+    private var reconnectJob: Job? = null
+
+    fun connect(url: String, scope: CoroutineScope) {
+        scope.launch {
+            manager.state.collect { state ->
+                when (state) {
+                    is WebSocketState.Error,
+                    is WebSocketState.Disconnected -> scheduleReconnect(url, scope)
+                    else -> Unit
+                }
+            }
+        }
+        manager.connect(url)
+    }
+
+    private fun scheduleReconnect(url: String, scope: CoroutineScope) {
+        reconnectJob?.cancel()
+        reconnectJob = scope.launch {
+            var attempt = 0
+            while (true) {
+                val delay = minOf(1000L * (2.0.pow(attempt)).toLong(), 30_000L)
+                delay(delay)
+                manager.connect(url)
+                attempt++
+            }
+        }
+    }
+}
+```
+
+---
+
+## Typed Message Handling
+
+```kotlin
+// ✅ Parse incoming messages to typed events
+@Serializable
+sealed interface SocketEvent {
+    @Serializable @SerialName("user_updated")
+    data class UserUpdated(val user: UserDto) : SocketEvent
+
+    @Serializable @SerialName("notification")
+    data class Notification(val message: String) : SocketEvent
+}
+
+// ✅ Map raw messages to typed events in ViewModel or repository
+val events: Flow<SocketEvent> = webSocketManager.state
+    .filterIsInstance<WebSocketState.Message>()
+    .mapNotNull { runCatching { json.decodeFromString<SocketEvent>(it.data) }.getOrNull() }
+```
+
+---
+
+## Lifecycle Integration
+
+```kotlin
+// ✅ Connect/disconnect tied to ViewModel lifecycle
+class ChatViewModel @Inject constructor(
+    private val webSocket: WebSocketManager
+) : ViewModel() {
+
+    init {
+        webSocket.connect(BuildConfig.WS_URL)
+        viewModelScope.launch {
+            webSocket.state.collect { handleState(it) }
+        }
+    }
+
+    override fun onCleared() {
+        webSocket.disconnect()
+        super.onCleared()
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Exposing raw `WebSocketListener` callbacks to the ViewModel — wrap in `Flow`
+- Not handling reconnection — mobile networks drop frequently
+- Sending messages without checking connection state — silent failures
+- Keeping WebSocket open after the user leaves the feature — wastes battery and connection
+- Using WebSocket for request/response patterns — use HTTP instead
+
+---
+
+## Related Skills
+- `okhttp` — OkHttp client that powers the WebSocket
+- `ktor` — Ktor WebSocket for KMP projects
+- `flow` — modeling streams of messages
+- `server-sent-events` — one-way alternative to WebSocket
+- `retry-backoff` — backoff strategy for reconnection

package/skills/Observability/Crash Reporting/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: crash-reporting
+description: >
+  Crash reporting setup and best practices for Android using Firebase Crashlytics.
+  Load this skill when configuring Crashlytics, adding custom context to crash
+  reports, handling non-fatal errors, filtering noise, or integrating crash
+  reporting with the logging pipeline.
+---
+
+# Crash Reporting
+
+## Overview
+Crash reporting captures uncaught exceptions and ANRs in production, providing stack traces, device info, and custom context. Firebase Crashlytics is the standard for Android. The goal is to have high signal-to-noise ratio — every reported issue should be actionable.
+
+---
+
+## Core Principles
+
+- Report **non-fatal errors** explicitly — don't wait for crashes to find bugs
+- Add **custom context** before crashes happen — user state, feature flags, last actions
+- Set **user ID** on login/logout — essential for understanding crash impact
+- Filter out **known non-actionable** crashes — third-party SDK crashes, OOM on old devices
+- Test crash reporting in debug with a deliberate crash — don't assume it works
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[plugins]
+google-services = { id = "com.google.gms.google-services", version = "4.4.2" }
+firebase-crashlytics = { id = "com.google.firebase.crashlytics", version = "3.0.2" }
+
+[libraries]
+firebase-crashlytics = { module = "com.google.firebase:firebase-crashlytics-ktx" }
+firebase-bom = { module = "com.google.firebase:firebase-bom", version = "33.1.0" }
+```
+
+```kotlin
+// app/build.gradle.kts
+plugins {
+    alias(libs.plugins.google.services)
+    alias(libs.plugins.firebase.crashlytics)
+}
+
+dependencies {
+    implementation(platform(libs.firebase.bom))
+    implementation(libs.firebase.crashlytics)
+}
+```
+
+---
+
+## Initialization
+
+```kotlin
+// ✅ Configure in Application.onCreate()
+class App : Application() {
+    override fun onCreate() {
+        super.onCreate()
+
+        FirebaseCrashlytics.getInstance().apply {
+            // Disable in debug to avoid noise in the dashboard
+            setCrashlyticsCollectionEnabled(!BuildConfig.DEBUG)
+        }
+    }
+}
+```
+
+---
+
+## Setting User Context
+
+```kotlin
+// ✅ Set user ID and properties on login
+class AuthManager @Inject constructor(
+    private val crashlytics: FirebaseCrashlytics
+) {
+    fun onUserLoggedIn(user: User) {
+        crashlytics.setUserId(user.id)
+        crashlytics.setCustomKey("user_plan", user.plan)
+        crashlytics.setCustomKey("user_region", user.region)
+    }
+
+    fun onUserLoggedOut() {
+        crashlytics.setUserId("")
+        crashlytics.setCustomKey("user_plan", "none")
+    }
+}
+```
+
+---
+
+## Custom Keys for Context
+
+```kotlin
+// ✅ Set keys before operations that might crash
+class SyncManager @Inject constructor(
+    private val crashlytics: FirebaseCrashlytics
+) {
+    suspend fun sync(userId: String) {
+        // Set context before the risky operation
+        crashlytics.setCustomKey("sync_user_id", userId)
+        crashlytics.setCustomKey("sync_started_at", System.currentTimeMillis())
+        crashlytics.setCustomKey("sync_attempt", syncAttemptCount)
+
+        try {
+            performSync(userId)
+            crashlytics.setCustomKey("sync_status", "success")
+        } catch (e: Exception) {
+            crashlytics.setCustomKey("sync_status", "failed")
+            throw e
+        }
+    }
+}
+```
+
+---
+
+## Non-Fatal Error Reporting
+
+```kotlin
+// ✅ Record non-fatal errors for bugs that don't crash but are wrong
+class UserRepository @Inject constructor(
+    private val crashlytics: FirebaseCrashlytics
+) {
+    suspend fun getUser(id: String): Result<User> {
+        return runCatching { api.getUser(id) }
+            .onFailure { error ->
+                when (error) {
+                    is HttpException -> {
+                        if (error.code() == 500) {
+                            // Server error — report as non-fatal
+                            crashlytics.recordException(error)
+                        }
+                        // 4xx — expected, don't report
+                    }
+                    is IOException -> {
+                        // Network error — expected, don't report
+                    }
+                    else -> {
+                        // Unexpected error — always report
+                        crashlytics.recordException(error)
+                    }
+                }
+            }
+            .map { mapper.toDomain(it) }
+    }
+}
+```
+
+---
+
+## Breadcrumbs via Log
+
+```kotlin
+// ✅ Add breadcrumbs — recent actions shown in crash report
+class NavigationLogger @Inject constructor(
+    private val crashlytics: FirebaseCrashlytics
+) {
+    fun onNavigate(route: String) {
+        // Crashlytics.log() messages appear as breadcrumbs in crash reports
+        crashlytics.log("Navigate to: $route")
+    }
+}
+
+// ✅ Log important user actions as breadcrumbs
+crashlytics.log("User tapped delete on item: id=$itemId")
+crashlytics.log("Sync started: attempt=$attempt")
+crashlytics.log("Payment flow entered")
+```
+
+---
+
+## Timber Integration
+
+```kotlin
+// ✅ CrashlyticsTree — route Timber errors to Crashlytics
+class CrashlyticsTree : Timber.Tree() {
+    private val crashlytics = FirebaseCrashlytics.getInstance()
+
+    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
+        crashlytics.log("${priorityLabel(priority)}/$tag: $message")
+
+        if (priority == Log.ERROR) {
+            t?.let { crashlytics.recordException(it) }
+                ?: crashlytics.recordException(Exception("Error logged without exception: $message"))
+        }
+    }
+
+    private fun priorityLabel(priority: Int) = when (priority) {
+        Log.VERBOSE -> "V"
+        Log.DEBUG   -> "D"
+        Log.INFO    -> "I"
+        Log.WARN    -> "W"
+        Log.ERROR   -> "E"
+        else        -> "?"
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Enabling Crashlytics in debug builds — floods dashboard with non-production crashes
+- Not setting user context — can't measure crash impact by user count
+- Reporting all `IOException` as non-fatal — network errors are expected, creates noise
+- Not using `setCustomKey` before risky operations — crash report lacks context
+- Catching all exceptions silently without reporting — bugs hidden in production
+
+---
+
+## Related Skills
+- `logging` — Timber setup that feeds into Crashlytics
+- `structured-logging` — adding structured context to crash reports
+- `metrics` — tracking error rates alongside crashes
+- `firebase` — Firebase setup and configuration

package/skills/Observability/Logging/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: logging
+description: >
+  Logging strategy and implementation for Android apps.
+  Load this skill when setting up Timber, defining log levels,
+  controlling log output per build type, tagging logs consistently,
+  or deciding what should and should not be logged.
+---
+
+# Logging
+
+## Overview
+Logging is the first line of observability in Android. Timber is the standard logging library — it wraps Android's `Log` class, adds automatic tag detection, and supports pluggable trees for different build types. In debug builds, logs go to Logcat. In release builds, logs go to Crashlytics or a remote logging service.
+
+---
+
+## Core Principles
+
+- Use **Timber** — never `Log.d()` directly in application code
+- Never log **sensitive data** — tokens, passwords, PII, payment info
+- Log at the **right level** — don't use `d` for errors or `e` for debug info
+- Debug logs are **free in debug builds** — don't hold back useful context
+- Release builds should send errors and warnings to a remote service, not Logcat
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[libraries]
+timber = { module = "com.jakewharton.timber:timber", version = "5.0.1" }
+```
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation(libs.timber)
+}
+```
+
+---
+
+## Initializing Timber
+
+```kotlin
+// ✅ Plant trees in Application.onCreate()
+class App : Application() {
+    override fun onCreate() {
+        super.onCreate()
+
+        if (BuildConfig.DEBUG) {
+            Timber.plant(Timber.DebugTree())  // Logcat in debug
+        } else {
+            Timber.plant(CrashlyticsTree())   // Remote in release
+        }
+    }
+}
+
+// ✅ Release tree — sends warnings and errors to Crashlytics
+class CrashlyticsTree : Timber.Tree() {
+    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
+        if (priority < Log.WARN) return  // skip DEBUG and INFO in release
+
+        when (priority) {
+            Log.WARN  -> FirebaseCrashlytics.getInstance().log("W/$tag: $message")
+            Log.ERROR -> {
+                FirebaseCrashlytics.getInstance().log("E/$tag: $message")
+                t?.let { FirebaseCrashlytics.getInstance().recordException(it) }
+            }
+        }
+    }
+}
+```
+
+---
+
+## Log Levels
+
+```kotlin
+// ✅ VERBOSE — highly detailed, development only
+Timber.v("Received ${users.size} users from cache")
+
+// ✅ DEBUG — useful development info
+Timber.d("Loading user profile for id=$userId")
+
+// ✅ INFO — significant lifecycle events
+Timber.i("User logged in: userId=$userId")
+
+// ✅ WARN — unexpected but recoverable situation
+Timber.w("Cache miss for key=$key, falling back to network")
+
+// ✅ ERROR — something failed, needs attention
+Timber.e(exception, "Failed to sync user data")
+
+// ✅ WTF — should never happen, treat as fatal
+Timber.wtf("Received null userId in authenticated state")
+```
+
+---
+
+## Tagging
+
+```kotlin
+// ✅ Timber auto-detects class name as tag — no manual tagging needed
+class UserRepository {
+    fun loadUser() {
+        Timber.d("Loading user")  // tag = "UserRepository" automatically
+    }
+}
+
+// ✅ Manual tag when needed (e.g. in utility functions)
+Timber.tag("NetworkMonitor").d("Connection state: $state")
+```
+
+---
+
+## What NOT to Log
+
+```kotlin
+// ❌ Never log sensitive data
+Timber.d("Token: $accessToken")           // security risk
+Timber.d("Password entered: $password")   // security risk
+Timber.d("Card number: $cardNumber")      // PCI violation
+
+// ✅ Log safe identifiers only
+Timber.d("User authenticated: userId=${userId.take(4)}***")
+Timber.d("Token refreshed successfully")
+```
+
+---
+
+## Logging in Repositories and Use Cases
+
+```kotlin
+// ✅ Log at entry and error points
+class UserRepositoryImpl : UserRepository {
+
+    override suspend fun getUser(id: String): Result<User> {
+        Timber.d("Fetching user: id=$id")
+
+        return runCatching {
+            api.getUser(id).also {
+                Timber.d("User fetched successfully: id=$id")
+            }
+        }.onFailure { error ->
+            Timber.e(error, "Failed to fetch user: id=$id")
+        }.map { mapper.toDomain(it) }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using `Log.d()` directly — bypasses tree system, always prints in release
+- Logging sensitive data (tokens, PII, passwords) — security and privacy violation
+- Using `Timber.e()` for expected errors (empty state, 404) — use `Timber.w()` instead
+- No logging in release builds — blind to production issues
+- Over-logging — logging every line makes logs unreadable
+
+---
+
+## Related Skills
+- `structured-logging` — structured log format for log aggregation
+- `crash-reporting` — integrating logs with crash reports
+- `observability` — broader observability strategy