jetpack-compose-audit

# Jetpack Compose Audit This skill audits Android Jetpack Compose repositories with a strict, evidence-based report. **Rubric version:** v1 — current as of 2026-04-13. Compose track: Kotlin 2.0.20+ / Compose Compiler 1.5.4+ (Strong Skipping Mode default). 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>). ## 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. - Compose Multiplatform-specific rules (`expect`/`actual`, target-specific code paths). - Wear OS / TV / Auto / Glance surfaces. - 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 - baseline-profile related modules or config 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` 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. ### 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. 2. **Check for a Gradle wrapper** in the target: `test -x <target>/gradlew`. If missing, skip to the fallback in step 6. 3. **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. 4. **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. 5. **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. 6. **Fallback if the build fails or Gradle is unavailable.** Proceed with source-inferred stability findings, but: - set `Compiler diagnostics used: no` in the report's Notes And Limits and explain the failure reason briefly (wrapper missing, compile error, timeout) - reduce overall confidence by one level - state each stability-related deduction as "inferred from source — not verified against compiler reports" Stability deductions from step 5 are measured evidence and should be weighted normally. Fallback deductions from step 6 are inferred and must be flagged as such in the report. ### 5. Audit The Four Categories Use the scoring rubric in `references/scoring.md` and the heuristics in `references/search-playbook.md`. #### Performance Focus on: - expensive work in composition - avoidable recomposition - lazy list keys - bad state-read timing - unstable or overly broad reads - backwards writes - obvious release-performance hygiene where visible #### State Management Focus on: - hoisting correctness - single source of truth - reusable stateless seams - correct use of `remember` vs `rememberSaveable` - lifecycle-aware observable collection - observable vs non-observable mutable state #### Side Effects Focus on: - side effects incorrectly done in composition - correct effect API choice - effect keys - stale lambda capture - cleanup correctness - lifecycle-aware effect behavior #### Composable API Quality Focus on reusable internal components, not every leaf screen. Check: - `modifier` presence and placement - parameter order - explicit over implicit configuration - meaningful defaults - avoiding `MutableState<T>` or `State<T>` parameters in reusable APIs where a better shape exists - component purpose and layering ### 6. Verify Findings Before deducting points: - read the file where the smell appears - make sure the pattern is real, not a false positive - check whether the repo already has a compensating pattern elsewhere - distinguish one-off mistakes from systemic patterns - for stability findings (skippable / restartable / unstable params), use the compiler reports generated in Step 4. Cite the specific report line (e.g. `app/build/compose_audit/app_release-classes.txt:42`) as evidence. Only fall back to source-inferred stability claims if Step 4 failed, and label them as such. ### 7. Score Assign each category a `0-10` score and a status: - `0-3`: fail - `4-6`: needs work - `7-8`: solid - `9-10`: excellent Use the weights in `references/scoring.md` to compute the overall score. **Measured ceilings are mandatory, not suggestive.** When Step 4 produced compiler reports, the Performance rubric in `references/scoring.md` defines a ceiling based on `skippable%` and unstable-param count. After arriving at a qualitative Performance score, you MUST apply the ceiling and lower the score if it exceeds the cap. Show the math in the report: ``` Performance ceiling check: skippable% = 186/273 = 68.1% → falls in 50-70% band → cap at 4 qualitative score: 7 applied score: 4 (ceiling lowered from 7) ``` Do not round `skippable%` up into a higher band. `68.1%` is not `≥70%`. If a qualitative score lands at or below the ceiling, no adjustment is needed — but the check itself must appear in the report so the reader can audit it. If a category genuinely has too little auditable surface area, mark it `N/A`, explain why, and renormalize the remaining weights. ### 8. Write The Report Use `references/report-template.md`. The report must include: - overall score - category score table - top critical findings - category-by-category reasoning - evidence file paths - prioritized remediation list - optional follow-up note to run `material-3` if design issues are suspected Write the report to: - `COMPOSE-AUDIT-REPORT.md` inside the audited target (the path the user passed), not the current working directory. If `COMPOSE-AUDIT-REPORT.md` already exists at that path, do not overwrite it silently. Either confirm overwrite with the user, or write to `COMPOSE-AUDIT-REPORT-<YYYY-MM-DD>.md` alongside it. ### 9. Return A Short Summary In chat, produce a summary that mirrors the report's `Prioritized Fixes` section — not a generic recap. The developer should be able to act on the summary alone without opening the report file. Include: - overall score (and the delta vs. any prior `COMPOSE-AUDIT-REPORT*.md` at the same path, if present) - one-line judgment for each category, with the applied ceiling if any (e.g. "Performance 6/10 — capped by 79% skippability") - compiler-report highlights when Step 4 succeeded: Strong Skipping on/off, `skippable%`, count of unstable shared types, any module that failed to build - **top three actionable fixes**, each with: - the concrete change ("add `key = { it.id }` to `items(...)` in `feed/FeedList.kt:42`") - file path(s) and line numbers — the same ones listed in the report's Prioritized Fixes - one official doc URL from `references/canonical-sources.md` - expected impact ("unlocks skipping for `FeedItem`, should move `skippable%` from 79% → ~90%") - whether a `material-3` audit is worth running next The top-three fixes in the chat summary MUST be the same items as the report's `Prioritized Fixes` list (same file paths, same doc links). Do not add generic advice in chat that isn't in the written report. ## Evidence Rules - Prefer multiple examples over one dramatic example. - Use positive evidence too, not just failures. - Do not infer runtime problems you cannot justify from the code. - When a rule is based on official guidance but app-level tradeoffs may justify deviation, call it out as a tradeoff instead of pretending it is always wrong. ## Large Repo Strategy For medium or large repositories: 1. Map modules first. 2. Pick representative files per module. 3. Parallelize category scans when possible. 4. Merge repeated findings into systemic issues instead of listing the same smell twenty times. ## What To Avoid - Do not produce a generic checklist with no repository evidence. - Do not turn the report into a public-library API lecture if the repo is an app. - Do not inflate the performance score just because the app uses Compose. - Do not over-penalize isolated experiments or sample files unless they are part of production paths. - Do not score design in v1. - Do not flag `LaunchedEffect(Unit)` or `LaunchedEffect(true)` on its own — the "run once" pattern is idiomatic. Only flag it when the body captures a value that may change without `rememberUpdatedState`. - Do not deduct on Compose Multiplatform code paths for Android-only APIs (`collectAsStateWithLifecycle`, `lifecycle-runtime-compose`). Note the platform constraint as a tradeoff instead. - Do not double-count the same root cause across categories. A stability problem typically surfaces in both Performance and State — pick the dominant category and cross-reference. ## References - `references/scoring.md` — per-rule rubric with inline citations - `references/search-playbook.md` — search patterns and red-flag heuristics - `references/report-template.md` — required structure for `COMPOSE-AUDIT-REPORT.md` - `references/canonical-sources.md` — the official URLs every deduction must cite - `references/diagnostics.md` — copy-pasteable Gradle/code snippets for Compose Compiler reports, stability config, baseline profiles, and R8 checks - `scripts/compose-reports.init.gradle` — Gradle init script the skill injects via `--init-script` in Step 4 to generate compiler reports automatically