android-sdd 1.0.0

package/skills/Observability/Metrics/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: metrics
+description: >
+  Application metrics and telemetry for Android apps.
+  Load this skill when tracking performance metrics, measuring feature
+  adoption, monitoring error rates, capturing user behavior signals,
+  or building a custom metrics pipeline.
+---
+
+# Metrics
+
+## Overview
+Metrics provide quantitative signals about app health and user behavior — error rates, response times, feature usage, and performance. On Android, metrics are typically sent via Firebase Analytics, Firebase Performance Monitoring, or a custom backend. The goal is to detect regressions and understand usage patterns before users complain.
+
+---
+
+## Core Principles
+
+- Track **outcomes**, not implementation details — "checkout_completed" not "button_tapped"
+- Every metric must be **actionable** — if you can't act on it, don't track it
+- Separate **performance metrics** from **business metrics** — different stakeholders
+- Avoid tracking PII — user IDs are fine, email addresses are not
+- Define metrics **before** shipping a feature — don't instrument retroactively
+
+---
+
+## Firebase Performance Monitoring
+
+```toml
+# libs.versions.toml
+[libraries]
+firebase-perf = { module = "com.google.firebase:firebase-perf-ktx" }
+```
+
+```kotlin
+// ✅ Custom trace for critical operations
+class SyncRepository @Inject constructor(
+    private val firebasePerf: FirebasePerformance
+) {
+    suspend fun syncData(): Result<Unit> {
+        val trace = firebasePerf.newTrace("sync_data")
+        trace.start()
+
+        return runCatching {
+            val result = performSync()
+            trace.putMetric("items_synced", result.itemCount.toLong())
+            trace.putAttribute("sync_type", result.type)
+            result
+        }.onSuccess {
+            trace.putAttribute("status", "success")
+        }.onFailure {
+            trace.putAttribute("status", "failure")
+            trace.putAttribute("error", it::class.simpleName ?: "unknown")
+        }.also {
+            trace.stop()
+        }.map { Unit }
+    }
+}
+```
+
+---
+
+## Custom Metrics Tracker
+
+```kotlin
+// ✅ Typed metrics tracker wrapping Firebase Analytics
+@Singleton
+class MetricsTracker @Inject constructor(
+    private val analytics: FirebaseAnalytics,
+    private val firebasePerf: FirebasePerformance
+) {
+    // ✅ Business event tracking
+    fun trackEvent(event: MetricEvent) {
+        val bundle = Bundle().apply {
+            event.properties.forEach { (key, value) ->
+                when (value) {
+                    is String -> putString(key, value)
+                    is Long   -> putLong(key, value)
+                    is Double -> putDouble(key, value)
+                    is Int    -> putInt(key, value)
+                    is Boolean -> putBoolean(key, value)
+                }
+            }
+        }
+        analytics.logEvent(event.name, bundle)
+    }
+
+    // ✅ Performance timing
+    fun <T> measureTrace(name: String, block: () -> T): T {
+        val trace = firebasePerf.newTrace(name)
+        trace.start()
+        return try {
+            block()
+        } finally {
+            trace.stop()
+        }
+    }
+
+    // ✅ Async performance timing
+    suspend fun <T> measureTraceAsync(name: String, block: suspend () -> T): T {
+        val trace = firebasePerf.newTrace(name)
+        trace.start()
+        return try {
+            block()
+        } finally {
+            trace.stop()
+        }
+    }
+}
+```
+
+---
+
+## Metric Events
+
+```kotlin
+// ✅ Typed event definitions
+sealed class MetricEvent(
+    val name: String,
+    val properties: Map<String, Any> = emptyMap()
+) {
+    class FeatureViewed(featureName: String) : MetricEvent(
+        name = "feature_viewed",
+        properties = mapOf("feature" to featureName)
+    )
+
+    class ActionCompleted(action: String, durationMs: Long) : MetricEvent(
+        name = "action_completed",
+        properties = mapOf("action" to action, "duration_ms" to durationMs)
+    )
+
+    class ErrorOccurred(errorType: String, screen: String) : MetricEvent(
+        name = "error_occurred",
+        properties = mapOf("error_type" to errorType, "screen" to screen)
+    )
+
+    class SyncCompleted(itemCount: Int, durationMs: Long, success: Boolean) : MetricEvent(
+        name = "sync_completed",
+        properties = mapOf(
+            "item_count" to itemCount,
+            "duration_ms" to durationMs,
+            "success" to success
+        )
+    )
+}
+```
+
+---
+
+## Error Rate Tracking
+
+```kotlin
+// ✅ Track error rates per feature
+class UserRepository @Inject constructor(
+    private val metrics: MetricsTracker
+) {
+    suspend fun getUser(id: String): Result<User> {
+        val startTime = System.currentTimeMillis()
+
+        return runCatching { api.getUser(id) }
+            .onSuccess {
+                metrics.trackEvent(MetricEvent.ActionCompleted(
+                    action = "fetch_user",
+                    durationMs = System.currentTimeMillis() - startTime
+                ))
+            }
+            .onFailure { error ->
+                metrics.trackEvent(MetricEvent.ErrorOccurred(
+                    errorType = error::class.simpleName ?: "unknown",
+                    screen = "user_detail"
+                ))
+            }
+            .map { mapper.toDomain(it) }
+    }
+}
+```
+
+---
+
+## Network Request Metrics
+
+```kotlin
+// ✅ Track all network request performance
+class MetricsInterceptor @Inject constructor(
+    private val metrics: MetricsTracker
+) : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val start = System.currentTimeMillis()
+        val request = chain.request()
+
+        return try {
+            val response = chain.proceed(request)
+            val duration = System.currentTimeMillis() - start
+
+            metrics.trackEvent(MetricEvent.ActionCompleted(
+                action = "network_${request.method.lowercase()}_${request.url.encodedPath}",
+                durationMs = duration
+            ))
+            response
+        } catch (e: Exception) {
+            metrics.trackEvent(MetricEvent.ErrorOccurred(
+                errorType = "network_${e::class.simpleName}",
+                screen = request.url.encodedPath
+            ))
+            throw e
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Tracking every tap and scroll — creates noise, hard to find signal
+- Tracking PII (email, name) as metric properties — privacy violation
+- Not defining metric names as constants — typos create duplicate metrics
+- Tracking metrics in debug builds — pollutes production dashboards
+- No baseline — can't detect regression without knowing the previous value
+
+---
+
+## Related Skills
+- `crash-reporting` — crash data alongside error metrics
+- `structured-logging` — log events that feed into metrics pipelines
+- `analytics` — Firebase Analytics for user behavior
+- `observability` — broader observability combining logs, metrics, and traces

package/skills/Observability/Structured Logging/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: structured-logging
+description: >
+  Structured logging for Android apps — consistent, queryable log format.
+  Load this skill when building log aggregation pipelines, adding context
+  to log events, correlating logs across requests, or making logs
+  machine-parseable for log management tools.
+---
+
+# Structured Logging
+
+## Overview
+Structured logging formats log entries as key-value pairs or JSON instead of free-form strings. This makes logs searchable, filterable, and correlatable in log management systems (Datadog, Elastic, Splunk). On Android, structured logs are typically sent to Crashlytics or a custom logging backend.
+
+---
+
+## Core Principles
+
+- Every log event has a **consistent schema** — event name + context fields
+- Include **correlation IDs** to trace a request across multiple log entries
+- Log **events**, not state — "user_login_succeeded" not "user is logged in"
+- Never include sensitive data in structured logs — same rule as plain logs
+- Use a typed log event model — not free-form strings
+
+---
+
+## Log Event Model
+
+```kotlin
+// ✅ Typed log event — consistent schema
+data class LogEvent(
+    val name: String,
+    val level: LogLevel,
+    val timestamp: Long = System.currentTimeMillis(),
+    val userId: String? = null,
+    val sessionId: String? = null,
+    val properties: Map<String, Any> = emptyMap(),
+    val error: Throwable? = null
+)
+
+enum class LogLevel { DEBUG, INFO, WARN, ERROR }
+
+// ✅ Event name constants — prevents typos
+object LogEvents {
+    const val USER_LOGIN_SUCCESS    = "user_login_success"
+    const val USER_LOGIN_FAILURE    = "user_login_failure"
+    const val SYNC_STARTED          = "sync_started"
+    const val SYNC_COMPLETED        = "sync_completed"
+    const val SYNC_FAILED           = "sync_failed"
+    const val NETWORK_REQUEST       = "network_request"
+    const val NETWORK_ERROR         = "network_error"
+}
+```
+
+---
+
+## Structured Logger
+
+```kotlin
+// ✅ Central structured logger
+@Singleton
+class StructuredLogger @Inject constructor(
+    private val sessionManager: SessionManager,
+    private val crashlytics: FirebaseCrashlytics
+) {
+    fun log(
+        name: String,
+        level: LogLevel = LogLevel.INFO,
+        properties: Map<String, Any> = emptyMap(),
+        error: Throwable? = null
+    ) {
+        val event = LogEvent(
+            name = name,
+            level = level,
+            userId = sessionManager.currentUserId,
+            sessionId = sessionManager.sessionId,
+            properties = properties,
+            error = error
+        )
+
+        // Debug: log to Logcat
+        if (BuildConfig.DEBUG) {
+            Timber.tag("StructuredLog").d(event.toLogString())
+        }
+
+        // Release: send to Crashlytics
+        crashlytics.log(event.toLogString())
+        error?.let { crashlytics.recordException(it) }
+    }
+
+    private fun LogEvent.toLogString(): String {
+        val props = properties.entries.joinToString(", ") { "${it.key}=${it.value}" }
+        return "[$level] $name | userId=$userId sessionId=$sessionId | $props"
+    }
+}
+```
+
+---
+
+## Usage in Repository and Use Cases
+
+```kotlin
+// ✅ Log structured events at key boundaries
+class AuthRepositoryImpl @Inject constructor(
+    private val api: AuthApi,
+    private val logger: StructuredLogger
+) : AuthRepository {
+
+    override suspend fun login(email: String, password: String): Result<User> {
+        return runCatching {
+            val response = api.login(email, password)
+            logger.log(
+                name = LogEvents.USER_LOGIN_SUCCESS,
+                properties = mapOf("method" to "email")
+            )
+            mapper.toDomain(response)
+        }.onFailure { error ->
+            logger.log(
+                name = LogEvents.USER_LOGIN_FAILURE,
+                level = LogLevel.ERROR,
+                properties = mapOf(
+                    "method" to "email",
+                    "error_type" to error::class.simpleName.orEmpty()
+                ),
+                error = error
+            )
+        }
+    }
+}
+```
+
+---
+
+## Network Request Logging
+
+```kotlin
+// ✅ Log all network requests with structured context
+class StructuredLoggingInterceptor @Inject constructor(
+    private val logger: StructuredLogger
+) : Interceptor {
+
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request()
+        val startTime = System.currentTimeMillis()
+
+        return try {
+            val response = chain.proceed(request)
+            val duration = System.currentTimeMillis() - startTime
+
+            logger.log(
+                name = LogEvents.NETWORK_REQUEST,
+                properties = mapOf(
+                    "method"   to request.method,
+                    "path"     to request.url.encodedPath,
+                    "status"   to response.code,
+                    "duration" to duration
+                )
+            )
+            response
+        } catch (e: IOException) {
+            logger.log(
+                name = LogEvents.NETWORK_ERROR,
+                level = LogLevel.ERROR,
+                properties = mapOf(
+                    "method" to request.method,
+                    "path"   to request.url.encodedPath
+                ),
+                error = e
+            )
+            throw e
+        }
+    }
+}
+```
+
+---
+
+## Session Correlation
+
+```kotlin
+// ✅ Generate session ID to correlate logs within a session
+@Singleton
+class SessionManager @Inject constructor() {
+    var currentUserId: String? = null
+        private set
+
+    var sessionId: String = generateSessionId()
+        private set
+
+    fun onUserLoggedIn(userId: String) {
+        currentUserId = userId
+        sessionId = generateSessionId()  // new session per login
+    }
+
+    fun onUserLoggedOut() {
+        currentUserId = null
+        sessionId = generateSessionId()
+    }
+
+    private fun generateSessionId() = UUID.randomUUID().toString().take(8)
+}
+```
+
+---
+
+## Crashlytics Key-Value Context
+
+```kotlin
+// ✅ Set Crashlytics keys for crash context
+fun setCrashlyticsContext(userId: String, plan: String) {
+    val crashlytics = FirebaseCrashlytics.getInstance()
+    crashlytics.setUserId(userId)
+    crashlytics.setCustomKey("user_plan", plan)
+    crashlytics.setCustomKey("app_version", BuildConfig.VERSION_NAME)
+    crashlytics.setCustomKey("session_id", sessionManager.sessionId)
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Free-form log strings — not queryable or consistent
+- Logging sensitive data (email, tokens) as properties — privacy violation
+- No event name constants — typos cause missed log entries
+- Logging too many events — drowns out important signals
+- Not including session/user context — can't correlate related events
+
+---
+
+## Related Skills
+- `logging` — basic Timber setup and log levels
+- `crash-reporting` — integrating structured logs with crash reports
+- `observability` — metrics and telemetry alongside logs

package/skills/Performance/ANR Prevention/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: anr-prevention
+description: >
+  ANR (Application Not Responding) prevention in Android.
+  Load this skill when investigating ANR reports, identifying blocking
+  main thread operations, using StrictMode to detect violations,
+  or ensuring the main thread stays responsive under load.
+---
+
+# ANR Prevention
+
+## Overview
+An ANR occurs when the main thread is blocked for more than 5 seconds (input) or 10 seconds (broadcast). Android shows a dialog asking the user to wait or close the app. ANRs are caused by I/O, network, database queries, or heavy computation running on the main thread.
+
+---
+
+## Core Principles
+
+- **Nothing blocking** on the main thread — no I/O, no network, no heavy computation
+- Use `Dispatchers.IO` for all I/O operations — database, file, network
+- Use `Dispatchers.Default` for CPU-heavy work — parsing, sorting, crypto
+- Keep `BroadcastReceiver.onReceive()` under 10 seconds — delegate to WorkManager if longer
+- Use StrictMode in development to catch violations before they reach users
+
+---
+
+## ANR Triggers
+
+```
+Input dispatch timeout:  5 seconds — user touched screen, app didn't respond
+Broadcast timeout:      10 seconds (foreground) / 60 seconds (background)
+Service timeout:        20 seconds (foreground) / 200 seconds (background)
+ContentProvider timeout: 10 seconds
+
+Common causes:
+  - SharedPreferences.edit().commit() on main thread (use apply())
+  - Room query on main thread (Room throws by default — don't disable this)
+  - Bitmap decoding on main thread
+  - Heavy JSON parsing on main thread
+  - Synchronized lock contention on main thread
+  - Binder calls to slow system services on main thread
+```
+
+---
+
+## StrictMode — Catch Violations in Development
+
+```kotlin
+// ✅ Enable StrictMode in debug builds
+class App : Application() {
+    override fun onCreate() {
+        super.onCreate()
+
+        if (BuildConfig.DEBUG) {
+            StrictMode.setThreadPolicy(
+                StrictMode.ThreadPolicy.Builder()
+                    .detectDiskReads()
+                    .detectDiskWrites()
+                    .detectNetwork()
+                    .detectCustomSlowCalls()
+                    .penaltyLog()             // log to Logcat
+                    .penaltyFlashScreen()     // visual flash in debug
+                    .build()
+            )
+
+            StrictMode.setVmPolicy(
+                StrictMode.VmPolicy.Builder()
+                    .detectLeakedSqlLiteObjects()
+                    .detectLeakedClosableObjects()
+                    .detectActivityLeaks()
+                    .penaltyLog()
+                    .build()
+            )
+        }
+    }
+}
+```
+
+---
+
+## Moving Work off Main Thread
+
+```kotlin
+// ❌ Blocking main thread
+class UserRepository {
+    fun getUser(id: String): User {
+        return database.userDao().getUser(id)  // blocks main thread
+    }
+}
+
+// ✅ Suspend function on IO dispatcher
+class UserRepository {
+    suspend fun getUser(id: String): User = withContext(Dispatchers.IO) {
+        database.userDao().getUser(id)
+    }
+}
+
+// ❌ SharedPreferences commit on main thread
+prefs.edit().putString("key", "value").commit()  // synchronous write
+
+// ✅ apply() — asynchronous write
+prefs.edit().putString("key", "value").apply()
+
+// ❌ Heavy computation on main thread
+val sorted = largeList.sortedBy { expensiveFunction(it) }  // main thread
+
+// ✅ Move to Default dispatcher
+val sorted = withContext(Dispatchers.Default) {
+    largeList.sortedBy { expensiveFunction(it) }
+}
+```
+
+---
+
+## BroadcastReceiver — Delegate Long Work
+
+```kotlin
+// ❌ Long work in onReceive — 10 second limit
+class SyncReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        performLongSync()  // may exceed 10s — ANR
+    }
+}
+
+// ✅ Delegate to WorkManager from onReceive
+class SyncReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        // onReceive must return quickly — enqueue work
+        WorkManager.getInstance(context)
+            .enqueue(OneTimeWorkRequestBuilder<SyncWorker>().build())
+    }
+}
+```
+
+---
+
+## Detecting ANRs in Production
+
+```kotlin
+// ✅ Firebase Crashlytics reports ANRs automatically
+// Check Firebase Console → Crashlytics → ANRs tab
+
+// ✅ Custom ANR watchdog for more detail
+class AnrWatchdog(private val timeoutMs: Long = 5_000) : Thread() {
+    private val mainHandler = Handler(Looper.getMainLooper())
+    @Volatile private var tick = 0
+
+    override fun run() {
+        while (!isInterrupted) {
+            val prev = tick
+            mainHandler.post { tick++ }
+            sleep(timeoutMs)
+            if (tick == prev) {
+                // Main thread hasn't processed the message — potential ANR
+                Timber.e("Potential ANR detected — main thread blocked for ${timeoutMs}ms")
+            }
+        }
+    }
+}
+```
+
+---
+
+## Reading ANR Traces
+
+```bash
+# Pull ANR trace from device
+adb pull /data/anr/traces.txt
+
+# Key things to look for in traces.txt:
+# "main" thread in state BLOCKED or WAIT
+# Holding lock: or waiting to lock:
+# Long stack traces in android.database or java.io
+```
+
+---
+
+## Anti-Patterns
+
+- `SharedPreferences.commit()` on main thread — use `apply()`
+- Room `allowMainThreadQueries()` — never enable in production
+- `Bitmap.decodeFile()` on main thread — use coroutine with `Dispatchers.IO`
+- Long `synchronized {}` blocks on main thread — can cause lock contention ANR
+- `Thread.sleep()` on main thread — blocks all UI processing
+
+---
+
+## Related Skills
+- `coroutine` — moving work off the main thread
+- `background-processing` — delegating work to background
+- `rendering-performance` — keeping main thread free during frames
+- `workmanager` — delegating BroadcastReceiver work safely