Diagnosing Compose Stability

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 87cfb886f00d · 16 Oct 2026Report an issue or request a re-scan

• Publisherskydoves GitHub userOwner of the repository this skill is read from
• Source folderskydoves/compose-performance-skills/stability/diagnosing-compose-stabilityThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict87cfb886f00dA new audit runs when the source changes
• Repository statusNot archivedLast push 121 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use this skill to diagnose Jetpack Compose stability problems by enabling and reading the Compose Compiler Reports (classes.txt, composables.txt, composables.csv, module.json). Covers the Gradle DSL, the release-only…

---
name: diagnosing-compose-stability
description: Use this skill to diagnose Jetpack Compose stability problems by enabling and reading the Compose Compiler Reports (classes.txt, composables.txt, composables.csv, module.json). Covers the Gradle DSL, the release-only build requirement, and how to interpret per-class and per-composable stability annotations including stable, unstable, runtime, restartable, skippable, readonly, @static, and @dynamic markers. Use when the developer asks "why does this recompose", reports jank, dropped frames, slow scroll, high recomposition count, suspects an unstable parameter, mentions Compose Compiler Reports, classes.txt, composables.txt, module.json, or wants to know which composables are non-skippable. The fix lives in a sibling skill — this one only diagnoses.
license: Apache-2.0. See LICENSE for complete terms.
metadata:
  author: Jaewoong Eum (skydoves)
  keywords:
  - jetpack-compose
  - performance
  - stability
  - compose-compiler-reports
  - recomposition
  - skippability
  - classes-txt
  - composables-txt
  - diagnostics
---

# Diagnosing Compose Stability — Read the Compiler Reports First

Compose skips recomposition by comparing parameters. When a parameter is unstable, skipping is disabled — this skill tells Claude how to find out which parameters are unstable and why. The output is a prioritized list of unstable types and non-skippable composables; the fix lives in `../stabilizing-compose-types/SKILL.md`.

## When to use this skill

- The developer asks "why does this recompose?", reports jank, dropped frames, or scroll stutter.
- A `@TraceRecomposition` log shows recomposition counts that exceed the number of meaningful state changes.
- The developer mentions Compose Compiler Reports, `classes.txt`, `composables.txt`, `composables.csv`, `module.json`, or "non-skippable".
- The developer asks how to find unstable parameters, or whether `List<Foo>`, `LocalDateTime`, or a domain type is stable.
- A reviewer asks for evidence that a perf-sensitive composable is skippable.

## When NOT to use this skill

- The unstable types are already known — jump straight to `../stabilizing-compose-types/SKILL.md`.
- The symptom is a wrong-phase state read (`Modifier.alpha(state.value)`); use `../../recomposition/deferring-state-reads/SKILL.md`.
- The symptom is a `derivedStateOf` misuse; use `../../recomposition/choosing-derivedstateof/SKILL.md`.
- The developer wants CI gating instead of one-shot diagnosis; use `../enforcing-stability-in-ci/SKILL.md`.

## Prerequisites

- Kotlin **2.0.0+** with the Compose Compiler Gradle plugin applied: `id("org.jetbrains.kotlin.plugin.compose")`. The pre-2.0 `kotlinCompilerExtensionVersion` flow is obsolete.
- A buildable **release** variant of the target module. Reports MUST be produced in release; debug adds Live Literals which makes constants look dynamic and skews every report.
- Apply the `org.jetbrains.kotlin.plugin.compose` Gradle plugin (Kotlin 2.0+). The `composeCompiler { ... }` extension is owned by that plugin; AGP version is incidental.
- Optional but **PREFERRED:** the developer has a stability baseline goal, not a 100-percent-skippable goal (skydoves hot take #1 — skippability is a diagnostic, not a KPI).

## Workflow

- [ ] **1. Enable the reports in the module's `build.gradle.kts`.** Scope to release only — debug builds emit misleading data.

```kotlin
// app/build.gradle.kts (or any compose module)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("org.jetbrains.kotlin.plugin.compose")
}

composeCompiler {
    // Only emit reports for release to avoid Live Literals noise.
    val isReleaseBuild = providers.gradleProperty("composeCompilerReports").orNull == "true"
    if (isReleaseBuild) {
        reportsDestination = layout.buildDirectory.dir("compose_compiler")
        metricsDestination = layout.buildDirectory.dir("compose_compiler")
    }
}
```

Or the always-on form:

```kotlin
composeCompiler {
    reportsDestination = layout.buildDirectory.dir("compose_compiler")
    metricsDestination = layout.buildDirectory.dir("compose_compiler")
    // Optional — opt mutable third-party types into stability:
    stabilityConfigurationFiles.add(
        rootProject.layout.projectDirectory.file("stability_config.conf")
    )
}
```

- [ ] **2. Build the release variant** so Live Literals and interpreted-mode noise are absent:

```bash
./gradlew :app:assembleRelease -PcomposeCompilerReports=true
```

For a library module: `./gradlew :feature-feed:assembleRelease`. The release flavor is required — see RIGHT/WRONG below.

- [ ] **3. Locate the four output files.** They are written to `<module>/build/compose_compiler/`:

```
app/build/compose_compiler/
├── app_release-classes.txt        # per-class stability
├── app_release-composables.txt    # per-composable signatures
├── app_release-composables.csv    # CSV mirror of the above (CI-friendly)
└── app_release-module.json        # aggregate counts
```

If any file is missing, the plugin did not run for that variant — re-check that `composeCompiler { reportsDestination = ... }` is on the right module and that the build was release.

- [ ] **4. Open `composables.txt` first.** This is the highest-signal file. Search for `restartable` lines that are **not** followed by `skippable`. Each one is a recomposition entry point that cannot be skipped. Inside each block, read the per-parameter prefix: `stable`, `unstable`, `@static`, `@dynamic`. Any `unstable` parameter blocks skipping. See `references/reading-composables-txt.md` for the full grammar.

- [ ] **5. Open `classes.txt` to learn _why_ a class is unstable.** For every type flagged `unstable` in composables.txt, find its declaration in classes.txt. The line tells you whether a `var` field, a generic parameter, or an unstable nested type is the cause. The `runtime stable class Box { stable val value: T }` shape means "this class is stable iff the runtime `$stable: Int` field of

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/skydoves/compose-performance-skills
git -C compose-performance-skills checkout 87cfb886f00d

Works in

1. 2026-10-16
   ✓SAFE B 89 / 100

   first audit · source 87cfb886f00d

Questions about Diagnosing Compose Stability

• github.com/skydoves/compose-performance-skills/tree/main/stabili — the audited source at commit 87cfb886f00d and every finding aboveObserved · 16 Oct 2026

Spotted something wrong? Report a correction · Methodology