android-sdd 1.0.0

package/skills/Performance/Allocation Optimization/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: allocation-optimization
+description: >
+  Reducing object allocations and GC pressure in Android.
+  Load this skill when optimizing hot code paths, reducing garbage
+  collection pauses, minimizing allocations in draw/layout loops,
+  or improving frame rate by reducing allocation churn.
+---
+
+# Allocation Optimization
+
+## Overview
+Excessive object allocation causes frequent garbage collection pauses, which manifest as frame drops and janky animations. On Android, the ART GC is generational and mostly concurrent, but large or frequent allocations in hot code paths (draw loops, scroll, animation) still cause measurable pauses.
+
+---
+
+## Core Principles
+
+- **Never allocate** in `onDraw`, `Canvas` operations, or tight animation loops
+- Reuse objects with object pools or `remember {}` in Compose
+- Prefer **primitives** over boxed types (`Int` not `Integer`, `IntArray` not `List<Int>`)
+- Use `StringBuilder` for string concatenation in loops — not `+` operator
+- Profile with **Android Studio Profiler → Memory → Allocation** before optimizing
+
+---
+
+## Common Allocation Hotspots
+
+```kotlin
+// ❌ Allocating in draw loop — every frame creates new objects
+class CustomView(context: Context) : View(context) {
+    override fun onDraw(canvas: Canvas) {
+        val paint = Paint()           // allocation every frame ❌
+        val rect = RectF(0f, 0f, width.toFloat(), height.toFloat())  // allocation every frame ❌
+        canvas.drawRect(rect, paint)
+    }
+}
+
+// ✅ Pre-allocate outside draw loop
+class CustomView(context: Context) : View(context) {
+    private val paint = Paint().apply { color = Color.RED }
+    private val rect = RectF()
+
+    override fun onDraw(canvas: Canvas) {
+        rect.set(0f, 0f, width.toFloat(), height.toFloat())  // reuse — no allocation
+        canvas.drawRect(rect, paint)
+    }
+}
+```
+
+---
+
+## String Concatenation in Loops
+
+```kotlin
+// ❌ String concatenation creates new String each iteration
+var result = ""
+items.forEach { result += it.name + ", " }  // O(n²) allocations
+
+// ✅ StringBuilder — single allocation
+val sb = StringBuilder()
+items.forEach { sb.append(it.name).append(", ") }
+val result = sb.toString()
+
+// ✅ Or use joinToString — optimized internally
+val result = items.joinToString(", ") { it.name }
+```
+
+---
+
+## Avoiding Boxing
+
+```kotlin
+// ❌ Boxing primitives in hot path
+val counts: Map<String, Int> = mutableMapOf()  // Int boxed to Integer
+
+// ✅ Use SparseArray for Int keys — avoids boxing
+val counts = SparseIntArray()
+
+// ✅ Use primitive arrays
+val buffer = IntArray(1024)  // no boxing
+val floatBuffer = FloatArray(256)
+
+// ❌ forEach on ranges — can box index
+for (i in 0..100) { ... }  // optimized by compiler, actually fine
+
+// ❌ Lambda capturing primitives
+listOf(1, 2, 3).map { it * 2 }  // boxes Int in some cases
+```
+
+---
+
+## Compose Allocation Optimization
+
+```kotlin
+// ❌ Creating lambda on every recomposition
+@Composable
+fun UserList(users: List<User>, onUserClick: (User) -> Unit) {
+    users.forEach { user ->
+        UserItem(
+            user = user,
+            onClick = { onUserClick(user) }  // ❌ new lambda every recomposition
+        )
+    }
+}
+
+// ✅ Use remember or stable callbacks
+@Composable
+fun UserList(users: List<User>, onUserClick: (User) -> Unit) {
+    users.forEach { user ->
+        val onClick = remember(user.id) { { onUserClick(user) } }
+        UserItem(user = user, onClick = onClick)
+    }
+}
+
+// ❌ Creating objects in composable body
+@Composable
+fun Chart(data: List<Float>) {
+    val path = Path()  // ❌ recreated every recomposition
+}
+
+// ✅ remember to reuse
+@Composable
+fun Chart(data: List<Float>) {
+    val path = remember { Path() }  // ✅ created once
+}
+```
+
+---
+
+## Reusable Buffers
+
+```kotlin
+// ✅ Thread-local buffer for repeated operations
+private val threadLocalBuffer = ThreadLocal.withInitial { ByteArray(8192) }
+
+fun processData(input: InputStream) {
+    val buffer = threadLocalBuffer.get()!!
+    var read: Int
+    while (input.read(buffer).also { read = it } != -1) {
+        process(buffer, read)
+    }
+}
+```
+
+---
+
+## Measuring Allocations
+
+```
+Android Studio Profiler → Memory tab:
+  1. Start recording allocations
+  2. Perform the action to profile (scroll, animation)
+  3. Stop recording
+  4. Sort by "Alloc Count" — find hotspots
+
+Key signals:
+  - Many small allocations in RecyclerView/LazyColumn scroll → reuse objects
+  - Repeated allocation of same type → use pool or remember
+  - Allocation inside animation frame → move outside animation
+```
+
+---
+
+## Anti-Patterns
+
+- Allocating `Paint`, `Path`, `RectF` inside `onDraw` — every frame creates garbage
+- String `+` concatenation in loops — use `StringBuilder`
+- Creating collections inside tight loops — pre-allocate or reuse
+- `List<Int>` when `IntArray` would work — unnecessary boxing
+- Allocating large arrays on the main thread — use background thread
+
+---
+
+## Related Skills
+- `heap-management` — managing heap size and cache limits
+- `compose-optimization` — Compose-specific allocation patterns
+- `rendering-performance` — frame rendering and draw optimization
+- `benchmark` — measuring allocation count with benchmarks

