Android polish

Android Polish & Ship Gate

This is the final stage of the Android app pipeline. The app exists and builds; this pass closes the gap between "functionally complete" and "passes Google Play review and feels finished." It is the last gate, so it carries the strictest rule in the whole pipeline: every item is verified with a command, a tool, or a snapshot - never an eyeball.

Pipeline position:

research -> planning -> monetization -> design -> MCP code -> > POLISH / SHIP GATE <

Core philosophy

1. The happy path was the easy 80%. The polish is in the empty screens, the error states, the slow network, the rotated phone, the backgrounded-and-killed process, the screen reader, the 200%-font user, and the aggressive-battery OEM.
2. Verifiable, not vibes - enforced. This skill's #1 failure mode is eyeballing the home screen and declaring victory. So every check names how to verify it: a gradle task, a tool, a snapshot test, or a measured number. If you cannot verify it, it is not done. A polish report without command output / tool results / snapshots is not a polish report.
3. Ship-blockers before polish. A beautiful app Play rejects is not shippable. Clear the P0 compliance and crash checks before spending budget on screenshot framing.
4. Match the design system. Reuse the tokens, motion, and components the design skill chose. Don't introduce a new accent or radius in the polish pass.

How to run it

Work strictly by severity. Each item is tagged:

• P0 - blocks ship. Play will reject it, or the app crashes / loses data. Must pass with evidence.
• P1 - quality. Real users hit it; fix before a public launch.
• P2 - spit-shine. Final finish.

Deep how-to for the heavier topics lives in references/. Read the relevant file when its topic comes up; don't inline all of it here.

P0 - Ship-blockers & crashes (do these first)

Play submission requirements current as of 2026 - a checklist that skips these can green-light an app Play will reject. Full detail + verification commands in references/01-ship-blockers.md and references/06-release-and-security.md.

• You are testing the build you think you are. Before trusting any result below, confirm Android Studio's active project matches the path you edited, then force-stop + uninstall the app and do a clean reinstall. A change that "won't show up" after a rebuild is an environment/build-target problem until proven otherwise - do not patch correct code chasing a phantom. Verify: your latest visible change is on-screen after a clean reinstall.
• Target API meets Play's minimum. New apps and updates require API 35+; API 36 from Aug 31, 2026. Verify: targetSdk in build.gradle.kts is at or above the current Play floor.
• Ship an AAB with Play App Signing. APKs cannot be uploaded for new apps, and a debug-signed build cannot ship. Verify: ./gradlew bundleRelease produces an .aab; the release signing config uses an upload key; Play App Signing is enrolled.
• 16 KB page-size compliance. From May 1, 2026, updates without 16 KB support cannot be released (new apps since Nov 2025). Affects any app with native code / NDK SDKs (many media, analytics, RN/Flutter libs). Verify: check .so alignment (APK Analyzer or check_elf_alignment.sh), or confirm "no native code -> compliant."
• Themed icon monochrome layer. Android 13+ themed icons need a <monochrome> layer in the adaptive icon (108x108dp single-color silhouette) or the system auto-generates a poor one. Verify: <adaptive-icon> contains <monochrome>.
• No release-build crashes / ANRs on the core journey. Verify: run the release variant through the primary flow; confirm crash/ANR reporting (Crashlytics/Sentry) is actually wired; treat planning's stability budget + Android Vitals thresholds as the explicit gate.
• Release build is shrunk and clean. R8 + shrinkResources on; isDebuggable = false; no secrets in source; keep-rules don't strip anything used by reflection. Verify: ./gradlew bundleRelease + APK Analyzer; grep the source tree for keys/tokens.
• Edge-to-edge not broken. Mandatory at targetSdk 35+. Verify: content respects insets, nothing hidden under the system bars (check a tall and a short device).

P1 - Quality (fix before a public launch)

