create-pr

name	create-pr
description	Create a GitHub pull request for the pvcaptest fork following project conventions. Use this skill whenever the user asks to create a PR, open a pull request, submit changes for review, or push a branch up for review. Handles pre-flight checks (tests, lint, docs), commit analysis, and PR creation via the gh CLI targeting the upstream pvcaptest repo.

Create Pull Request (pvcaptest)

This skill walks through creating a well-structured pull request for a pvcaptest fork. The repo has a fork/upstream layout — all PRs target pvcaptest/pvcaptest:master.

Repository layout

The fork uses two remotes:

• origin → contributor's personal fork on GitHub (e.g. [e-mail]:USERNAME/pvcaptest.git)
• upstream → [e-mail]:pvcaptest/pvcaptest.git

All git commands use the standard git CLI. All recipe commands use just.

---

Environment detection

Before running any commands, resolve these two values and use them throughout the rest of the skill:

# Absolute path to the repo root
REPO_ROOT=$(git rev-parse --show-toplevel)

# GitHub username of the fork owner, parsed from the origin remote URL
FORK_OWNER=$(git remote get-url origin | sed -E 's|.*[:/]([^/]+)/[^/]+(.git)?$|\1|')

Verify both values look correct before continuing.

---

Step 1: Pre-flight checks

Run all checks before doing anything else. Stop and tell the user what needs fixing if any fail.

1a. Verify gh CLI is installed and authenticated

gh --version
gh auth status

If not installed or not authenticated, stop and guide the user accordingly.

1b. Check for uncommitted changes

git -C "$REPO_ROOT" status --porcelain

If output appears, stop. List the dirty files and ask the user to commit or stash before continuing.

1c. Check for an existing PR on this branch

BRANCH=$(git -C "$REPO_ROOT" branch --show-current)
gh pr list --head "$BRANCH" --repo pvcaptest/pvcaptest --json number,title,url

If a PR already exists, show the details and ask if the user wants to view it, push more commits to update it, or close it and open a new one. Only proceed with creation if there is no existing PR.

1d. Verify we're not on master

git -C "$REPO_ROOT" branch --show-current

If the current branch is master, stop and ask the user to switch to or create a feature branch.

1e. Run tests and linting

These must pass before opening a PR (run in order shown):

just -f "$REPO_ROOT/.justfile" lint
just -f "$REPO_ROOT/.justfile" fmt
just -f "$REPO_ROOT/.justfile" test

If tests or linting fail, stop and report the failures. Do not proceed until they are resolved.

1f. Check whether docs need updating

Get the files changed on this branch relative to upstream:

git -C "$REPO_ROOT" diff upstream/master...HEAD --name-only

If any src/captest/ Python files are changed but no docs/ files appear in the diff, the docs likely haven't been updated. Ask the user: "Source files changed but docs haven't been updated. Would you like to run the docs-update skill before creating the PR?"

• If yes: invoke docs-update, then return here and continue.
• If no: proceed.

---

Step 2: Gather context

2a. Analyze commits on this branch

git -C "$REPO_ROOT" log upstream/master..HEAD --oneline

Review these commits to understand the scope and intent of the changes.

2b. Review the diff summary

git -C "$REPO_ROOT" diff upstream/master..HEAD --stat

This shows which files changed and helps identify the type of change (feature, fix, refactor, docs, etc.).

---

Step 3: Push the branch to the fork

The branch MUST be pushed to origin (the contributor's fork). NEVER push feature branches to upstream (pvcaptest/pvcaptest).

First, confirm the branch already exists on the fork:

BRANCH=$(git -C "$REPO_ROOT" branch --show-current)
git -C "$REPO_ROOT" ls-remote --heads origin "$BRANCH"

If the output is empty, the branch does not yet exist on the fork. Push it and set up tracking:

git -C "$REPO_ROOT" push -u origin HEAD

If the branch already exists on the fork, push any new commits:

git -C "$REPO_ROOT" push origin HEAD

If the branch was rebased, use:

git -C "$REPO_ROOT" push origin HEAD --force-with-lease

After pushing, confirm the branch is present on the fork before continuing.

---

Step 4: Compose the PR

PR title

Synthesize a clear, specific title from the commits and diff. Avoid generic titles like "fix", "update", or "changes".

Look for a conventional-commits style in the commit messages (feat:, fix:, docs:, refactor:, test:, chore:). If present, use that prefix. Otherwise use a plain descriptive title, e.g. "Add pagination to search results" or "Fix race condition in authentication flow."

If a GitHub issue number appears in commit messages or the branch name (patterns like #123, fixes #123, issue-123), append it to the title.

PR body

There is no .github/pull_request_template.md in this repo. Use this structure:

## Summary

<What problem does this solve or what feature does it add? 1–3 sentences.>

## Changes

<Bullet list of the meaningful changes — files or behaviors modified.>

## Testing

<How was this tested? Mention test files modified or commands run.>

## Notes (optional)

<Breaking changes, follow-up work, or anything the reviewer should know.>

Fill each section from the commit messages and diff. Be specific — reference method names, parameter names, and module names where relevant.

If an issue number was found, add a Closes #N or Fixes #N line at the bottom of the body.

Draft vs. ready-for-review

Use --draft when:

• Changes are incomplete or you want early feedback
• CI is expected to fail and you need help debugging
• You want to mark progress but aren't ready for merge

Skip --draft when tests pass and the work is complete.

---

Step 5: Create the PR

Always include --head FORK_OWNER:BRANCH to explicitly identify the fork branch as the source. Without this flag the gh CLI may interactively push the branch to the upstream repo instead of the fork.

BRANCH=$(git -C "$REPO_ROOT" branch --show-current)
gh pr create \
  --title "PR_TITLE" \
  --body "PR_BODY" \
  --base master \
  --head "${FORK_OWNER}:${BRANCH}" \
  --repo pvcaptest/pvcaptest

For a draft:

BRANCH=$(git -C "$REPO_ROOT" branch --show-current)
gh pr create \
  --title "PR_TITLE" \
  --body "PR_BODY" \
  --base master \
  --head "${FORK_OWNER}:${BRANCH}" \
  --repo pvcaptest/pvcaptest \
  --draft

---

Step 6: Post-creation

Open the PR in the browser to verify it rendered correctly:

gh pr view --web --repo pvcaptest/pvcaptest

Remind the user that the CI workflow (.github/workflows/pytest.yml) will run automatically. Monitor it with:

gh pr checks --repo pvcaptest/pvcaptest

---

Error reference

Problem	What to do
No commits ahead of upstream/master	Ask if the user is on the right branch
Branch not pushed to fork	Run git -C "$REPO_ROOT" push -u origin HEAD
PR already exists	Show it; ask if they want to update or replace
Tests failing	Fix failures before proceeding
Merge conflicts with upstream	Guide through git -C "$REPO_ROOT" rebase upstream/master
Branch accidentally pushed to upstream	Close the PR, delete the upstream branch with git -C "$REPO_ROOT" push upstream --delete BRANCH_NAME, push to fork with git -C "$REPO_ROOT" push -u origin HEAD, then recreate the PR with the correct --head flag

---

Co-author attribution

All commits should include the co-author line. When committing as part of this workflow:

Co-Authored-By: Oz <[e-mail]>