create-pr

name	create-pr
description	Create a draft GitHub PR from the current feature branch with a convention-aware title and body. Use when the user asks to create, prepare, draft, or open a pull request.

Create PR

Create a draft GitHub PR from the current branch with a convention-aware title and body.

This skill has remote side effects: it may push the current branch and create a PR on GitHub. Do not push or create the PR until the user explicitly approves the PR description and confirms creation.

Inputs

Parse any PR options from the user's request before gathering context:

• --base <branch>: use this branch as the PR base.
• --branch <branch>: alias for --base <branch>.
• --title <title>: include this title as the first title suggestion.

If the user provides an unknown flag or a flag missing a required value, report valid usage and stop.

User Questions

When user input is needed, ask in plain chat text with concise numbered options. This keeps the skill compatible with Codex and other chat-only runners.

Ask the user when:

• Selecting or confirming the base branch.
• Uncommitted changes exist and the user must decide whether to continue.
• The generated PR title needs user selection or editing.
• The generated PR description needs explicit approval.
• The final push and PR creation needs confirmation.

Question rules:

• Do not depend on an interactive selector UI.
• Do not say that an interactive selector cannot be rendered.
• Put the recommended option first when there is one.
• Let the user answer with a number, exact option text, or free-form replacement.

Step 1: Select and Validate Base Branch

Confirm the working tree is on a feature branch and has commits to submit.

1. Get the current branch:

   git branch --show-current
   

2. Resolve the base branch explicitly:
   • List local branches:

     git branch --format='%(refname:short)'
     

   • If --base or --branch was provided, include that value as the first option.
   • Otherwise, if a likely default branch is known from gh repo view --json defaultBranchRef -q .defaultBranchRef.name, put it first.
   • Ask the user Which base branch should I create the PR against? in plain chat text.
   • Show branch choices as a numbered list, with the recommended branch first.
   • If the user provides free-form input, treat it as the base branch.
3. If the current branch is the base branch, output Nothing to submit -- current branch is the base branch. and stop.
4. Fetch the base branch:

   git fetch origin <base> --quiet
   

5. Count commits ahead:

   git rev-list --count origin/<base>..HEAD
   

6. Check local changes:

   git status --short
   

If there are zero commits ahead and no uncommitted changes, output Nothing to submit -- no commits ahead of base branch. and stop.

If there are uncommitted changes, tell the user that uncommitted changes will not be included in the PR. Ask whether to continue using a plain-text yes/no question. If the user declines, stop.

Step 2: Learn PR Conventions

Examine recent merged PRs to infer the repository's PR style:

gh pr list --state merged --limit 5 --json title,body,number

Analyze the returned PRs for:

• Title format: prefixes such as feat:, fix:, ticket IDs, capitalization, and length.
• Body style: how much context they include, when they use headings, how they link issues, and how casual or formal the writing is.
• Code links: prefer full GitHub blob/<sha>/path#Lx-Ly links for important ranges. GitHub renders linked code snippets in the PR, which makes reviews easier. Example: https://github.com/a4s-lab/spreadsheet/blob/44aa272358fa048cfe2c52b0c6dccdb182513bc2/crates/workbook/src/operation.rs#L357-L370.

If no merged PRs exist or gh pr list fails, use a concise body with only the sections that help this PR.

Step 3: Gather Diff and Commit History

Collect enough context to write the PR:

git log --oneline origin/<base>..HEAD
git log --format="%h %s%n%n%b" origin/<base>..HEAD
git diff --stat origin/<base>...HEAD
git diff origin/<base>...HEAD

For large diffs, focus on git diff --stat and read changed files selectively. Do not paste long raw diffs into the final response.

Step 4: Generate and Confirm PR Title

Generate 2-3 title suggestions from the conventions and branch diff, then ask the user to choose or edit the title.

Title rules:

• Match the repository's recent PR convention.
• If --title was provided, include it as the first suggestion.
• If no convention is detected, use a concise imperative title.
• Keep the title under 72 characters.

Ask in plain chat text:

Which PR title should I use? Reply with a number, or type an edited title.

1. <suggested title>
2. <suggested title>
3. <suggested title>

If the user replies with a number, use that suggestion. If the user types free-form input, use that as the final title.

Step 5: Generate and Approve PR Description

Generate a PR description that fits this repository and this change. Choose the smallest useful structure based on recent merged PRs, the commit history, and the diff.

Recent a4s-lab/spreadsheet PRs are good examples: short opening context, a few targeted links, and extra explanation only when the implementation is non-obvious.

Writing rules:

• Start high level: what this PR enables or fixes, not how every file changed.
• Keep it concise. Reviewers dislike text-heavy descriptions.
• Use markdown for scanability: short paragraphs, bullets, and headings only when they help.
• No strict template. Decide section breaks per PR. A forced Summary / Changes / Tests shape can look generated.
• Do not list every changed file.
• Link important code ranges with full GitHub URLs so GitHub shows code snippets inline.
• Explain complex or surprising implementation choices, but stay out of low-level narration.
• Casual fragments are fine in bullets. They do not all need to be complete sentences.
• Mention issue links, validation, screenshots, rollout notes, breaking changes, or follow-ups only when useful.

A good description may be as small as:

This PR implements `Operation::SetCellFormats` and `Operation::ClearCellFormats`.

https://github.com/a4s-lab/spreadsheet/blob/44aa272358fa048cfe2c52b0c6dccdb182513bc2/crates/workbook/src/operation.rs#L357-L370

The old `FormatStore` had behavior that did not match the spreadsheet model, so this redesign moves the store under `sheet/stores` and keeps changed ranges sparse for reviewers to inspect.

Please refer to #143 for the background.

After generating the description, show the full proposed description and ask for explicit approval in plain chat text:

Use this PR description?

1. Approve description
2. Regenerate description

Or type requested edits.

If the user types requested edits, revise the description once using those edits and ask for approval again. Do not create the PR until the user approves the final description.

Step 6: Confirm and Create PR

Before any remote side effect, show:

• Base branch
• Current branch
• Draft mode: always enabled
• Final title
• Approved description

Ask for confirmation in plain chat text. If the user does not confirm, stop without pushing or creating a PR.

After confirmation:

1. Push the current branch:

   git push -u origin <current-branch>
   

2. Create the draft PR:

   gh pr create --draft --base <base-branch> --title "<title>" --body "$(cat <<'EOF'
   <body>
   EOF
   )"
   

3. Output the PR URL returned by gh pr create.

If git push or gh pr create fails, report the exact failure and stop.