type(scope): lowercase description

Types: feat, fix, chore, docs, refactor, test, perf, ci
Scope: package or area affected (groq, cli, form, schema, deps, etc.)
No backticks, quotes, or markdown in the title
Description starts lowercase

3. Write the PR body

Lead with why. Only elaborate on the non-obvious. The reviewer can read the diff — they need the context the diff can't give them. Default to terse; expand only where a reader would genuinely wonder.

Priorities for the Description section:

Heavy on why — the motivation, the problem being solved, the constraint or incident that forced this change
Cover why not — alternatives considered and rejected, one sentence each. This is often the most valuable part: it prevents the reviewer from suggesting a path you've already ruled out. Skip if there were no real alternatives worth mentioning
Light on how — only call out approach when it's non-obvious, novel, or a reviewer might reasonably have picked a different path. Skip it for routine changes where the diff speaks for itself
Minimal what — the diff shows what changed. One sentence of orientation at most; don't restate file-by-file changes the reviewer can see

Length test: if a sentence would tell the reviewer something they could deduce in 10 seconds from the diff, cut it. A good PR description is often 3–5 sentences total. Bulleted lists of "alternatives considered" should be one line per alternative, not a paragraph.

If you catch yourself writing "this PR renames X to Y" or "adds a new function Z", delete it. If you're explaining why X needed to be renamed or why Z exists (and why the obvious alternative wasn't chosen), keep it — but stay brief.

Use all four sections:

Description

Focus on why and why not, tersely:

The problem or context the diff doesn't reveal (one short paragraph)
Alternatives considered and why rejected (one line each, only if they were real candidates)
How only when non-obvious or debatable
What reduced to a one-line orientation

What to review

Which files/areas matter most
Anything tricky or non-obvious
Which packages are affected (this is a monorepo)

Testing

Tests added or modified
If no automated tests: how you tested and why automation wasn't practical

Notes for release

This section is used by the docs team to write release notes.

If not needed, write one of:

N/A — internal-only changes
N/A – Part of feature X — partial implementation not yet enabled
N/A – Internal only — tooling/chore work

If needed, write for end users and the docs team:

What changed from a user perspective
How to use it (code snippets if applicable)
Limitations or breaking changes

4. Create the PR

Always create as draft. Do not mark as ready for review until CI passes.

gh pr create --draft --title "type(scope): description" --body "$(cat <<'EOF'
### Description

[what and why]

### What to review

[guidance for reviewers]

### Testing

[tests added or manual testing explanation]

### Notes for release

[release notes or N/A]
EOF
)"

After CI is green, mark ready for review:

gh pr ready

Release notes checklist

Written for end users, not internal engineers
Includes code snippets for new APIs or changed behavior
Mentions breaking changes prominently
No unexplained jargon
Concise — a paragraph plus code example is ideal

pr-description

PR Description & Release Notes

When creating a PR

1. Analyze the changes

2. PR title