---
name: gh-create-pr
description: Create or update GitHub pull requests using the repository-required workflow and template compliance. Use when asked to create/open/update a PR so the assistant reads `.github/pull_request_template.md`, fills every template section, preserves markdown structure exactly, and marks missing data as N/A or None instead of skipping sections.
---

# GitHub PR Creation

## Stack tooling

This repository ships `.agents/skills/gh-stack/SKILL.md` as a public project skill; developers do not install the agent skill separately. Read it before operating on stacked branches or PRs. Agents that consume `.agents/skills/` discover it directly. If a Claude checkout is missing `.claude/skills/gh-stack`, run `pnpm skills:sync` followed by `pnpm skills:check`; do not download a separate global copy.

Before the first `gh stack` command in a task, verify the GitHub CLI and install the official extension if it is missing:

```bash
command -v gh >/dev/null 2>&1 || {
  echo "GitHub CLI is required: https://cli.github.com/" >&2
  exit 1
}
gh auth status
if ! gh stack --help >/dev/null 2>&1; then
  gh extension install github/gh-stack
fi
gh stack --help >/dev/null
```

Stop if authentication, installation, or the final verification fails. Do not infer a stack with ad hoc Git commands. For human-authored Cherry PRs, use `gh stack push`, create each compliant PR through this skill from bottom to top, then link the existing PRs with `gh stack link`; `gh stack submit --auto` creates PRs outside the template-compliant body flow and must not bypass this workflow.

## Workflow

1. Read `.github/pull_request_template.md` before drafting the PR body.
2. Collect PR context from the current branch (base/head, scope, linked issues, testing status, breaking changes, release note content). Resolve the live base and run `pnpm change:scope --base <verified-base-ref>`; do not infer scope from the latest commit alone.
3. Read `.agents/notes/README.md` and classify the change:
   - Fill `Agent Note` with the repository path, or `N/A — <reason>` for a local/mechanical change.
   - For a Spec PR, fill `Spec PR: This PR` and list every AC.
   - For an implementation layer, link the Spec PR and list only the AC IDs covered by this layer. Verify an `APPROVED` review whose `commit_id` equals the current Spec head; a stale approval does not authorize implementation.
   - For a direct bug fix with durable rationale, link its implemented `bug-fix` note and use `Spec PR: N/A`.
   - Automation-authored PRs (repository workflows and Dependabot) are exempt from these metadata fields. Do not make their bodies imitate a human-authored PR.
4. For an implementation PR, complete the stack tooling preflight, then run `gh stack view --json`. If it exits 2, follow the `gh-stack` skill's remote-discovery procedure; missing local metadata does not prove the PR is standalone. Inspect every downstack implementation PR and aggregate only ACs backed by actual verification. Keep the note proposed on intermediate layers. If the current PR is the final layer and cumulative evidence covers the complete approved Spec, move the bilingual triplet to `implemented/` and run `pnpm agent-notes:check-transition --base <verified-spec-ref>` before publishing.
5. Fill `Verification` with commands and scenarios actually run. Never present a planned, pending, skipped, or CI-only check as passed.
6. Check if the current branch has been pushed to remote. If not, push it first:
   - Default remote is `origin`, but ask the user if they want to use a different remote.
   ```bash
   git push -u <remote> <head-branch>
   ```
7. Determine the base branch:
   - Inspect the head branch before applying any default. If the head is `release/v<version>`, stop: never open a pull request from a release branch, especially not to `main`. Put an isolated fix on a topic branch and target the release branch, or let Post Release create the metadata sync branch.
   - Before defaulting an arbitrary topic branch to `main`, inspect its merge base and upstream. A product-code fix that started from `release/v<version>` must stop and be recreated from `main` as a hotfix; only a release-only repair or explicit backport recovery topic may target that exact release branch.
   - A `backport/v<version>/pr-<number>` head must target the matching `release/v<version>` base and its body must contain `<!-- release-backport-source-pr: <number> -->` on its own line for the exact source hotfix PR. A `release-sync/v<version>` head must target `main`, use the exact title `chore(release): sync v<version> metadata`, retain the `release-metadata-boundary: v<version>` body marker, and be squash-merged.
   - For official repo(CherryHQ/cherry-studio) as `origin`: default base is `main` from `origin`, but allow the user to explicitly indicate a base branch.
   - `main` is the active development line, including hotfix PRs. Do not target an old maintenance branch unless the user explicitly requests it.
   - Only classify a PR as a release hotfix when the user explicitly says it must be included in the active draft release. Use the title `hotfix: <description>` or `hotfix(<kebab-case-scope>): <description>` with a lowercase alphanumeric kebab-case scope, exactly one space after the colon, and a non-empty description. The title grammar synchronizes the `hotfix` label automatically. Merging opens a separate backport PR only when exactly one draft semantic-version release has a matching active `release/v<version>` branch; otherwise automation stops without guessing a target.
   - If the hotfix is user-facing, provide one release-note line in each language so automation can update the active draft and stable release history. Put this exact structure inside the template's existing `release-note` fence; do not include bullet prefixes:
     ```text
     <!--LANG:en-->
     [Component] English description.
     <!--LANG:zh-CN-->
     [组件] 中文说明。
     <!--LANG:END-->
     ```
   - If the hotfix has no user-facing release note, keep `NONE` in the template's `release-note` fence. The code is still backported, but release metadata is unchanged. A provided bilingual block must satisfy the exact structure above.
   - For fork repo as `origin`: check available remotes with `git remote -v`, default base may be `upstream/main` or another remote. Always assume that user wants to merge head to CherryHQ/cherry-studio/main, unless the user explicitly indicates a base branch.
   - Ask the user to confirm the base branch if it's not the default.
