Auditing Compose Performance

Auditing Compose Performance — the Measure → Diagnose → Fix → Verify orchestrator

This is the highest-level entry point in the compose-performance-skills library. When the developer's symptom is broad — "the app feels sluggish", "scroll is rough everywhere", "we're starting a perf sprint", "where do we even start?" — Claude enters here. The orchestrator does NOT replace the 25 focused skills; it sequences them through a four-phase loop and produces a written audit report at the end.

The phases are Measure → Diagnose → Fix → Verify, run in order, never skipped. Phase 1 establishes baseline numbers from a release + R8 build on a real device, because anything else is fiction. Phase 2 turns symptoms into named causes from the Compose Compiler reports, Layout Inspector, and runtime tracing. Phase 3 applies one targeted fix at a time, re-measuring between fixes so the delta of each change is provable. Phase 4 regenerates the Baseline Profile, locks in a CI stability gate, and commits the baseline files so regressions cannot slip back.

Perf work without measurement is guessing. Skydoves hot take #1 applies throughout: DO NOT chase 100% skippability — that is a diagnostic on a compiler report, not the goal. The goal is FrameTimingMetric and StartupTimingMetric improvement on a real device.

When to use this skill

• The developer reports broad sluggishness with no specific surface ("the app feels heavy", "everything is slow").
• A team is kicking off a performance sprint and wants a structured plan.
• A new team member needs onboarding to a perf-troubled codebase.
• A pre-release perf gate is required before shipping.
• The user asks for an "audit", "perf review", or a written deliverable.
• The user has no idea where to start and wants Claude to triage.

When NOT to use this skill

• A specific symptom is already named (scroll jank in LazyColumn, derivedStateOf not firing, custom modifier recomposing). Go straight to the focused skill. See ../../INDEX.md for the symptom→skill map.
• The developer only wants to fix one issue and does not want a written report. Pick the focused skill from ../../INDEX.md.
• No release build is possible (e.g. broken signing config). Resolve that first; this audit MUST measure release.

Prerequisites

• Project builds the release variant successfully (./gradlew assembleRelease).
• At least one physical Android device for measurement. Emulator numbers are not representative.
• A Macrobenchmark module is present, or willingness to add one (see ../../measurement/generating-baseline-profiles/SKILL.md).
• Willingness to commit Baseline Profile and stability baseline files to the repo.
• Compose Compiler 1.5.5+ for stabilityConfigurationFile. Kotlin 2.0.20+ for Strong Skipping default. AGP 8.2+ for the Baseline Profile Generator template.
• Optional but recommended: a feature branch to land each fix as its own PR.

Workflow

Run all four phases in order. DO NOT skip ahead. After each Phase 3 fix, return to Phase 1 to re-measure and Phase 2 to re-diagnose before applying the next fix.

Phase 1 — Measure (establish baseline numbers BEFORE changing any code)

• Confirm the release variant builds and is the measurement target. Cross-link ../../measurement/testing-compose-in-release-mode/SKILL.md.
• Confirm R8 is enabled correctly (full mode, proguard-android-optimize.txt, resource shrinking on). Cross-link ../../build/configuring-r8-for-compose/SKILL.md.
• Generate or refresh the Baseline Profile via the Baseline Profile Generator module. Cross-link ../../measurement/generating-baseline-profiles/SKILL.md.
• Capture cold startup numbers with MacrobenchmarkRule + StartupTimingMetric under CompilationMode.Partial(BaselineProfileMode.Require). Run ≥10 iterations.
• Capture scroll numbers for the suspect surface with FrameTimingMetric (P50, P90, P99). Run ≥5 iterations on the same device.
• Record every number in the audit report's "Baseline (Phase 1)" section. MUST be done before any code change.

// Phase 1 baseline scroll measurement (record P50/P90/P99 of frameDurationCpuMs)
@Test fun feedScroll() = rule.measureRepeated(
    packageName = "com.example",
    metrics = listOf(FrameTimingMetric()),
    iterations = 5,
    startupMode = StartupMode.WARM,
    compilationMode = CompilationMode.Partial(BaselineProfileMode.Require),
) {
    startActivityAndWait()
    device.findObject(By.res("feed")).fling(Direction.DOWN)
}

Phase 2 — Diagnose (turn symptoms into named causes)

