Prepare PR

Prepare a PokeTokenBar PR

Use this repository's title and template rules even when a personal PR skill is also active. The shared instructions live here; Claude Code discovers them via .claude/skills/prepare-pr, and Codex via .agents/skills/prepare-pr. Run commands from the repository root. Paths below are relative to that root.

Title and body

Read CONTRIBUTING.md and .github/PULL_REQUEST_TEMPLATE.md before preparing or updating the PR. Resolve the actual target repository and base branch, then read the complete base...HEAD diff and base..HEAD commit range. Do not summarize only the last commit or use unrelated work already on the branch as new work.

Write the title and body in English. Use a Conventional Commits title such as fix(home): retain idle usage history or docs: require UI images in PRs. Choose a type and optional scope that describe the final change; do not copy a ticket prefix or a personal skill's title convention over repository rules.

Start the body from the current template. Fill Summary, select the actual Type of change, and retain the template's checklist. Check an item only when the performed work supports it; leave tests unchecked if they were not run or added, and explain why when relevant. Report actual validation and limitations. Keep the body in a UTF-8 file and pass it with gh ... --body-file.

Mandatory UI images

Decide whether the full diff changes visible UI. Inspect changes outside Sources/PokeTokenBar/UI/ too: data, localization, resources, and settings can change what users see. A change inside that directory triggers the local image check; an outside change with visible effects needs --ui-changes. For changes inside the UI directory that have no visible effect (such as comments or an equivalent refactor), inspect the full diff and use --no-ui-changes '<reason>'. Never use this declaration to excuse missing images for a visible change.

For every affected screen or state, embed images directly in UI changes:

• Existing screens: before and after images of the relevant state.
• New screens: explain that no previous screen exists and embed the new screen.
• Removed screens: show the previous screen and the resulting replacement or parent screen after removal.

If images are not ready, create them yourself as part of preparing the PR. Reuse accurate existing images or capture the app; when capture is impractical, render the relevant UI locally or draw it based on the actual change. Inspect the result and attach it. Do not stop, ask the user to provide images, or request separate permission merely because no image already exists. An authorized PR creation/update includes producing and attaching its required UI images; a local title/body preparation request keeps the generated images local too.

Actual app screenshots, local renders of production UI, and images drawn to illustrate the changed UI are all accepted. Label them App screenshot, Sample-data render, or Illustration / mockup as appropriate. Reuse existing images only if they accurately depict the relevant version and state. Show the change, not an unrelated app overview. Keep comparable data, language, theme, and dimensions where practical. Inspect the generated images before using them; an illustration demonstrates the design, not proof that the app was tested.

Existing local render harnesses can help when the running app is difficult to capture. Create a temporary output directory, then use the relevant harness:

PTB_SCREENSHOT_DIR=<existing-dir> swift test --filter ScreenshotGenTests
PTB_ZERO_USAGE_SCREENSHOT_DIR=<existing-dir> swift test --filter ZeroUsageHomeRenderingTests
PTB_COLLECTION_SCREENSHOT_DIR=<existing-dir> swift test --filter CollectionReadabilityRenderingTests

Read the selected harness before using its output. Some AppKit controls and scroll views do not render faithfully in tests; capture the running app when those details are the change being demonstrated. Capture/render the base and head separately when no accurate before image exists; do not reset the user's working tree to obtain a before image. Do not regenerate release screenshots merely to prepare a PR.