Create Pull Request

Push branch and create a PR with a concise, issue-linked description.

IMPORTANT: This skill MUST be used for ALL pull request creation — even when the user says "create pr" without

/pr

. Never create a PR without following these steps.

Current Branch Context

• Branch: !

  git branch --show-current

• Commits: !

  git log main..HEAD --oneline 2>/dev/null

• Changed files: !

  git diff main..HEAD --stat 2>/dev/null

Arguments

• $ARGUMENTS

  - Issue reference (optional, e.g.,

  #42

  or

  42

  ). If provided, the PR will be linked to this issue.

Instructions

1. Review the branch context above — the commits and changed files are already loaded.

2. MANDATORY: Update CHANGELOG.md — Read

   CHANGELOG.md

   and check the

   ## Unreleased

   section. If the changes from this branch are NOT already listed there, you MUST update it before proceeding. Do NOT skip this step. Do NOT proceed to push without verifying.

• Add entries under the appropriate subsection (

  ### Added

  ,

  ### Changed

  ,

  ### Fixed

  , etc.)
• Reference issue numbers where applicable (e.g.,

  (Issue #123)

  )
• Commit the update:

  git add CHANGELOG.md && git commit -m "docs: update changelog"
  

3. Push branch:

git push -u origin HEAD

• The

  pre-commit

  hook runs tests, shellcheck, and linting automatically on commit. Ensure all checks passed before pushing.
• If push fails, read the output, fix the issue, commit the fix, and retry. Do NOT use

  --no-verify

  to bypass.

4. Generate PR title:

• If

  $ARGUMENTS

  contains an issue number, fetch the issue title:

  gh issue view <number> --json title -q '.title'
  

• PR title format:

  <type>(<scope>): <short description>

  (conventional commit style, under 70 chars)
• Derive the type from the branch prefix (

  feat/

  → feat,

  fix/

  → fix,

  docs/

  → docs)

5. Create PR using the template from

   .github/PULL_REQUEST_TEMPLATE.md

   :

gh pr create --title "<title>" --assignee @me --label "<label>" --body "$(cat <<'EOF'
## 🤔 Background

Related #<issue-number>

<1-2 sentences: motivation and context for the changes>

## 💡 Changes

- <bullet 1: what changed and why>
- <bullet 2>
- <bullet 3> (optional)
- <bullet 4> (optional)
EOF
)"

MANDATORY: Always follow the PR template structure (

## 🤔 Background

+

## 💡 Changes

). Never use a different format.

Assignee: Always assign to

@me

(the PR creator).

Labels: Add the single most relevant label based on the branch prefix and change context:

• bug

  — branch starts with

  fix/

  and addresses a defect

• enhancement

  — branch starts with

  feat/

  or adds new functionality

• documentation

  — branch starts with

  docs/

  or only changes docs

• refactor

  — code restructuring with no behavior change

• ui

  — visual/frontend-only changes

• investigation

  — spikes, research, or exploratory work

Body guidelines:

• Background: Link the issue with

  Related #<number>

  , then 1-2 sentences of context. NEVER use

  Closes

  or

  Fixes

  .
• Changes: 2-4 short bullet points. Focus on what and why, not implementation details.
• No file lists, no class names, no code snippets in the body.
• Keep the entire body under 15 lines.

6. Move issue to "In Review" in GitHub Project (if issue number provided):

# Read project config from .claude/github-project.json
ITEM_ID=$(gh project item-list PROJECT_NUMBER --owner OWNER --format json \
  | jq -r '.items[] | select(.content.number == ISSUE_NUMBER) | .id')

gh project item-edit \
  --id "$ITEM_ID" \
  --project-id "PROJECT_ID" \
  --field-id "STATUS_FIELD_ID" \
  --single-select-option-id "IN_REVIEW_OPTION_ID"

Note: Requires

project

scope. Run

gh auth refresh -s project

if needed.

7. Report the PR URL to the user.

Example Usage

/pr
/pr #42
/pr 15