review-pr-ui-screenshots

name	review-pr-ui-screenshots
description	Download and review Easydict pull request CI screenshot artifacts from GitHub Actions using gh, then verify whether each screenshot matches its filename and artifact directory. Use when asked to review PR UI screenshots, CI visual artifacts, ui-screenshots artifacts, baseline candidates, visual diffs, or failure snapshots generated by the UI Automation workflow.

Review PR UI Screenshots

Goal

Fetch the relevant GitHub Actions UI screenshot artifacts for a PR, then review them like local UI artifacts: file and directory names describe the expected UI state, and mismatches should be reported first.

Resolve PR And Run

Use gh from the repository root. Start by confirming authentication:

gh auth status

If the user gave a PR number, use it. Otherwise resolve the current branch PR:

$pr = gh pr view --json number,headRefName,headRefOid,url | ConvertFrom-Json

Find the latest matching UI Automation workflow run for the PR head commit:

$runs = gh run list `
  --workflow ui-automation.yml `
  --branch $pr.headRefName `
  --event pull_request `
  --limit 20 `
  --json databaseId,status,conclusion,headSha,createdAt,displayTitle,url |
  ConvertFrom-Json

$run = $runs |
  Where-Object { $_.headSha -eq $pr.headRefOid -and $_.status -eq "completed" } |
  Sort-Object createdAt -Descending |
  Select-Object -First 1

If no completed run matches, list the latest runs and explain whether the workflow is still running, skipped, failed before artifacts, or expired.

Download Screenshot Artifacts

Download into a unique, meaningful local directory:

$dest = "artifacts/pr-ui-screenshots/pr-$($pr.number)/run-$($run.databaseId)"
New-Item -ItemType Directory -Force -Path $dest | Out-Null

gh run download $run.databaseId --pattern "ui-screenshots-*" --dir $dest
gh run download $run.databaseId --pattern "baseline-candidates-*" --dir $dest
gh run download $run.databaseId --pattern "theme-contrast-regression-screenshots-*" --dir $dest

Artifact names should remain visible in the folder tree, for example:

artifacts/pr-ui-screenshots/pr-123/run-456/ui-screenshots-ocr-overlay/
artifacts/pr-ui-screenshots/pr-123/run-456/ui-screenshots-core-settings-darkmode/
artifacts/pr-ui-screenshots/pr-123/run-456/baseline-candidates-pop-button/

If gh run download reports no matching artifacts, inspect the run status and artifact list:

gh run view $run.databaseId --json status,conclusion,url
gh run view $run.databaseId --log-failed

Review Workflow

Use the local screenshot review workflow on the downloaded root. Review priority is:

1. visual-diffs/ and *_diff.png
2. baseline-candidates-* artifacts and baseline-candidates/ directories
3. diagnostic files containing not_found, failed, failure, missing, error, or navigation_failed
4. regular ui-screenshots-* artifacts

Inspect individual images, not just generated galleries. The artifact name should help set expectations:

• ui-screenshots-pop-button: PopButton settings, selection, popup visibility, and mini-window launch states.
• ui-screenshots-mini-phonetic-dictionary: mini window long text, phonetic display, dictionary WebView/fallback states.
• ui-screenshots-core-settings-darkmode: main window, translation, settings scrolling, window lifecycle, dark mode states.
• ui-screenshots-theme-contrast: theme matrix and light/dark contrast states.
• ui-screenshots-ocr-overlay: OCR hotkey, overlay, cancel/dismiss, and silent OCR states.
• ui-screenshots-long-document: long document mode controls and translation workflow states.

For each screenshot, compare the visible UI to the filename semantics. Examples:

• *_before_* should show pre-action state.
• *_after_translate should show translation output or an expected result state.
• *_overlay_active should show the capture overlay.
• *_not_found or *_failed should be treated as diagnostic evidence, not a successful UI state.
• *_dark_* and *_light_* should match the named palette.

Report Format

Lead with findings. For each finding include:

• severity: High, Medium, or Low
• artifact and screenshot path
• expected state inferred from artifact/file name
• observed state
• why this matters for PR review
• suggested next check or fix

Then include:

• PR URL, run URL, run id, conclusion, and head SHA
• downloaded artifact root
• reviewed artifact groups
• any artifacts that were missing, expired, or not reviewed

If no mismatches are found, say so explicitly and state the review coverage.