• Every screen has loading / empty / error states. Not just the happy path. Loads under ~2s use skeletons; known-progress uses a determinate indicator; cached/instant content shows no loader. Verify: a screenshot/snapshot test per state - see references/02-testing.md.
• Process-death restoration. The common production failure, harder than rotation. Verify: enable Developer Options -> Don't keep activities (or background-kill), reopen, confirm rememberSaveable / SavedStateHandle restore the user's place.
• Accessibility (WCAG 2.2 AA). Labels, semantic headings, stateDescription for toggles, liveRegion for dynamic content, focus order, mergeDescendants for compound items; SC 2.5.8 target size (Material's 48dp clears it), SC 1.4.11 non-text contrast 3:1 for icons/controls. Verify: Accessibility Scanner + a TalkBack pass + a 200%-font screenshot. Full list in references/05-accessibility.md.
• Static analysis & code hygiene. ./gradlew lint (with a baseline), detekt / ktlint / Spotless formatting, prune unused resources & dependencies, sweep dead code / TODO / debug Log (no PII; strip verbose logging in release), LeakCanary for leaks, and the architecture anti-patterns (no GlobalScope / runBlocking, collectAsStateWithLifecycle not collectAsState, no state stranded in MainActivity). See references/03-static-analysis-and-hygiene.md.
• Automated tests exist and pass. Unit tests on core logic, Compose UI tests on critical flows, and screenshot/snapshot tests that lock visual states - dark mode, 200% font, RTL, key locales (Paparazzi / Roborazzi / Compose Preview Screenshot Testing; Roborazzi can run a11y checks in the same pass). This is how "every screen has its three states" becomes verified instead of asserted. Verify: ./gradlew test connectedCheck + your snapshot task. See references/02-testing.md.
• Performance. Baseline and Startup Profiles generated and wired into the release build; measured before/after with Macrobenchmark on a real device (not an emulator); per-second/streaming updates don't recompose the whole screen. Verify: recomposition counts (Layout Inspector), the Compose compiler stability report, and Macrobenchmark numbers. See references/04-performance.md.
• Localization beyond strings.xml. "No hardcoded strings" is necessary, not sufficient: RTL/mirroring, pseudolocales (en-XA / ar-XB) to surface truncation + string concatenation, positional format args, <plurals>, locale-aware number/date formatting. Verify: run in a pseudolocale and an RTL locale.
• Dark mode + configuration breadth. A real dark variant on every screen (not auto-inverted); large-screen/foldable layout, landscape, and split-screen/multi-window actually opened and checked. Verify: snapshot tests across configurations.
• Motion. 2-3 meaningful spring-based moments; no celebration on routine actions. Verify: watch the transitions; confirm no dropped frames (JankStats).

P2 - Spit-shine

• Adaptive launcher icon (foreground + background + the P0 monochrome layer). Pull from the asset library if present (below), else place into res/mipmap-* manually.
• Splash screen uses the Splash Screen API, does not appear on warm starts, and hands off without a flash.
• Play listing assets - screenshots (phone + any supported larger form factors) from real screens, short/full description seeded from the research ASO keywords, Data Safety form matching what the app actually collects.

Using the asset library (optional)

If an asset-library MCP is available (list_assets / read_asset / copy_asset_to_project), pull icons, fonts, and imagery from it and copy them into res/mipmap-*, res/font, etc. If it is not available, that is fine - generate or source the asset and place it manually into the right res/ folder. Never block the polish pass on the asset library.

Note on building

Building and running happen with the buttons in Android Studio (the MCP server doesn't build). Run the gradle verification tasks above from Studio or the terminal; have the user report results, or read them back via the MCP where possible.

Independent review before sign-off

Polish is the last gate, so it most needs an outside check. Before declaring the app shippable, run an independent adversarial pass: where subagents are available, launch a separate one (the Task tool) briefed to "find what still makes this feel like a prototype, and what would fail Google Play review." Otherwise red-team it in a fresh frame. Record what it finds and fix or explicitly accept each item. A self-passed checklist from the same agent that built the app is the failure mode to avoid.

Output

A polish report, severity-ordered: each P0 item marked pass/fail with the verification evidence (the command output, the tool result, the snapshot), then P1, then P2, then any remaining items that need the user (signing keys, real-device battery testing, store screenshots). The app is shippable only when every P0 passes with evidence.

Lessons learned / v-next candidates

• v1 -> v2 (this pass). v1 was a flat memory-jogger: no verification method, no severity, and missing the 2026 Play ship-blockers (16 KB pages, target-API gate, AAB + Play App Signing, themed-icon monochrome layer). It also hard-depended on an asset-library MCP and omitted whole categories (automated testing, static analysis). v2 adds severity ordering, a verification method per item, the ship-blockers, conditional asset use, an independent review step, and reference files for depth.
• Watch for the agent still eyeballing instead of running the verification command - if reports lack command output/snapshots, tighten the wording.
• Candidate: a machine-checkable subset (lint + tests + bundle + size) the MCP could run directly and diff between runs.
• Reference files date fast - re-check the Play target-API floor, the 16 KB deadline, and tool names each cycle.

File map

android-polish/
├── SKILL.md                              <- this file
└── references/
    ├── 01-ship-blockers.md               <- 2026 Play submission gates
    ├── 02-testing.md                     <- unit + Compose UI + screenshot/a11y snapshots
    ├── 03-static-analysis-and-hygiene.md <- lint, detekt/ktlint, pruning, leaks, anti-patterns
    ├── 04-performance.md                 <- baseline+startup profiles, macrobenchmark, recomposition
    ├── 05-accessibility.md               <- WCAG 2.2, semantics, tooling
    └── 06-release-and-security.md        <- AAB, signing, shrinking, security hygiene