PR

Quickly push changes and open a draft pull request on GitHub.

When to Use

• You have staged changes ready to push and want to create a draft PR
• Early feedback needed on work-in-progress
• Want to document and track changes before final review
• Need to open a PR for discussion or CI validation

Instructions

Step 1: Verify Staged Changes

Check what will be committed:

git status

Ensure all changes you want are staged with:

git add <files>

Or add everything:

git add .

Step 2: Create Commit Message

Write a clear, conventional commit message. Use the format:

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

<optional body with details>

Types: feat, fix, chore, refactor, docs, test, etc.

Examples:

• feat(registry): add new skill category
• fix(cli): resolve version mismatch
• chore: regenerate artifacts

Step 3: Commit Changes

git commit -m "your commit message here"

Step 5: Push to Remote

git push -u origin <branch-name>

If you're on main or pushing to an existing branch:

git push

Step 6: Create Draft PR

gh pr create --draft

This will prompt you for:

• Title — auto-filled from commit, edit as needed
• Body — add context, description, or leave blank
• Assignees — optional
• Labels — apply by judgement; see Step 7

For multiline descriptions, use a body file with real newlines. Do not pass literal \\n sequences or rely on shell $'...' quoting; malformed quoting can make GitHub display \\n (and sometimes a stray $).

cat > /tmp/pr-body.md <<'EOF'
## Summary

Describe the change here.
EOF
gh pr create --draft --title "Your PR Title" --body-file /tmp/pr-body.md

After creating or editing the PR, verify the stored body:

gh pr view <number> --json body --jq .body

Or specify details inline for a one-line body:

gh pr create --draft --title "Your PR Title" --body "Description here"

Step 7: Apply Labels by Judgement

Labels are how humans and automation triage the PR queue, so choose them deliberately — but never hardcode a fixed label list. Repos define their own labels and rename or retire them over time; a memorized set rots and won't transfer across repos. Instead, read the live set and reason about fit each time.

1. Read the repo's actual labels (names and descriptions — the description tells you the intended use):

   gh label list --limit 200 --json name,description --jq '.[] | "\(.name) — \(.description)"'
   

2. Pick the smallest set that is actually true of this PR. Match the diff's substance against label descriptions:

   • What kind of change is it? (bug fix, enhancement, refactor, docs, dependency bump …)
   • What area does it touch? (frontend, backend, CLI, schema, CI …)
   • Does a cross-cutting label genuinely apply? (performance, security, tech-debt …) — only if the PR materially does that, not aspirationally.
   • Is there a state/process label the repo uses for triage or gating? (needs-review, awaiting-assets, blocked …) Apply one only if it reflects reality.

3. Prefer precision over coverage. Two labels that are exactly right beat five that are loosely related. If nothing fits, apply nothing — a wrong label misroutes triage worse than a missing one.

4. Skip labels you can't justify. Roadmap/sprint/phase tags, auto-merge eligibility, ownership cosign labels, etc. usually require context the PR author must supply — don't guess them. If a required-by-process label is missing (e.g. the repo gates on a scope or migration-notes label) and you can't satisfy it, say so rather than applying it falsely.

5. Apply, then confirm:

   gh pr edit <number> --add-label "<label-1>" --add-label "<label-2>"
   gh pr view <number> --json labels --jq '.labels[].name'
   

State briefly why each label was chosen (and note any you deliberately skipped) so the reasoning is auditable.

Tips

• Accidental staging leakage: if a PR contains unrelated staging changes, do not force-push blindly. Start a clean branch from current origin/main, apply only the intended files, verify git diff --stat origin/main...HEAD, then push and create a replacement draft PR. Close the contaminated PR and cross-reference the replacement in a comment.
• Draft PRs show as "Draft" and won't trigger auto-merge workflows
• Rebase before final PR — git rebase -i origin/main to clean up commits
• Ready to review? — Use gh pr ready to convert from draft to ready-for-review
• Add more commits — Just push again with git push, the PR updates automatically

Troubleshooting

"fatal: The current branch has no upstream branch"

• Use git push -u origin <branch-name> on first push

"Permission denied" when pushing

• Check your git credentials: gh auth status
• Re-authenticate if needed: gh auth login

PR creation fails

• Ensure you're in a git repository: git rev-parse --show-toplevel
• Check GitHub CLI is installed: gh version