@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.1

package/pipeline/skills/shared/external/android-performance/SKILL.md

@@ -9,6 +9,10 @@ Performance optimization patterns for Android apps targeting Jetpack Compose,
 R8, Baseline Profiles, and modern profiling tools. Covers startup, runtime,
 memory, and image loading optimization.
 
+Detailed code examples live in `references/patterns.md`, organized under the
+same section headings used below. Load the matching section when you implement
+or review that area; the guidance here is enough to decide what to do.
+
 ## Contents
 
 - [Baseline Profiles](#baseline-profiles)
@@ -27,88 +31,15 @@ memory, and image loading optimization.
 ## Baseline Profiles
 
 Baseline Profiles pre-compile critical code paths at install time, improving
-startup time and reducing jank on first run.
-
-### Setup
-
-```kotlin
-// build.gradle.kts (:app)
-plugins {
-    alias(libs.plugins.android.application)
-    alias(libs.plugins.baselineprofile)
-}
-
-dependencies {
-    baselineProfile(project(":baselineprofile"))
-}
-
-baselineProfile {
-    automaticGenerationDuringBuild = true
-}
-```
-
-### Generator Module
-
-```kotlin
-// :baselineprofile/build.gradle.kts
-plugins {
-    alias(libs.plugins.android.test)
-    alias(libs.plugins.baselineprofile)
-}
-
-android {
-    namespace = "com.example.baselineprofile"
-    targetProjectPath = ":app"
-}
-
-baselineProfile {
-    useConnectedDevices = true
-}
-```
-
-### Profile Generator
-
-```kotlin
-@RunWith(AndroidJUnit4::class)
-@LargeTest
-class BaselineProfileGenerator {
-
-    @get:Rule
-    val rule = BaselineProfileRule()
-
-    @Test
-    fun generateBaselineProfile() {
-        rule.collect(
-            packageName = "com.example.app",
-            includeInStartupProfile = true,
-        ) {
-            // Cold start
-            pressHome()
-            startActivityAndWait()
-
-            // Critical user journeys
-            device.findObject(By.text("Search")).click()
-            device.waitForIdle()
-
-            device.findObject(By.res("search_field")).text = "Istanbul"
-            device.waitForIdle()
-
-            device.findObject(By.res("flight_card")).click()
-            device.waitForIdle()
-        }
-    }
-}
-```
-
-### Generate and Apply
+startup time and reducing jank on first run. Apply the `baselineprofile` plugin
+to `:app`, add a `:baselineprofile` test module that targets `:app`, and write a
+`BaselineProfileRule` generator that exercises cold start plus the critical user
+journeys. Run `./gradlew :app:generateBaselineProfile` to produce
+`baseline-prof.txt` and `startup-prof.txt` under `app/src/main/`.
 
-```bash
-# Generate baseline profile
-./gradlew :app:generateBaselineProfile
-
-# Profile is written to app/src/main/baseline-prof.txt
-# Startup profile to app/src/main/startup-prof.txt
-```
+See `references/patterns.md` -> "Baseline Profiles" for the `:app` and
+generator `build.gradle.kts`, the `BaselineProfileGenerator` test, and the
+generate command.
 
 ## Compose Stability
 
@@ -125,564 +56,117 @@ For this to work, parameters must be **stable** (immutable or observable).
 | `class` (non-data) | No | Compose cannot infer stability |
 | Lambda `() -> Unit` | Unstable by default | Captured variables may change |
 
-### @Immutable and @Stable Annotations
-
-```kotlin
-// Mark a class as truly immutable (all properties never change after construction)
-@Immutable
-data class FlightUiModel(
-    val id: String,
-    val route: String,
-    val price: String,
-    val status: String,
-)
-
-// Mark a class as stable (Compose can track changes via equals)
-@Stable
-data class FilterState(
-    val origin: String = "",
-    val destination: String = "",
-    val date: LocalDate? = null,
-)
-```
-
-### Use kotlinx.collections.immutable
+Mark truly immutable models `@Immutable` and observable-but-stable state
+`@Stable`. Replace `List`/`Set`/`Map` parameters with
+`kotlinx.collections.immutable` variants (`ImmutableList`, `persistentListOf()`)
+so list-carrying UI state stays stable. On Kotlin 2.0+ the Compose Compiler
+enables strong skipping by default (unstable params compared by `===`, lambdas
+memoized), reducing the need for manual annotations. Verify results in the
+Compose compiler reports.
 
-Replace `List`, `Set`, `Map` with immutable variants for stable parameters:
-
-```kotlin
-// build.gradle.kts
-implementation("org.jetbrains.kotlinx:kotlinx-collections-immutable:0.3.8")
-
-// Usage
-@Immutable
-data class FlightListUiState(
-    val flights: ImmutableList<FlightUiModel> = persistentListOf(),
-    val isLoading: Boolean = false,
-)
-
-// Convert in ViewModel
-val uiState: StateFlow<FlightListUiState> = repository.getFlights()
-    .map { flights ->
-        FlightListUiState(
-            flights = flights.map(::toUiModel).toImmutableList(),
-        )
-    }
-    .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), FlightListUiState())
-```
-
-### Strong Skipping Mode (Kotlin 2.0+)
-
-With the Compose Compiler plugin for Kotlin 2.0+, strong skipping is enabled
-by default. This makes more composables skippable:
-
-- Unstable parameters are compared by instance equality (`===`)
-- Lambdas are memoized by default
-- Less need for manual `@Stable` / `@Immutable` annotations
-
-Verify in Compose compiler reports:
-
-```properties
-# gradle.properties
-composeCompiler.reportsDestination=build/compose-reports
-composeCompiler.metricsDestination=build/compose-metrics
-```
-
-```bash
-./gradlew assembleRelease
-# Check build/compose-reports/app_release-composables.txt for skippability
-```
+See `references/patterns.md` -> "Compose Stability" for the annotation
+examples, the immutable-collections `StateFlow` mapping, and the
+`gradle.properties` report settings.
 
 ## Recomposition Debugging
 
-### Layout Inspector (Android Studio)
-
-1. Run app in debug mode
-2. Open Layout Inspector: View > Tool Windows > Layout Inspector
-3. Enable "Show Recomposition Counts" in the toolbar
-4. Interact with the app and observe which composables recompose
-
-High recomposition counts on composables that should not change indicate
-unnecessary invalidation.
-
-### Recomposition Highlighter
-
-```kotlin
-// Debug utility -- remove before release
-@Composable
-fun RecompositionCounter(label: String) {
-    val count = remember { mutableIntStateOf(0) }
-    count.intValue++
-    SideEffect {
-        Log.d("Recomposition", "$label: ${count.intValue}")
-    }
-}
-```
-
-### Compose Compiler Metrics
-
-Generate stability reports to identify unstable composables:
-
-```bash
-./gradlew assembleRelease \
-    -PcomposeCompiler.reportsDestination=build/compose-reports \
-    -PcomposeCompiler.metricsDestination=build/compose-metrics
-```
-
-Key files:
-- `*-composables.txt`: Lists all composables with restartable/skippable status
-- `*-classes.txt`: Lists all classes with stability status
-- `*-module.json`: Summary metrics
-
-Look for composables marked `restartable` but NOT `skippable` -- these are
+Use Android Studio's Layout Inspector with "Show Recomposition Counts" enabled
+to find composables that recompose more than they should. For targeted logging,
+a small `RecompositionCounter` debug composable prints per-label counts (remove
+before release). For a build-wide view, generate Compose compiler metrics and
+look for composables marked `restartable` but NOT `skippable` -- those are the
 recomposition hotspots.
 
-## Lazy Layout Performance
+See `references/patterns.md` -> "Recomposition Debugging" for the Layout
+Inspector steps, the `RecompositionCounter` snippet, the metrics command, and
+the report files to read.
 
-### LazyColumn/LazyRow Keys
+## Lazy Layout Performance
 
-Always provide stable keys for lazy layouts. Without keys, Compose cannot
-efficiently diff items.
+Always provide a stable `key` for `LazyColumn`/`LazyRow` items; without it
+Compose cannot diff efficiently and re-renders the whole list on any change.
 
 ```kotlin
-// CORRECT: stable key from item ID
 LazyColumn {
-    items(
-        items = flights,
-        key = { flight -> flight.id },
-    ) { flight ->
+    items(items = flights, key = { it.id }) { flight ->
         FlightCard(flight = flight)
     }
 }
-
-// WRONG: no key -- full list diff on every change
-LazyColumn {
-    items(flights) { flight ->
-        FlightCard(flight = flight)
-    }
-}
-```
-
-### contentType for Heterogeneous Lists
-
-```kotlin
-LazyColumn {
-    items(
-        items = feedItems,
-        key = { it.id },
-        contentType = { item ->
-            when (item) {
-                is FeedItem.Flight -> "flight"
-                is FeedItem.Hotel -> "hotel"
-                is FeedItem.Ad -> "ad"
-            }
-        },
-    ) { item ->
-        when (item) {
-            is FeedItem.Flight -> FlightCard(item)
-            is FeedItem.Hotel -> HotelCard(item)
-            is FeedItem.Ad -> AdBanner(item)
-        }
-    }
-}
 ```
 
-`contentType` enables Compose to reuse view holders of the same type,
-similar to RecyclerView's view type system.
-
-### Avoid Heavy Computation in Item Scope
-
-```kotlin
-// WRONG: formatting on every recomposition
-items(flights, key = { it.id }) { flight ->
-    val formatted = SimpleDateFormat("HH:mm", Locale.getDefault())
-        .format(Date(flight.departureTime))
-    Text(formatted)
-}
-
-// CORRECT: precompute in ViewModel or UiModel
-data class FlightUiModel(
-    val id: String,
-    val formattedDeparture: String, // precomputed
-)
-```
+For heterogeneous lists, add `contentType` so Compose reuses layouts of the
+same type (like RecyclerView view types). Never format or allocate inside item
+scope -- precompute display strings in the `UiModel`. Default prefetch is
+usually sufficient.
 
-### Prefetch Configuration
-
-```kotlin
-LazyColumn(
-    state = rememberLazyListState(),
-    // Default prefetch is usually sufficient
-    // For custom behavior:
-    flingBehavior = ScrollableDefaults.flingBehavior(),
-) {
-    items(flights, key = { it.id }) { flight ->
-        FlightCard(flight = flight)
-    }
-}
-```
+See `references/patterns.md` -> "Lazy Layout Performance" for the keyed vs
+unkeyed contrast, the `contentType` example, the precompute-in-UiModel pattern,
+and prefetch configuration.
 
 ## R8 Optimization
 
 R8 performs code shrinking, obfuscation, and optimization in release builds.
+Enable it with `isMinifyEnabled = true` and `isShrinkResources = true` on the
+`release` build type, using `proguard-android-optimize.txt` plus your keep
+rules. Turn on `android.enableR8.fullMode=true` for more aggressive
+optimization (may require extra keep rules for reflection-based code). Measure
+impact by comparing debug and release APK sizes.
 
-### Enable Full Optimization
-
-```kotlin
-android {
-    buildTypes {
-        release {
-            isMinifyEnabled = true
-            isShrinkResources = true
-            proguardFiles(
-                getDefaultProguardFile("proguard-android-optimize.txt"),
-                "proguard-rules.pro",
-            )
-        }
-    }
-}
-```
-
-### R8 Full Mode
-
-R8 full mode enables more aggressive optimizations:
-
-```properties
-# gradle.properties
-android.enableR8.fullMode=true
-```
-
-Full mode may require additional keep rules for reflection-based code.
-
-### Measuring R8 Impact
-
-```bash
-# Before R8 (debug APK)
-./gradlew assembleDebug
-ls -la app/build/outputs/apk/debug/app-debug.apk
-
-# After R8 (release APK)
-./gradlew assembleRelease
-ls -la app/build/outputs/apk/release/app-release.apk
-
-# Compare sizes
-```
+See `references/patterns.md` -> "R8 Optimization" for the `buildTypes` block,
+the full-mode property, and the size-comparison commands.
 
 ## Memory Leak Detection
 
-### LeakCanary Setup
-
-```kotlin
-// build.gradle.kts
-debugImplementation("com.squareup.leakcanary:leakcanary-android:2.14")
-```
-
-LeakCanary runs automatically in debug builds. It detects:
-- Activity leaks
-- Fragment leaks
-- ViewModel leaks
-- Service leaks
-- Custom watched objects
-
-### Common Leak Patterns
-
-```kotlin
-// LEAK: Activity reference in singleton
-object Analytics {
-    private var context: Context? = null // holds Activity reference
-    fun init(context: Context) { this.context = context }
-}
-
-// FIX: Use application context
-object Analytics {
-    private var context: Context? = null
-    fun init(context: Context) { this.context = context.applicationContext }
-}
-
-// LEAK: Coroutine scope outlives lifecycle
-class MyActivity : ComponentActivity() {
-    init {
-        GlobalScope.launch { // outlives Activity
-            // long-running work
-        }
-    }
-}
-
-// FIX: Use lifecycleScope
-class MyActivity : ComponentActivity() {
-    override fun onCreate(savedInstanceState: Bundle?) {
-        super.onCreate(savedInstanceState)
-        lifecycleScope.launch {
-            // cancelled when Activity is destroyed
-        }
-    }
-}
-
-// LEAK: Anonymous inner class holds reference
-class MyViewModel : ViewModel() {
-    val callback = object : Callback {
-        override fun onResult(data: Data) {
-            // this holds implicit reference to MyViewModel
-        }
-    }
-}
-```
-
-### Manual Object Watching
+Add LeakCanary as `debugImplementation` only; it runs automatically in debug
+builds and reports Activity, Fragment, ViewModel, Service, and custom watched
+leaks. The recurring leak sources are: Activity/Context references held in
+singletons (fix with `applicationContext`), `GlobalScope` coroutines that
+outlive a lifecycle (fix with `lifecycleScope`/`viewModelScope`), and anonymous
+inner classes capturing an implicit outer reference. For custom objects, watch
+them explicitly with `objectWatcher.expectWeaklyReachable(...)`.
 
-```kotlin
-// Watch custom objects for leaks
-val watcher = LeakCanary.objectWatcher
-watcher.expectWeaklyReachable(myObject, "MyObject should be GC'd")
-```
+See `references/patterns.md` -> "Memory Leak Detection" for the dependency
+line, the leak-vs-fix pairs, and the manual object-watching snippet.
 
 ## Startup Optimization
 
-### Macrobenchmark for Startup Tracing
-
-```kotlin
-@RunWith(AndroidJUnit4::class)
-class StartupBenchmark {
-
-    @get:Rule
-    val benchmarkRule = MacrobenchmarkRule()
-
-    @Test
-    fun startupCompilation() {
-        benchmarkRule.measureRepeated(
-            packageName = "com.example.app",
-            metrics = listOf(StartupTimingMetric()),
-            iterations = 5,
-            startupMode = StartupMode.COLD,
-        ) {
-            pressHome()
-            startActivityAndWait()
-        }
-    }
-
-    @Test
-    fun startupWithScrolling() {
-        benchmarkRule.measureRepeated(
-            packageName = "com.example.app",
-            metrics = listOf(
-                StartupTimingMetric(),
-                FrameTimingMetric(),
-            ),
-            iterations = 5,
-            startupMode = StartupMode.COLD,
-        ) {
-            pressHome()
-            startActivityAndWait()
-
-            val list = device.findObject(By.res("flight_list"))
-            list.setGestureMargin(device.displayWidth / 5)
-            list.fling(Direction.DOWN)
-            device.waitForIdle()
-        }
-    }
-}
-```
-
-### Startup Best Practices
-
-```kotlin
-@HiltAndroidApp
-class MyApplication : Application() {
-    override fun onCreate() {
-        super.onCreate()
-        // Only initialize essentials here
-        // Defer non-critical init to background
-    }
-}
-
-// Use App Startup library for lazy initialization
-class AnalyticsInitializer : Initializer<Analytics> {
-    override fun create(context: Context): Analytics {
-        return Analytics.init(context)
-    }
-
-    override fun dependencies(): List<Class<out Initializer<*>>> = emptyList()
-}
-```
-
-### Defer Heavy Initialization
-
-```kotlin
-// WRONG: blocking startup
-class MyApplication : Application() {
-    override fun onCreate() {
-        super.onCreate()
-        Database.initialize(this)      // slow
-        ImageLoader.setup(this)        // slow
-        CrashReporting.setup(this)     // slow
-    }
-}
+Measure cold start with a Macrobenchmark `StartupTimingMetric` (add
+`FrameTimingMetric` to catch scroll jank during startup), running against a
+release build on a real device. Keep `Application.onCreate` minimal: initialize
+only essentials, defer database, image loader, and other heavy setup to a
+background dispatcher (or the App Startup library). Crash reporting can usually
+stay on main.
 
-// CORRECT: defer to background
-class MyApplication : Application() {
-    override fun onCreate() {
-        super.onCreate()
-        ProcessLifecycleOwner.get().lifecycleScope.launch(Dispatchers.Default) {
-            Database.initialize(this@MyApplication)
-            ImageLoader.setup(this@MyApplication)
-        }
-        // Crash reporting can stay on main (usually lightweight)
-        CrashReporting.setup(this)
-    }
-}
-```
+See `references/patterns.md` -> "Startup Optimization" for the
+`StartupBenchmark` tests, the App Startup `Initializer`, and the
+blocking-vs-deferred `Application.onCreate` contrast.
 
 ## Image Loading with Coil
 
-### Basic Setup
-
-```kotlin
-// build.gradle.kts
-implementation("io.coil-kt:coil-compose:2.7.0")
-
-// Composable
-@Composable
-fun FlightImage(imageUrl: String, modifier: Modifier = Modifier) {
-    AsyncImage(
-        model = ImageRequest.Builder(LocalContext.current)
-            .data(imageUrl)
-            .crossfade(true)
-            .memoryCacheKey(imageUrl)
-            .diskCacheKey(imageUrl)
-            .build(),
-        contentDescription = "Flight image",
-        modifier = modifier,
-        contentScale = ContentScale.Crop,
-    )
-}
-```
-
-### Global Image Loader Configuration
-
-```kotlin
-@HiltAndroidApp
-class MyApplication : Application(), ImageLoaderFactory {
-
-    override fun newImageLoader(): ImageLoader =
-        ImageLoader.Builder(this)
-            .memoryCache {
-                MemoryCache.Builder(this)
-                    .maxSizePercent(0.25) // 25% of app memory
-                    .build()
-            }
-            .diskCache {
-                DiskCache.Builder()
-                    .directory(cacheDir.resolve("image_cache"))
-                    .maxSizePercent(0.02) // 2% of disk
-                    .build()
-            }
-            .crossfade(true)
-            .respectCacheHeaders(true)
-            .build()
-}
-```
-
-### Image Size Optimization
-
-```kotlin
-// Downscale to view size -- prevents loading full-resolution images
-AsyncImage(
-    model = ImageRequest.Builder(LocalContext.current)
-        .data(imageUrl)
-        .size(Size(200, 200)) // Request specific size
-        .scale(Scale.FILL)
-        .build(),
-    contentDescription = null,
-    modifier = Modifier.size(100.dp), // Display size
-)
-```
-
-### Placeholder and Error States
+Load images with Coil's `AsyncImage`, enabling `crossfade` and explicit
+cache keys. Configure a global `ImageLoader` via `ImageLoaderFactory` with
+memory and disk cache limits (e.g. 25% of app memory, 2% of disk). Always
+request images at display size with `.size(...)` to avoid decoding
+full-resolution bitmaps, and supply `placeholder`/`error`/`fallback` painters.
 
-```kotlin
-AsyncImage(
-    model = imageUrl,
-    contentDescription = "Airline logo",
-    placeholder = painterResource(R.drawable.placeholder_airline),
-    error = painterResource(R.drawable.error_airline),
-    fallback = painterResource(R.drawable.default_airline),
-    modifier = Modifier
-        .size(48.dp)
-        .clip(CircleShape),
-)
-```
+See `references/patterns.md` -> "Image Loading with Coil" for the basic
+`AsyncImage`, the `ImageLoaderFactory` configuration, the size-optimization
+request, and the placeholder/error states.
 
 ## General Performance Patterns
 
-### derivedStateOf for Expensive Computations
-
-```kotlin
-@Composable
-fun FlightList(flights: List<Flight>) {
-    val listState = rememberLazyListState()
-
-    // Only recalculates when the derived condition changes
-    val showScrollToTop by remember {
-        derivedStateOf { listState.firstVisibleItemIndex > 5 }
-    }
-
-    Box {
-        LazyColumn(state = listState) {
-            items(flights, key = { it.id }) { FlightCard(it) }
-        }
-
-        if (showScrollToTop) {
-            FloatingActionButton(
-                onClick = { /* scroll to top */ },
-                modifier = Modifier.align(Alignment.BottomEnd),
-            ) {
-                Icon(Icons.Default.ArrowUpward, contentDescription = "Scroll to top")
-            }
-        }
-    }
-}
-```
-
-### remember for Expensive Objects
-
-```kotlin
-// WRONG: recreated every recomposition
-@Composable
-fun DateDisplay(timestamp: Long) {
-    val formatter = SimpleDateFormat("dd MMM yyyy", Locale.getDefault())
-    Text(formatter.format(Date(timestamp)))
-}
-
-// CORRECT: remembered across recompositions
-@Composable
-fun DateDisplay(timestamp: Long) {
-    val formatter = remember { SimpleDateFormat("dd MMM yyyy", Locale.getDefault()) }
-    Text(formatter.format(Date(timestamp)))
-}
-```
-
-### Debounce for Search
-
-```kotlin
-@HiltViewModel
-class SearchViewModel @Inject constructor(
-    private val searchUseCase: SearchFlightsUseCase,
-) : ViewModel() {
-
-    private val searchQuery = MutableStateFlow("")
-
-    val searchResults: StateFlow<List<Flight>> = searchQuery
-        .debounce(300) // Wait 300ms after last keystroke
-        .distinctUntilChanged()
-        .filter { it.length >= 2 }
-        .flatMapLatest { query -> searchUseCase(query) }
-        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
-
-    fun onQueryChange(query: String) {
-        searchQuery.value = query
-    }
-}
-```
+- **`derivedStateOf`** for values computed from state that change less often
+  than their inputs (e.g. a scroll-to-top flag derived from
+  `firstVisibleItemIndex`), so recomposition triggers only on the derived
+  change.
+- **`remember`** expensive objects (formatters, regex) so they survive
+  recomposition instead of being reallocated each pass.
+- **Debounce** search input in the ViewModel (`debounce(300)` +
+  `distinctUntilChanged()` + `flatMapLatest`) to avoid a request per keystroke.
+
+See `references/patterns.md` -> "General Performance Patterns" for the
+`derivedStateOf` list example, the `remember` formatter contrast, and the
+debounced search `StateFlow`.
 
 ## Do's and Don'ts