• Enable Compose Compiler reports for the release variant. Cross-link ../../stability/diagnosing-compose-stability/SKILL.md.
• Read <module>-composables.txt. List every restartable-but-not-skippable composable and the unstable parameter that blocks skipping.
• Read <module>-classes.txt. List every unstable class with the offending field (a var, an unstable field type, an interface, etc.).
• For surprising verdicts (runtime, unknown, "this looks stable but the compiler disagrees"), run ../../stability/understanding-stability-inference/SKILL.md to walk the 12-phase algorithm.
• Layout Inspector pass on the suspect surfaces: enable recomposition counts and skip counts. Identify hotspots with high counts and low skips. Cross-link ../../recomposition/debugging-recompositions/SKILL.md.
• For release-grade tracing (Layout Inspector cannot reach release builds), instrument the top hotspots with @TraceRecomposition. Cross-link ../../measurement/tracing-recompositions-at-runtime/SKILL.md.
• Triage: rank issues by frequency × cost. A recomposition in a hot LazyColumn row beats a 10× recomposition on a one-off settings screen. DO NOT rank by compiler-report severity alone.
• Write the Diagnosis section of the audit report: top-5 hotspots, count of restartable-not-skippable composables, count of unstable classes, count of phase-misplaced reads.

Phase 3 — Fix (apply targeted, minimal-diff changes — one cause per PR)

For each ranked issue, pick the matching focused skill and apply the fix. PREFERRED: one PR per skill, so the diff is reviewable and bisectable. After each fix, re-run Phase 1 (measure) and Phase 2 (diagnose) to confirm the change moved the right needle and did not regress another.

• Stability fixes (unstable data class, List/Set/Map parameter, java.time.LocalDateTime) → ../../stability/stabilizing-compose-types/SKILL.md.
• Strong Skipping audit (verify mode is on, find lambda capture sites that need @DontMemoize or @NonSkippableComposable) → ../../recomposition/using-strong-skipping-correctly/SKILL.md.
• Phase-deferral fixes for animations and scroll (Modifier.offset { }, Modifier.graphicsLayer { }, Modifier.drawBehind { }) → ../../recomposition/deferring-state-reads/SKILL.md.
• derivedStateOf misuse (missing remember, captured non-state vars, used where input frequency does not exceed output frequency) → ../../recomposition/choosing-derivedstateof/SKILL.md.
• Lazy layout key and contentType for LazyColumn/LazyRow/LazyVerticalGrid, hoisting modifier chains out of the items lambda → ../../lists/optimizing-lazy-layouts/SKILL.md.
• Lazy prefetch tuning only if Compose Foundation 1.10+ defaults still drop frames at high scroll velocity → ../../lists/configuring-lazy-prefetch/SKILL.md.
• Custom modifier migrations from Modifier.composed { } to Modifier.Node + ModifierNodeElement → ../../modifiers/migrating-to-modifier-node/SKILL.md.
• Modifier order bugs (background painted in wrong region, click area extends past visible button, clip after background) → ../../modifiers/ordering-modifier-chains/SKILL.md.
• Flow collection safety (collectAsState → collectAsStateWithLifecycle, hoist Flow<T> parameters out of composables, add .conflate() / .distinctUntilChanged()) → ../../side-effects/collecting-flows-safely/SKILL.md.
• Effect API audit (LaunchedEffect vs RememberedEffect vs DisposableEffect vs SideEffect, stale callbacks via rememberUpdatedState) → ../../side-effects/using-efficient-effects/SKILL.md.
• After each fix: re-run Phase 1 + Phase 2 and record the Macrobenchmark delta in the audit report's Phase 3 table.

Phase 4 — Verify (lock it in)

• Re-generate the Baseline Profile so the now-faster code paths are captured. Cross-link ../../measurement/generating-baseline-profiles/SKILL.md.
• Compare Macrobenchmark numbers vs the Phase 1 baseline. Record P50/P90/P99 deltas in the "Verification (Phase 4)" section.
• Set up the CI stability gate so regressions fail the build (stabilityDump once, then stabilityCheck on every PR). Cross-link ../../stability/enforcing-stability-in-ci/SKILL.md.
• Commit app/src/main/generated/baselineProfiles/baseline-prof.txt (or wherever the consumer module placed it).
• Commit app/stability/*.stability baseline files generated by :stabilityDump.
• Document the audit report (template below) and circulate. MUST NOT declare the audit complete without the written report.