create-mobile-pr

What this skill does

# Create GitHub Pull Request

## Overview

Open a draft GitHub pull request with a JIRA-prefixed title, a description generated from the repo's PR template, and the current user as assignee. The PR is opened as a draft so the user can review on GitHub and mark it ready for review (and request reviewers) themselves. Release notes and QA notes go into `RELEASES.md`, not the PR description.

## When to Use

- User asks to create, open, or submit a pull request
- User says "make a PR" or "open a PR"
- Implementation is done and user wants to push and open a PR

## Process

### 1. Gather Context

Run these in parallel:

- `git branch --show-current` -- current branch name
- `git log master..HEAD --oneline` -- commits on the branch
- `git log master..HEAD` -- full commit messages (used as fallback for ticket extraction)
- `git diff master...HEAD --stat` -- changed files summary
- `git diff master...HEAD` -- full diff
- `cat .github/PULL_REQUEST_TEMPLATE.md` -- the PR template
- `cat RELEASES.md` -- the current release file (used to find the active release section for Release Notes and QA Notes)

Also check: did the user provide additional notes, context, or verification steps? Incorporate them into the appropriate sections.

### 2. Extract Ticket Number and Build Title

Extract the JIRA ticket number (pattern `[A-Z]+-[0-9]+`) from:

1. **Branch name first** -- the leading prefix before the first description segment
2. **Commit messages as fallback** -- if the branch name has no ticket, scan commit messages for the pattern

Examples:
- `CCCT-1929-refetch-sso-token` -> `CCCT-1929`
- `CI-609-personalid-phone-fragment-crash` -> `CI-609`
- `ENG-42-add-new-feature` -> `ENG-42`

If no ticket number is found anywhere, ask the user for it.

**Build the PR title:** `TICKET-NUMBER Short Concise Description`

- The description after the ticket number should summarize the PR's purpose in a few words
- Derive it from the commits and diff -- do not just reuse the branch name slug
- Keep the total title under 72 characters
- **Capitalize the first letter of every word** in the description portion (including short words like `on`, `to`, `for`, `the`, `a`, `an`, etc.)
- Preserve the existing casing of acronyms, identifiers, and ticket numbers (e.g. `SSO`, `URL`, `iOS`, `CCCT-1929`)
- Example: `CCCT-1929 Re-Fetch SSO Token On Invalid Token Error`

### 3. Ask the User About Their Personal Testing

The Safety Story section depends on what the *author* actually did to verify the change. Before generating the PR description, check whether the user has already described their personal testing (e.g. in earlier turns of this conversation, or in additional notes they provided).

If they have not, ask explicitly -- for example:

> What did you personally do to test these changes? (e.g. ran the app on a device, exercised a specific flow, ran a particular test suite, reviewed the diff only, etc.)

Wait for their answer before proceeding. Do not invent or assume testing the user did not describe. If they say they did not test it locally, record that honestly in the Safety Story.

### 4. Update RELEASES.md (Release Notes and QA Notes)

Release notes and QA notes belong in `RELEASES.md`, not in the PR description. Each is its own decision, its own draft-for-approval, and its own commit so the changes are easy to review.

Open `RELEASES.md` and find the **most recent release section** (the topmost `## CommCare X.YZ` heading).

**Never include JIRA ticket numbers in `RELEASES.md` entries** — not in Release Notes, not in QA Notes. No `CCCT-1234`-style identifiers, no ticket links, no parenthetical ticket references in the bullet text. The ticket lives in the PR title and description.

#### 4a. Release Notes (skip if not required)

The `### Release Notes` subsection is published publicly (Play Store, GitHub Releases, CommCare Forums), plus an `#### Internal Release Notes` block for project-specific notes. Add an entry **only if** the change is observable by end users or relevant projects:

- `#### What's New` — new user-visible features or capabilities
- `#### Important Bug Fixes` — user-visible bug fixes worth surfacing
- `#### Internal Release Notes` — changes relevant only to specific projects

**Skip this step entirely** when the change has no user-visible impact — refactors, dev-tooling, internal-only logic, code cleanup, test-only changes. If unsure, ask the user whether a release note is needed.

Write entries as short, user-facing descriptions of *what changed* from the user's perspective. No ticket numbers. No implementation detail.

Show the user a draft of the release note bullet(s) — which subsection they'll go under and the exact bullet text, verbatim — and wait for their response. Do **not** run `git add` or `git commit` until the user has approved the draft. Once approved, stage and commit the change on the current branch with a short message such as `Add release notes for TICKET-NUMBER`. Use a separate commit so it is easy to review.

#### 4b. QA Notes (skip if not required)

Append bullets to `### QA Notes` describing what QA should manually verify.

**Write QA notes for testers with phone access only.** Assume QA's only tooling is:

- A build of the app installed on their phone
- The app's normal UI and any user-facing surfaces (settings, forms, Connect, PersonalID, etc.)
- Their own test accounts / test projects
- Server-side admin views they would normally use (e.g. HQ), if relevant to the feature

Do **not** write steps that require Android Studio, Logcat, adb, unit/instrumentation tests, internal storage inspection, or any developer-only tooling. QA notes read as user-level actions and observable outcomes: "do X in the app, expect Y." If a regression cannot be observed without developer tools, say so and rely on automated coverage instead of writing an unrunnable QA step.

**Be ruthlessly concise.** QA notes are a checklist of the most important things to verify, not a tutorial.

- Aim for the **fewest bullets possible** — often 1-3. If you are writing more than 5, you are almost certainly being too verbose.
- **Do not write step-by-step instructions.** QA knows how to use the app. "Verify the login screen still loads" is enough; do not enumerate "open the app, tap login, enter credentials, tap submit."
- **Omit anything obvious or implied.** If a flow has an obvious happy path, do not spell it out. Call out only the non-obvious risks, edge cases, or behavior changes a tester would not think to check.
- **One bullet per distinct thing to verify.** Do not split a single check across multiple bullets.
- Prefer "verify X still works after Y" or "confirm Z behaves as expected" framing over numbered procedures.

**Skip this step** when there is nothing for QA to manually verify (e.g. pure refactor with automated coverage, dev-tooling change). If unsure, ask the user.

No ticket numbers in QA bullets.

Show the user a draft of the QA bullet(s) — the release section heading they'll go under (e.g. `## CommCare 2.56`) and the exact bullet text, verbatim — and wait for their response. Do **not** run `git add` or `git commit` until the user has approved the draft. Once approved, stage and commit the change on the current branch with a short message such as `Add QA notes for TICKET-NUMBER`. Use a separate commit so it is easy to review.

### 5. Generate PR Description from the Template

**Do not show the PR description to the user for approval before opening the PR.** The PR is opened as a draft, so the user will review and edit the description on GitHub. Asking them to review a long markdown block in the terminal duplicates that review and wastes their time. The only thing that requires explicit approval before the PR is created is `RELEASES.md` changes (step 4), because those get committed to the repo. The PR title and description do not.

Read `.github/PULL_REQUEST_TEMPLATE.md` and fill out each section per the instructions in its HTML comments. Replace the HTML comments with