8. Create a temp file and write the PR body using a single Bash heredoc
   (avoids `mktemp` + `Write` tool path-mismatch on Windows):
   ```bash
   pr_body_file="/tmp/gh-pr-body-$(date +%s).md"
   cat > "$pr_body_file" <<'EOF'
   ...filled template body...
   EOF
   ```
   Fill content using the template structure exactly (keep section order,
   headings, checkbox formatting). If not applicable, write `N/A` or `None`.
9. Inspect the temp file content via Bash `cat "$pr_body_file"` (the `Read`
   tool can fail on `/tmp/...` paths on Windows). If the user requests a preview
   or confirmation, show the full body and follow that request; otherwise,
   proceed with the authorized PR creation.
10. Create the PR, adding `--draft` when the user requests a draft:
   ```bash
   gh pr create --base <base> --head <head> --title "<title>" --body-file "$pr_body_file"
   ```
   For a release hotfix, use an exact classifier-compatible title so the workflow synchronizes the label and separately validates any provided bilingual note:
   ```bash
   gh pr create --base main --head <head> --title "hotfix: <description>" --body-file "$pr_body_file"
   ```
   After creation, verify that the classifier added `hotfix`; if it did not, fix the title instead of adding the label manually. Also fix any malformed optional release-note block reported by the workflow.
11. Clean up the temp file: `rm -f "$pr_body_file"`
12. Report the created PR URL and summarize title/base/head, Agent Note/Spec, AC coverage, actual verification, and any required follow-up.

## Constraints

- Never skip template sections.
- Never rewrite the template format.
- Keep content concise and specific to the current change set.
- PR title and body must be written in English.
- Never use a `hotfix` title or label for an ordinary bug fix. It opts the PR into an automatic backport PR after merge when one matching draft release is active.
- A release hotfix may use `NONE` when it has no user-facing release note. Never provide a partial, single-language, or otherwise malformed bilingual note; the backport workflow fails closed on malformed content.
- Never default a `release/v<version>` head to `main`; a release branch is not a pull request source branch.
- Never publish an implementation PR as ready when its current Spec head lacks an exact-head Approval. A Spec may remain unmerged and serve as the stack base.
- Every human-authored PR fills `Agent Note`, `Spec PR`, and `Acceptance criteria`; `N/A` requires a concise reason. Automation-authored PRs (repository workflows and Dependabot) are exempt from this metadata requirement.
- **Release note & Documentation checkbox** — both are driven by whether the change is **user-facing**. Use the table below:

  | Change type | Release note | Docs `[x]` |
  |---|---|---|
  | New user-facing feature / setting / UI | Describe the change | ✅ |
  | Bug fix visible to users | Describe the fix | ✅ if behavior changed |
  | Behavior change / default value change | Describe + `action required` | ✅ |
  | Security fix in a user-facing dependency | Describe the fix | ✅ if usage changed |
  | CI / GitHub Actions changes | `NONE` | ❌ |
  | Internal refactoring (user cannot tell) | `NONE` | ❌ |
  | Dev / build tooling changes | `NONE` | ❌ |
  | Dev-only dependency bump | `NONE` | ❌ |
  | Test-only / code style changes | `NONE` | ❌ |

## Command Pattern

```bash
# read template
cat .github/pull_request_template.md

# prepare and inspect the PR body
pr_body_file="/tmp/gh-pr-body-$(date +%s).md"
cat > "$pr_body_file" <<'EOF'
...filled template body...
EOF
cat "$pr_body_file"

# create the authorized PR; add --draft when requested
gh pr create --base <base> --head <head> --title "<title>" --body-file "$pr_body_file"
rm -f "$pr_body_file"
```