hamen/compose_skill/jetpack-compose-audit

Jetpack Compose Audit

This skill audits Android Jetpack Compose repositories with a strict, evidence-based report.

Skill version: 4.3.2 — released 2026-07-07. Compose track: Kotlin 2.0.20+ / Compose Compiler 1.5.4+ (Strong Skipping Mode default). See the README changelog for what changed.

It is intentionally focused on four categories:

• Performance
• State management
• Side effects
• Composable API quality

This skill does not score design or Material 3 compliance in v1. If the audit surfaces likely design-system problems, recommend a follow-up audit with the material-3 skill (reference implementation: <https://github.com/hamen/material-3-skill>).

Testing, focus/keyboard navigation, and Compose Multiplatform are coverage notes, not score categories. Map those surfaces when present, flag obvious risk, and recommend the focused compose-agent references (testing, focus, kmp) as follow-up work. Do not fold them into the 0-100 score unless the same root cause clearly affects one of the four scored categories.

Android launch UX resources are also adjacent coverage, not a score category. Always scan splash-screen theme resources; if Android 12+ could render a static splash icon blurry, include it as an Android Launch UX finding and allow it into Critical Findings / Prioritized Fixes when the evidence is concrete.

Out Of Scope In v1

Owned and deliberate scope choices — call out the limitation in the report rather than silently producing thin coverage:

• Material 3 compliance, theming, color/typography tokens — defer to the material-3 skill.
• Accessibility scoring (semantics, content descriptions, touch-target sizing) — flag obvious gaps as a note, do not score.
• UI test coverage and Compose test rule patterns — note presence/absence, do not score; recommend compose-agent focus on testing for deeper review.
• Compose Multiplatform-specific rules (expect/actual, target-specific code paths) — note surface area and obvious platform-boundary risk; recommend compose-agent focus on kmp for deeper review.
• Wear OS / TV / Auto / Glance surfaces — note obvious focus / keyboard / D-pad risk; recommend compose-agent focus on focus for deeper review.
• Build performance (incremental compilation, KSP/KAPT choice).

If the user explicitly asks for any of these, narrow the scope and state it in the report.

When To Use

Use this skill when the user asks to:

• audit a Jetpack Compose repository
• review Compose architecture or quality
• rate a codebase with scores
• inspect recomposition, state, or effects issues
• identify Compose best-practice violations in an existing repo

Typical trigger phrases:

• "audit this Compose repo"
• "score this Jetpack Compose codebase"
• "review state hoisting and side effects"
• "check Compose performance"
• "rate this repository"

Expected Output

Produce both:

• a repository report file named COMPOSE-AUDIT-REPORT.md
• a short chat summary with the overall score, category scores, worst issues, and the top fixes

Audit Principles

• Be strict, but evidence-based.
• Do not score from search hits alone. Read representative files before judging a category.
• Cite concrete file paths in the report for every important deduction.
• Cite an official documentation URL for every deduction. No "trust me" findings — the rubric maps every rule to a canonical source in references/canonical-sources.md. The report template requires a References: line per finding.
• Prefer canonical Android guidance over folklore.
• Treat performance as important, but not as the only lens.
• Do not punish app code for failing public-library purity tests. Apply API-quality checks mainly to reusable internal components, design-system pieces, and shared UI building blocks.
• Reserve 0-3 scores for repeated or systemic problems, not isolated mistakes.
• Do not award 9-10 unless the repo is consistently strong across the category.

Process

1. Confirm Scope

Identify the target path:

• If the user passed an explicit path ([repo path or module path]), use it.
• If no path was passed, default to the current working directory.
• If the path does not exist, ask the user to clarify.

Before mapping modules, confirm Compose is actually present (fast-fail):

• grep for androidx.compose in any build.gradle* or libs.versions.toml
• grep for setContent { or @Composable under src/

If neither shows up, stop and report that the target is out of scope. Do not run a full module map first.

If Compose is present only in samples/, demos/, or test sources (no production usage), narrow the scope to those directories, set confidence to Low, and state in the report that the audit is over sample code rather than production paths. Do not score production-quality categories against demo code.

2. Map The Repository

Before scoring, identify:

• Gradle modules
• Android app and feature modules
• likely Compose source roots
• shared UI/component packages
• theme or design-system packages
• state holder or ViewModel areas
• test and preview locations
• UI test, screenshot test, focus/keyboard test, and semantics-test locations
• baseline-profile related modules or config if present
• KMP / Compose Multiplatform source sets (commonMain, androidMain, iosMain, desktopMain, wasmJsMain) if present
• Android splash-screen themes and drawable resources (res/values*/themes.xml, styles.xml, drawable-v31) if present

3. Build A Compose Surface Map

Look for:

• @Composable functions
• reusable UI components
• screens and routes
• ViewModel usage
• remember, rememberSaveable, mutableStateOf
• collectAsStateWithLifecycle, collectAsState
• LaunchedEffect, DisposableEffect, SideEffect, rememberUpdatedState, produceState
• LazyColumn, LazyRow, items, itemsIndexed
• animation APIs: animate*AsState, Animatable, updateTransition, rememberInfiniteTransition, AnimatedVisibility, AnimatedContent, Crossfade
• focus APIs: FocusRequester, focusRequester, focusProperties, focusable, onFocusChanged, onPreviewKeyEvent, onKeyEvent
• UI testing APIs: createComposeRule, createAndroidComposeRule, onNodeWithText, assertIsDisplayed, assertIsFocused, screenshot test rules
• KMP/CMP indicators: commonMain, expect, actual, AndroidView, UIKitView, platform services passed into common UI
• Android launch resources: windowSplashScreenAnimatedIcon, android:windowSplashScreenAnimatedIcon, drawable-v31, animated-vector

If the repo is large, audit by category or by module. If subagents are available, parallelize category scans by spawning Explore-type subagents (no write tools) and merge the findings.

3a. Audit Android Launch UX Resources

This is non-scored adjacent coverage, but it should run on every normal audit because the failure is user-visible and cheap to miss in Kotlin-only scans.

Look for:

• windowSplashScreenAnimatedIcon and android:windowSplashScreenAnimatedIcon in res/values*/themes.xml and res/values*/styles.xml
• referenced drawables such as @drawable/ic_splash
• API-qualified overrides in res/drawable-v31/
• drawable XML roots: <animated-vector>, <vector>, <adaptive-icon>, <bitmap>, <layer-list>

An AnimatedVectorDrawable is Animatable, so the platform draws it on a SurfaceView at full size; a static icon instead falls onto the internal ImmobileIconDrawable path (pre-rendered at 108 dp, upscaled into the 160/192 dp icon), which is what looks blurry on XHDPI+ devices. Flag a finding when all of these are true:

1. A theme sets windowSplashScreenAnimatedIcon for an Android app.
2. The API 31+ resource resolution points to a static icon (<vector>, <adaptive-icon>, bitmap, or a layer-list around those), or there is no drawable-v31 override for the referenced splash icon.
3. The resource is not already an <animated-vector> on API 31+.

Report it as Android Launch UX: Android 12+ static splash icon may render blurry, not as a Compose score deduction. Evidence should include the theme item, the resolved drawable file, and whether the res/drawable-v31 animated-vector override is missing. The fix direction is to keep the theme's @drawable/<name> stable and have it resolve to an <animated-vector> on API 31+ that wraps the real vector — no animators are required; an empty `<animated-vector>` is enough, because being an AVD is what changes the render path. One correctness caveat worth carrying into the report: the wrapper must reference a separately-named vector (a wrapper that references its own theme name re-resolves to itself on API 31+ and loops). Cite the Android splash-screen docs, the AndroidX SplashScreen reference, and the platform issue https://issuetracker.google.com/issues/520672537 (which quotes the AOSP source). The bug dates to Android 12 (API 31) on XHDPI+ devices and was open when this skill shipped; confirm the live status against the issue rather than asserting it open-endedly.

4. Generate Compose Compiler Reports (Automatic)

Do not ask the user to edit build.gradle or run commands themselves. The skill runs the build with a bundled Gradle init script that injects reportsDestination / metricsDestination into every Compose module without modifying any file in the target repo. Before scoring, attempt this:

1. Locate the init script shipped with the skill: scripts/compose-reports.init.gradle. The absolute path is the skill's install location — in most installs that's ~/.claude/skills/jetpack-compose-audit/scripts/compose-reports.init.gradle. If you cannot resolve the path, fall back to writing the script to <target>/.compose-audit-reports.init.gradle and delete it after the run.

1. Check for a Gradle wrapper in the target: test -x <target>/gradlew. If missing, skip to the fallback in step 6.

1. Pick a compile target. Prefer the cheapest task that still triggers Kotlin compilation for a Compose module:

• find the first application module via rg -l 'com\.android\.application' -g '*.gradle*'
• try in order: :<app-module>:compileReleaseKotlinAndroid, :<app-module>:compileReleaseKotlin, assembleRelease, assembleDebug
• If the project is Compose-only on a library (com.android.library), use that module instead.

1. Run the build. Inform the user the build is starting (it may take several minutes).

``bash cd <target> && ./gradlew <task> \ --init-script <path-to>/compose-reports.init.gradle \ --no-daemon --quiet ``

Use a 600-second timeout. If the task fails, try the next fallback task in step 3 once. Do not loop indefinitely.

1. Collect the reports.

``bash find <target> -path '*/build/compose_audit/*' \ \( -name '*-classes.txt' -o -name '*-composables.txt' -o -name '*-composables.csv' -o -name '*-module.json' \) ``

From these files, extract:

• unstable classes (lines starting with unstable class in *-classes.txt) used as composable parameters
• non-skippable but restartable named composables (ignore zero-argument lambdas; focus on actual named functions in *-composables.txt or *-composables.csv where isLambda == "0")
• module-wide skippability counts from *-module.json, AND compute the named-only skippability from *-composables.csv (by filtering out rows where isLambda == "1" and calculating sum(skippable) / sum(restartable)). Cite both in the Performance section, noting that zero-argument lambdas can artificially anchor the module-wide metric.