pr

name	pr
description	Create a pull request with structured description, run review, and merge
version	2.0.0
compat	claude-code, codex, cursor, openclaw
fill	owner, repo, scopes

Skill: pr

Purpose

Create a pull request for the current branch with a structured description, run the review, and merge when the review approves. This is the formal closure of each task.

Preconditions

• npm run build must pass without errors before creating the PR
• All changes committed (git status clean)
• Branch pushed to origin

Invocation

/pr

---

Steps

1. Verify the build passes

npm run build

If it fails: fix before continuing. Do not create PRs with broken builds.

2. Commit pending changes

git status
# If there are uncommitted changes: use /commit before continuing

3. Push the branch

git push -u origin $(git branch --show-current)

4. Get the GitHub token

GITHUB_TOKEN=$(grep GITHUB_TOKEN .env.local | cut -d= -f2)

5. Create the PR via GitHub API

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/{{FILL: owner}}/{{FILL: repo}}/pulls \
  -d '{
    "title": "feat(scope): description",
    "head": "'"$(git branch --show-current)"'",
    "base": "main",
    "body": "..."
  }'

6. Run the review

git diff main...HEAD

Apply the /review skill (or equivalent for this project). If it finds blockers: fix → /commit → git push → repeat.

7. Merge when the review approves

curl -s -X PUT \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/{{FILL: owner}}/{{FILL: repo}}/pulls/{{PR_NUMBER}}/merge \
  -d '{"merge_method": "merge"}'

Method always merge — never squash. This preserves the individual history of each task.

8. Return to main and update

git checkout main
git pull origin main

Do not delete the branch — it serves as a historical reference.

---

PR Body Template

## What does this PR do?
<!-- One or two sentences describing the change from a product or architecture perspective. -->

## Main technical changes
<!-- List new/modified files or components. 2-4 bullets max. -->
- 
- 

## How to test
<!-- Steps to verify the change works. Important for backend or complex logic. -->
1. 
2. 

## Checklist
- [ ] `npm run build` passes without errors
- [ ] `npm run dev` works — manually tested the main flow
- [ ] No debug console.logs
- [ ] No hardcoded secrets
- [ ] No credentials or sensitive data in the description
- [ ] The review (`/review` or equivalent) found no blockers
- [ ] If UI: empty and error states are handled

## Screenshots (if applicable)
<!-- If it's a visual change, attach before/after screenshots. -->

---

Valid scopes for the PR title

{{FILL: List this project's scopes.

Convention: Scopes must match those in /commit. Example for e-commerce: auth, catalog, cart, payments, admin, db, notifications

The PR title must always follow Conventional Commits: <type>(<scope>): description

Examples:

• feat(cart): add quantity selector
• fix(auth): prevent login bypass on expired session
• refactor(db): consolidate migration scripts
• chore: update dependencies }}

---

PR Validation

A well-formed PR has:

• Title following Conventional Commits: <type>(<scope>): description
• Clear, concise body (not long paragraphs without formatting)
• Checklist marked (at least that npm run build passed)
• Brief what description; the how is in the diff

Common failure modes

Creating a PR without passing local tests. If npm run build fails on your machine, it will also fail in CI. Don't wait for the reviewer to find it.

PRs with mixed responsibilities. One task = one PR. If you changed auth and also the cart UI, those are two different PRs. The history suffers when they're mixed.

Empty body. The template exists for a reason. Filling it takes 2 minutes and saves the reviewer time. The body is async communication with the team.

Forgetting to push the branch. If git push -u doesn't execute or fails, the PR will point to a branch that doesn't exist on origin. Always verify with git branch -vv.