Android UI Visual Review

Android UI Visual Review

Turn a PR or branch into trustworthy visual evidence. The comparison is useful only when the before and after builds use the correct commits, Android runtime, viewport, app state, and navigation path.

Collect the two user choices

Before starting, resolve:

1. Target — a PR URL/number or a branch/commit. If it is missing, ask for it. For a branch, also ask for the intended base when it cannot be inferred safely; otherwise default to the repository's main.
2. Publishing — for a PR target, ask whether the final screenshots and findings should stay local or be posted as a PR comment. Do not perform any GitHub write unless the user explicitly chooses publishing. A prior explicit request such as “post these to the PR” already answers this question.

Do not block on publishing preference while doing read-only analysis if the user has not answered yet. Keep the local workflow useful on its own.

Read the routed guidance

• Read references/analysis-playbook.md for every run. It explains how to map a diff to screens, states, and a capture matrix.
• Read references/fixture-recipes.md whenever the affected screen needs messages, peers, channels, nicknames, settings, permissions, locale, theme, onboarding state, or another non-empty fixture.
• Read references/github-publishing.md only when the user has opted into a PR comment.

Create an isolated review session

Never switch the user's active checkout between before and after revisions. Run from the repository root:

.agents/skills/android-ui-visual-review/scripts/create_review_worktree.sh \
  --target "<PR URL, PR number, branch, or commit>"

For a branch with a non-default base:

.agents/skills/android-ui-visual-review/scripts/create_review_worktree.sh \
  --target "<branch>" \
  --base "<base ref>"

The script fetches a PR head when needed, computes the actual merge-base, creates a detached temporary worktree at the before SHA, and prints:

• session directory
• worktree path
• artifact directory
• before and after SHAs
• PR number/base metadata when applicable

Keep artifacts outside the worktree so checkouts cannot remove them. The script may symlink the ignored local.properties into the temporary worktree; never publish it or quote its contents.

If a review session already exists and its SHAs are verified, reuse it. Do not create a second worktree for the same run.

Establish the visual contract

Use the actual diff, not the PR title, to determine what should be visible.

1. Record git diff --stat, --name-status, and the focused diff between the before and after SHAs.
2. Trace changed UI symbols to their composable/activity, state source, entry point, and prerequisites.
3. Separate direct visual changes from indirect ones such as dynamic color, locale recreation, launcher resources, default data, or backend state shown by an otherwise unchanged screen.
4. Produce a local capture matrix before building. Each row should define: screen, navigation path, fixture, logical width, theme, locale, permissions, and what difference is expected.
5. Include a control state where the UI should remain unchanged when that helps distinguish intentional degradation from a regression.

When the diff contains no UI/resource/state-to-UI change, say so. If the user asked for a screenshot for every target, capture the nearest affected surface before and after and label the expected result no visual delta. Do not invent a UI claim for a behavioral fix.

Use the newest stable Android runtime

Prefer an emulator for repeatable UI evidence. At run time:

1. Inspect installed SDK/system images and current official Android release information. Choose the newest stable API; do not silently use a preview.
2. Create a dedicated AVD and isolated data directory when possible. If current command-line tools cannot create a newly versioned image (for example an extension image), a verified -sysdir override with an isolated data directory is acceptable.
3. After boot, record guest properties rather than trusting the AVD name:

adb -s "$ANDROID_REVIEW_SERIAL" shell getprop ro.build.version.release
adb -s "$ANDROID_REVIEW_SERIAL" shell getprop ro.build.version.sdk
adb -s "$ANDROID_REVIEW_SERIAL" shell getprop ro.build.version.security_patch
adb -s "$ANDROID_REVIEW_SERIAL" shell wm size
adb -s "$ANDROID_REVIEW_SERIAL" shell wm density

Use an explicit emulator serial for every ADB command when any physical device is also connected. Never put serials, device names, local paths, IP addresses, or other machine identifiers into reports or GitHub comments.

Use a physical device only when the affected UI depends on hardware that the emulator cannot reproduce. Ask before changing or clearing a physical device. This skill does not replace Mesh Lab: if the diff changes mesh, transport, crypto, service, or physical peer behavior, use the mesh-lab skill separately before claiming the behavior works.

Build and capture the before state

The worktree starts at the before SHA.

1. Build the debug APK with ./gradlew assembleDebug.
2. Install the ABI-matching APK with adb install -r.
3. Complete stable prerequisites such as onboarding and permissions.
4. Apply the fixture from the capture matrix.
5. Navigate using semantic/UI-automator evidence where possible. Use coordinate taps only after inspecting the current screen, and keep coordinates local.
6. Capture every matrix row with a descriptive name:

before-<surface>-<state>-<width>-<theme>.png

Use adb exec-out screencap -p so the PNG is written directly to the artifact directory. Inspect every screenshot immediately; a successful command is not proof that the intended screen was visible.