gh-pr

Push a development branch and create or update a GitHub pull request. Before opening the PR, optionally update project documentation (README, docs directory, planning files) so the PR includes all relevant changes. This skill is the natural next step after gh-dev.

Step 1: Verify prerequisites

gh auth status

If gh is not installed or not authenticated, stop and guide the user (see Gotchas).

Then confirm the repo state:

# Current branch
git branch --show-current

# Commits ahead of default branch
git log --oneline origin/main..HEAD 2>/dev/null || git log --oneline origin/master..HEAD 2>/dev/null

# Uncommitted changes
git status --porcelain

If the current branch is main or master, stop and tell the user to check out a feature branch first.

If there are uncommitted changes, inform the user and ask how to proceed — commit them, stash them, or abort.

If there are no commits ahead of the default branch, tell the user there is nothing to open a PR for and stop.

Store the current branch name as BRANCH_NAME.

Determine base branch

Detect whether the repository uses a development branch:

git branch -r | grep -E 'origin/(dev|develop)$'

If dev or develop exists, set BASE_BRANCH to that branch. Show the target to the user:

This PR will target dev. Correct?

Use AskUserQuestion to confirm. Do not proceed until the user confirms the base branch. If the user wants a different base, use the branch they specify.

If neither dev nor develop exists, default to main (or master if main does not exist). Still confirm with the user before proceeding.

Step 2: Detect the linked issue

Extract the issue number from the branch name. If the branch follows the issues/N convention:

echo "$BRANCH_NAME" | grep -oE 'issues/[0-9]+' | grep -oE '[0-9]+'

If a number is found, fetch the issue details:

gh issue view ISSUE_NUMBER --json title,body,labels,state

Store as ISSUE_NUMBER, ISSUE_TITLE, and ISSUE_LABELS. The labels are used in Step 9 to determine the PR type.

If no issue number can be extracted, ask the user whether this PR is linked to an issue. If not, proceed without one.

Step 3: Determine language

Decide which language to use for the PR body. Check in this order:

1. If the user explicitly states a language preference, use that.
2. Read CLAUDE.md in the project root. If it is written in Traditional Chinese or contains a language directive, use Traditional Chinese.
3. Default to English.

Store as PR_LANG — either en or zh-TW.

Step 4: Gather project conventions

git log --oneline -20
cat CLAUDE.md 2>/dev/null || true
cat CONTRIBUTING.md 2>/dev/null || cat .github/CONTRIBUTING.md 2>/dev/null || true

Infer the commit convention (prefix style, tense, scope, capitalization) the same way gh-dev does. Store as COMMIT_CONVENTION.

Step 5: Update README (optional)

Check whether the readme skill is available in the current session's available skills list.

If available:

1. Review the changes on this branch to determine whether the README needs updating (new features, changed APIs, modified configuration, new dependencies).
2. If updates are warranted, invoke the readme skill using the Skill tool.
3. After the skill completes, stage and commit the README changes following COMMIT_CONVENTION:

git add README.md
git commit -m "docs: update README to reflect branch changes"

Adapt the commit message prefix to match COMMIT_CONVENTION. No Co-Authored-By or attribution.

If the readme skill is not available, skip this step silently.

Step 6: Update docs directory (optional)

ls -d doc/ docs/ 2>/dev/null

If doc/ or docs/ exists:

1. Review the diff (git diff main..HEAD or equivalent) to identify whether any documented APIs, features, workflows, or configuration changed.
2. Read the relevant documentation files.
3. If updates are needed, edit the affected files.
4. Stage and commit each documentation update:

git add docs/affected-file.md
git commit -m "docs: update affected-file to reflect new behavior"

Adapt the commit message prefix to match COMMIT_CONVENTION. No Co-Authored-By or attribution.

If no doc/ or docs/ directory exists, skip this step.

Step 7: Update project tracking (optional)

Check whether the planning-with-files skill is available in the current session's available skills list.

If available:

1. Invoke the planning-with-files skill using the Skill tool to update project plan files with the completed work from this branch.
2. Stage and commit any changes to planning files:

git add task_plan.md progress.md findings.md
git diff --cached --stat
git commit -m "docs: update project tracking for completed work"

Adapt the commit message prefix to match COMMIT_CONVENTION. No Co-Authored-By or attribution.

If the planning-with-files skill is not available, skip this step silently.

Step 8: Push the branch

git push -u origin "$BRANCH_NAME"

If the push fails due to diverged history, inform the user and ask how to proceed. Never force-push without explicit user consent.

Step 9: Create or update the PR

9a: Check for existing PR

gh pr view "$BRANCH_NAME" --json number,title,state,url 2>/dev/null

If a PR exists and is open, proceed to update flow (Step 9f). Otherwise, create a new PR.

9b: Determine PR type

Map the PR to one of six types using the issue labels from Step 2:

• bug: labels contain "bug"
• feat: labels contain "enhancement", "feature", or no label but issue title starts with "feat:"
• refactor: labels contain "refactor" or issue title starts with "refactor:"
• doc: labels contain "documentation" or issue title starts with "doc:"
• perf: labels contain "performance" or issue title starts with "perf:"
• security: labels contain "security"

If the type cannot be determined from labels, infer from the commit history or ask the user.

Store as PR_TYPE.

9c: Read the template

Read the appropriate template from <skill-path>/templates/{PR_TYPE}.md (or {PR_TYPE}-zh-TW.md if PR_LANG is zh-TW).

9d: Fill the template

Fill every section using information from:

git log --oneline origin/main..HEAD
git diff --stat origin/main..HEAD

Plus the issue details from Step 2. Replace placeholder guidance with concrete details — file paths, function names, specific changes. If ISSUE_NUMBER exists, include Closes #ISSUE_NUMBER in the Summary section.

Build the PR title following COMMIT_CONVENTION. Keep under 80 characters.

9e: Present for review and create

Show the user the complete PR title and body in a fenced block. Use AskUserQuestion to ask for approval or changes. After approval:

gh pr create \
  --title "{title}" \
  --base "{BASE_BRANCH}" \
  --body "$(cat <<'PR_EOF'
{filled PR body}
PR_EOF
)"

Report the PR URL to the user.

9f: Update existing PR

If a PR already exists:

1. Rebuild the PR body using the same template, incorporating all commits including documentation updates.
2. Show the updated body to the user and ask for approval.
3. Update:

gh pr edit EXISTING_PR_NUMBER \
  --title "{updated_title}" \
  --body "$(cat <<'PR_EOF'
{updated PR body}
PR_EOF
)"

Report the PR URL to the user.

If the update includes fix commits (e.g., addressing review feedback), prompt the user after the push:

Want me to comment on the PR to confirm the fixes? I can run /gh-comment.

Step 10: Final summary

Report to the user:

• Branch name and PR URL
• Whether the PR was created or updated
• Which optional documentation steps were performed (README, docs, planning)
• Linked issue number (if any)

What's Next

If a linked issue was detected in Step 2 (ISSUE_NUMBER is set), offer:

Want me to post a status comment on issue #N? I can run /gh-comment.

Gotchas

Before running any `