package/skills/Performance/App Startup/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: app-startup
+description: >
+  Jetpack App Startup library for initializer management in Android.
+  Load this skill when controlling SDK initialization order, lazy-loading
+  initializers, replacing ContentProvider-based auto-init, or reducing
+  the number of ContentProviders at startup.
+---
+
+# App Startup
+
+## Overview
+The Jetpack App Startup library provides a standard way to initialize components at app startup. It consolidates multiple `ContentProvider` initializers (used by many SDKs) into a single one, reducing startup overhead. It also supports lazy initialization and explicit dependency ordering between initializers.
+
+---
+
+## Core Principles
+
+- Use App Startup to **consolidate** multiple SDK ContentProviders into one
+- Define **dependencies** between initializers to control order
+- Use **lazy initialization** for SDKs not needed immediately
+- Disable auto-init for SDKs that have their own ContentProvider when using App Startup
+- Keep each `Initializer.create()` fast — it runs on the main thread during startup
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[libraries]
+androidx-startup = { module = "androidx.startup:startup-runtime", version = "1.1.1" }
+```
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation(libs.androidx.startup)
+}
+```
+
+---
+
+## Creating Initializers
+
+```kotlin
+// ✅ Timber initializer
+class TimberInitializer : Initializer<Unit> {
+    override fun create(context: Context) {
+        if (BuildConfig.DEBUG) {
+            Timber.plant(Timber.DebugTree())
+        }
+    }
+
+    override fun dependencies(): List<Class<out Initializer<*>>> = emptyList()
+}
+
+// ✅ Analytics initializer — depends on Timber being initialized first
+class AnalyticsInitializer : Initializer<AnalyticsClient> {
+    override fun create(context: Context): AnalyticsClient {
+        return AnalyticsClient.initialize(context).also {
+            Timber.d("Analytics initialized")
+        }
+    }
+
+    override fun dependencies(): List<Class<out Initializer<*>>> =
+        listOf(TimberInitializer::class.java)  // ✅ Timber initializes first
+}
+
+// ✅ WorkManager initializer
+class WorkManagerInitializer : Initializer<WorkManager> {
+    override fun create(context: Context): WorkManager {
+        val config = Configuration.Builder()
+            .setMinimumLoggingLevel(Log.INFO)
+            .build()
+        WorkManager.initialize(context, config)
+        return WorkManager.getInstance(context)
+    }
+
+    override fun dependencies(): List<Class<out Initializer<*>>> = emptyList()
+}
+```
+
+---
+
+## Manifest Registration
+
+```xml
+<!-- AndroidManifest.xml -->
+<provider
+    android:name="androidx.startup.InitializationProvider"
+    android:authorities="${applicationId}.androidx-startup"
+    android:exported="false">
+
+    <!-- Register initializers -->
+    <meta-data
+        android:name="com.example.TimberInitializer"
+        android:value="androidx.startup" />
+
+    <meta-data
+        android:name="com.example.AnalyticsInitializer"
+        android:value="androidx.startup" />
+
+    <meta-data
+        android:name="com.example.WorkManagerInitializer"
+        android:value="androidx.startup" />
+</provider>
+```
+
+---
+
+## Lazy Initialization
+
+```kotlin
+// ✅ Initialize on demand — not at startup
+class HeavySdkInitializer : Initializer<HeavySdk> {
+    override fun create(context: Context): HeavySdk {
+        return HeavySdk.initialize(context)
+    }
+    override fun dependencies(): List<Class<out Initializer<*>>> = emptyList()
+}
+
+// ✅ Disable auto-init in manifest — initialize manually when needed
+// In manifest:
+// <meta-data android:name="com.example.HeavySdkInitializer" android:value="androidx.startup" />
+// Remove this entry to disable auto-init
+
+// Initialize manually when first needed
+AppInitializer.getInstance(context)
+    .initializeComponent(HeavySdkInitializer::class.java)
+```
+
+---
+
+## Disabling Third-Party SDK Auto-Init
+
+```xml
+<!-- ✅ Disable WorkManager's own ContentProvider to avoid duplicate init -->
+<provider
+    android:name="androidx.work.impl.WorkManagerInitializer"
+    android:authorities="${applicationId}.workmanager-init"
+    android:exported="false"
+    tools:node="remove" />
+
+<!-- ✅ Disable Firebase auto-init if using App Startup instead -->
+<provider
+    android:name="com.google.firebase.provider.FirebaseInitProvider"
+    android:authorities="${applicationId}.firebaseinitprovider"
+    tools:node="remove" />
+```
+
+---
+
+## Measuring Startup Impact
+
+```kotlin
+// ✅ Use systrace to see initializer timing
+// In Initializer.create():
+Trace.beginSection("TimberInitializer")
+try {
+    Timber.plant(Timber.DebugTree())
+} finally {
+    Trace.endSection()
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Doing network calls inside `Initializer.create()` — runs on main thread
+- Not declaring dependencies between initializers — ordering not guaranteed
+- Registering all SDKs eagerly when most can be lazy — slows startup
+- Initializing inside `Application.onCreate()` AND via App Startup — double initialization
+- Ignoring `tools:node="remove"` for SDKs with their own ContentProviders — duplicate init
+
+---
+
+## Related Skills
+- `startup-optimization` — broader startup performance strategy
+- `baseline-profile` — pre-compiling initialization code paths
+- `workmanager` — WorkManager initialization via App Startup
+- `lifecycle` — deferring init beyond startup using lifecycle observers

package/skills/Performance/Baseline Profile/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: baseline-profile
+description: >
+  Baseline Profiles for ahead-of-time compilation in Android.
+  Load this skill when generating baseline profiles, reducing app
+  startup time, improving scroll jank on first run, or integrating
+  profile generation into the CI pipeline.
+---
+
+# Baseline Profile
+
+## Overview
+Baseline Profiles tell the Android Runtime (ART) which code paths to compile ahead-of-time (AOT) during app install. Without a profile, ART uses JIT compilation, which is slower on first run. With a baseline profile, critical code paths (startup, scroll, navigation) are pre-compiled, resulting in faster startup and smoother initial interactions.
+
+---
+
+## Core Principles
+
+- Generate profiles for **critical user journeys** — startup, main screen scroll, key flows
+- Profile generation requires a **physical device or emulator with API 28+**
+- Profiles must be **regenerated** after major code changes
+- Combine with **Macrobenchmark** to measure the improvement
+- Ship profiles in the release build — they're included in the APK/AAB automatically
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+macrobenchmark = "1.3.0"
+profileinstaller = "1.3.1"
+
+[libraries]
+androidx-profileinstaller = { module = "androidx.profileinstaller:profileinstaller", version.ref = "profileinstaller" }
+androidx-benchmark-macro = { module = "androidx.benchmark:benchmark-macro-junit4", version.ref = "macrobenchmark" }
+```
+
+```kotlin
+// app/build.gradle.kts
+dependencies {
+    implementation(libs.androidx.profileinstaller)
+}
+
+// macrobenchmark/build.gradle.kts (separate module)
+plugins {
+    alias(libs.plugins.android.test)
+}
+android {
+    targetProjectPath = ":app"
+    experimentalProperties["android.experimental.self-instrumenting"] = true
+}
+dependencies {
+    implementation(libs.androidx.benchmark.macro)
+}
+```
+
+---
+
+## Profile Generator
+
+```kotlin
+// macrobenchmark module
+@RunWith(AndroidJUnit4::class)
+class BaselineProfileGenerator {
+
+    @get:Rule
+    val rule = BaselineProfileRule()
+
+    @Test
+    fun generate() = rule.collect(
+        packageName = "com.example.app",
+        profileBlock = {
+            // ✅ Cover critical user journeys
+
+            // 1. App startup
+            startActivityAndWait()
+
+            // 2. Navigate to main screen
+            device.findObject(By.text("Home")).click()
+            device.waitForIdle()
+
+            // 3. Scroll through a list
+            val list = device.findObject(By.scrollable(true))
+            list.fling(Direction.DOWN)
+            list.fling(Direction.UP)
+            device.waitForIdle()
+
+            // 4. Open a detail screen
+            device.findObject(By.text("First Item")).click()
+            device.waitForIdle()
+        }
+    )
+}
+```
+
+---
+
+## Generate and Install Profile
+
+```bash
+# Generate the profile
+./gradlew :macrobenchmark:connectedAndroidTest \
+  -Pandroid.testInstrumentationRunnerArguments.androidx.benchmark.enabledRules=BaselineProfile
+
+# Profile is saved to:
+# app/src/main/baseline-prof.txt (automatically)
+# or manually copy from device:
+# adb pull /sdcard/Android/media/com.example.app/baseline-prof.txt app/src/main/
+
+# Verify profile is included in release build
+./gradlew :app:assembleRelease
+# Check APK contains assets/dexopt/baseline.prof
+```
+
+---
+
+## Manual Profile (Simple)
+
+```
+# app/src/main/baseline-prof.txt
+# List critical class and method patterns
+
+# Startup classes
+Lcom/example/app/MainActivity;
+Lcom/example/app/di/AppModule;
+
+# Compose runtime
+Landroidx/compose/runtime/Composer;->**
+Landroidx/compose/ui/platform/AndroidComposeView;->**
+
+# Key repository
+Lcom/example/app/data/UserRepository;->getUser(Ljava/lang/String;)**
+```
+
+---
+
+## Measuring Impact
+
+```kotlin
+// ✅ Measure startup with and without baseline profile
+@RunWith(AndroidJUnit4::class)
+class StartupBenchmark {
+    @get:Rule
+    val benchmarkRule = MacrobenchmarkRule()
+
+    @Test
+    fun startupWithBaselineProfile() = benchmarkRule.measureRepeated(
+        packageName = "com.example.app",
+        metrics = listOf(StartupTimingMetric()),
+        compilationMode = CompilationMode.Partial(
+            baselineProfileMode = BaselineProfileMode.Require  // ✅ must use profile
+        ),
+        startupMode = StartupMode.COLD,
+        iterations = 5
+    ) {
+        pressHome()
+        startActivityAndWait()
+    }
+
+    @Test
+    fun startupWithoutProfile() = benchmarkRule.measureRepeated(
+        packageName = "com.example.app",
+        metrics = listOf(StartupTimingMetric()),
+        compilationMode = CompilationMode.None,  // no AOT — baseline comparison
+        startupMode = StartupMode.COLD,
+        iterations = 5
+    ) {
+        pressHome()
+        startActivityAndWait()
+    }
+}
+```
+
+---
+
+## CI Integration
+
+```yaml
+# .github/workflows/baseline-profile.yml
+- name: Generate Baseline Profile
+  run: |
+    ./gradlew :macrobenchmark:connectedAndroidTest \
+      -Pandroid.testInstrumentationRunnerArguments.androidx.benchmark.enabledRules=BaselineProfile
+  # Commit updated baseline-prof.txt to repo
+```
+
+---
+
+## Anti-Patterns
+
+- Not regenerating profiles after significant code changes — stale profile misses new code paths
+- Generating on emulator only — physical device gives more representative profiles
+- Not measuring improvement — can't justify the maintenance cost without data
+- Including only startup in profile generation — also cover scroll and navigation
+- Shipping without `profileinstaller` dependency — profile won't be installed at app install time
+
+---
+
+## Related Skills
+- `macrobenchmark` — measuring startup and runtime with Macrobenchmark
+- `startup-optimization` — complementary startup improvements
+- `benchmark` — microbenchmark for method-level measurement
+- `app-startup` — App Startup library for initialization ordering