name	create-pr
description	Create PRs with titles and bodies that produce accurate release notes. Use when opening a pull request, merging to develop or main, or when user says "open a PR", "create a PR", "ready to merge", or "ship it".

Create PR

Rules

Create short-lived feature branches from develop for all work.
Open normal work PRs from feature branches into develop.
Prefer squash merge for feature → develop PRs. The PR title becomes one clean Conventional Commit on develop.
Open release PRs from develop into main when ready to ship.
Merge release PRs with a merge commit, not squash, so release-please sees the individual Conventional Commits accumulated on develop.
The release PR body becomes useful release context, but release-please changelog entries come from commits merged to main.
Use fix(...) for release-affecting fixes, including broken publish/release automation. Do not use ci(...) if the change must trigger a release.

PR title format

<type>(<scope>): <summary of all changes>

Pick the highest-impact type: feat > fix > refactor > test > docs > chore.

PR body format

## What changed

- <change 1>
- <change 2>
- <change 3>

## Context

<1-2 sentences on why>

## Test plan

- [ ] <how to verify>

Before creating a feature → develop PR

Run git fetch origin.
Confirm current branch is a feature branch, not main or develop: git branch --show-current.
Run git diff origin/develop...HEAD --name-status to see actual changed files in the PR.
Run git diff origin/develop...HEAD -- <file> to understand actual content changes.
Synthesize the title and body from the diff, not from commit headlines alone.
Verify npm run build && npm test passes.
Push the branch: git push -u origin <branch>.
Create PR: gh pr create --base develop --head <branch> --title "<title>" --body "<body>".
After creating PR, run gh pr diff <number> --name-only and gh pr view <number> --json files,title,body to confirm body matches actual changed files.

Before creating a develop → main release PR

Run git fetch origin.
Run git diff origin/main...origin/develop --name-status to see actual release contents.
Run git log --oneline origin/main..origin/develop to review Conventional Commits that release-please will see after merge.
Verify release PR body summarizes the diff, not stale branch history.
Create PR: gh pr create --base main --head develop --title "chore(release): merge develop into main" --body "<body>".
Merge with a merge commit, not squash.

Title quality check

Would a user reading the changelog understand what changed?
Does it cover all user-visible changes, not just the first commit?
Is the type correct? (feat = user-visible feature, fix = bug, chore = internal)
No period at the end. No trailing punctuation.

Bad vs Good

Bad: feat: updates (vague) Bad: fix: typo in readme when the branch also adds tests and error handling (understates) Bad: feat: add error handling, tests, --version flag, npm publish, CONTRIBUTING.md (too long, use body)

Good: feat: add error handling, tests, and npm publish workflow (concise, accurate scope) Good: fix: handle malformed JSONL in source parsers (specific, covers the real fix)

Create PR

Rules

Create short-lived feature branches from develop for all work.

Open normal work PRs from feature branches into develop.

Prefer squash merge for feature → develop PRs. The PR title becomes one clean Conventional Commit on develop.

Open release PRs from develop into main when ready to ship.

Merge release PRs with a merge commit, not squash, so release-please sees the individual Conventional Commits accumulated on develop.

The release PR body becomes useful release context, but release-please changelog entries come from commits merged to main.

Use fix(...) for release-affecting fixes, including broken publish/release automation. Do not use ci(...) if the change must trigger a release.

PR title format

<type>(<scope>): <summary of all changes>

Pick the highest-impact type: feat > fix > refactor > test > docs > chore.

PR body format

## What changed - <change 1> - <change 2> - <change 3> ## Context <1-2 sentences on why> ## Test plan - [ ] <how to verify>

Before creating a feature → develop PR

Run git fetch origin.

Confirm current branch is a feature branch, not main or develop: git branch --show-current.

Run git diff origin/develop...HEAD --name-status to see actual changed files in the PR.

Run git diff origin/develop...HEAD -- <file> to understand actual content changes.

Synthesize the title and body from the diff, not from commit headlines alone.

Verify npm run build && npm test passes.

Push the branch: git push -u origin <branch>.

Create PR: gh pr create --base develop --head <branch> --title "<title>" --body "<body>".

After creating PR, run gh pr diff <number> --name-only and gh pr view <number> --json files,title,body to confirm body matches actual changed files.

Before creating a develop → main release PR

Run git fetch origin.

Run git diff origin/main...origin/develop --name-status to see actual release contents.

Run git log --oneline origin/main..origin/develop to review Conventional Commits that release-please will see after merge.

Verify release PR body summarizes the diff, not stale branch history.

Create PR: gh pr create --base main --head develop --title "chore(release): merge develop into main" --body "<body>".

Merge with a merge commit, not squash.

Title quality check

Would a user reading the changelog understand what changed?

Does it cover all user-visible changes, not just the first commit?

Is the type correct? (feat = user-visible feature, fix = bug, chore = internal)

No period at the end. No trailing punctuation.

Bad vs Good

Good: feat: add error handling, tests, and npm publish workflow (concise, accurate scope) Good: fix: handle malformed JSONL in source parsers (specific, covers the real fix)

create-pr

Create PR

Rules

PR title format

PR body format

Before creating a feature → develop PR

Before creating a develop → main release PR

Title quality check

Bad vs Good

Create PR

Rules

PR title format

PR body format

Before creating a feature → develop PR

Before creating a develop → main release PR

Title quality check

Bad vs Good