Generate PR descriptions for SDK pod packages following template and format rules. Use when creating an SDK pod PR or invoking /qv-sdk-pr-create.
SDK Pod PR Creation
Generate PR titles and descriptions for SDK pod packages, following the team's template and format rules.
When to use this skill
Applies to SDK pod packages as defined in .cursor/rules/sdk/sdk-pod-packages.mdc.
Use when:
Creating a PR for any SDK pod package
User asks to generate PR description
User invokes /qv-sdk-pr-create
Workflow
Identify base and current branch — note whether the base is main or a release-<pkg>-<x.y.z> branch
Collect commits/diff from <base>...origin/<branch>
Infer ticket, prefix, and tags from changes (see Inference Strategy)
Only ask user for input when inference confidence is low
Generate title: TICKET prefix[tags]: subject
Fill template sections based on changes
Validate tag requirements ([bc]/[api]/[mod])
If diff touches packages/sdk/package.json version or dep blocks, chain into the qv-sdk-bare-sdk-sync skill (see "SDK ↔ bare-SDK Sync Trigger" below)
Output complete PR description
If base is a release branch, chain into the dual-PR flow (see "Release Target Dual-PR Flow" below)
Inference Strategy
Infer first, ask only if uncertain:
Ticket number:
Extract from branch name pattern: QVAC-\d+, SDK-\d+
Extract from commit messages if referenced
ASK only if no ticket found
Prefix (feat/fix/doc/test/chore/infra):
Extract from branch name prefix: feat/, fix/, infra/, etc.
Use majority prefix from commit messages
If no conventional commits, infer from diff:
New files/exports → feat
Bug-related changes → fix
Only .md files → doc
Only test files → test
ASK only if mixed signals or unclear
Tags ([api]/[bc]/[mod]):
[api]: new exported functions/types in public API
[bc]: removed/changed existing public API signatures
[mod]: changes to model constant definitions
ASK only if change scope is ambiguous
Testing section:
If test files modified → "Unit tests added/updated for X"
If no tests → ASK what manual testing was done
Format References
PR title format: See .cursor/rules/sdk/commit-and-pr-format.mdc
PR body template: See .github/PULL_REQUEST_TEMPLATE/sdk-pod.md
Fill template sections based on the diff analysis. Delete sections that don't apply.
Output Format
ALWAYS output the PR in this copy-ready format, even when making corrections:
## PR Title
```
TICKET prefix[tags]: subject
```
## PR Body
```markdown
## 🎯 What problem does this PR solve?
...
```
gh CLI Integration
After generating the PR description, check for gh CLI:
Check if gh is installed: which gh
Check remotes: git remote -v to identify fork (origin) vs upstream
If available, ask user: "Create PR now with gh CLI?" [Yes / No / Preview first]
If yes, ensure changes are committed and pushed first
Create PR with explicit repo/base/head for fork workflows:
# For fork -> upstream PRs:
gh pr create \
--repo UPSTREAM_ORG/REPO \
--base main \
--head FORK_OWNER:BRANCH \
--title "TICKET prefix: subject" \
--body "..."# Then open in browser:
gh pr view --repo UPSTREAM_ORG/REPO BRANCH --web
Important:
--web alone only opens browser for manual creation, does NOT create the PR
For fork PRs, must specify --repo, --base, and --head explicitly
Commit and push before creating PR
If gh not available, output the copy-ready markdown format above
As part of the output, provide a clickable hyperlink (not plain text) to the PR on GitHub.
SDK ↔ bare-SDK Sync Trigger
Trigger: the PR diff (<base>...origin/<branch>) touches packages/sdk/package.json and modifies one of: version, dependencies, optionalDependencies, peerDependencies.
When triggered, prompt the user to run qv-sdk-bare-sdk-sync so the same change is mirrored into packages/bare-sdk/package.json (with bare-sdk's NOTICE regenerated) in the same commit/PR. @qvac/sdk and @qvac/bare-sdk ship in lockstep — letting them drift in a PR creates work for the next release.
Steps (after Step 7 of Workflow above)
Detect the trigger condition by inspecting the diff:
Changes touch the version line OR any dependencies / optionalDependencies / peerDependencies block
If triggered, ask user: "PR touches sdk's deps/version. Run qv-sdk-bare-sdk-sync to mirror into bare-sdk?" [Yes / No (skip)]
If yes, read .cursor/skills/qv-sdk-bare-sdk-sync/SKILL.md and follow it inline. The skill writes to packages/bare-sdk/package.json and regenerates packages/bare-sdk/NOTICE.
Verify with cd packages/bare-sdk && bun run check:deps-vs-sdk — must pass.
Stage and commit the bare-sdk changes onto the same branch BEFORE proceeding to Output step. The PR should ship the sdk and bare-sdk updates atomically.
If qv-notice-generate bare-sdk fails (missing env tokens, etc.), STOP and surface the error. Do not output the PR description until bare-sdk is in sync.
Opt-out
To skip the bare-sdk sync for a single run, the user can invoke /qv-sdk-pr-create --no-sync. The skill proceeds normally and emits a reminder at the end: "Reminder: sdk deps changed but bare-sdk was not synced. Run /qv-sdk-bare-sdk-sync before merge or expect check:deps-vs-sdk to fail in CI."
Docs Artifacts (SDK Releases)
Context: for @qvac/sdk releases, the qv-sdk-changelog skill (Step 8)
now generates the documentation-site API reference + release notes locally and
ships them in this same release PR. There is no longer a separate
auto-generated docs PR (the old docs-release.yml workflow was removed).
Staging works the same as for the rest of the release commit — no special
handling is needed. Step 8's three committable surfaces
(docs/website/content/docs/reference/api/**,
docs/website/content/docs/reference/release-notes/**,
docs/website/src/lib/versions.ts) show up in git status alongside the
changelog, while every generation/build byproduct
(api-data.json, .next/, .source/, out/, dist/, next-env.d.ts,
packages/sdk/dist/) is gitignored and therefore never appears. Review
git status and commit the shown files as usual.
Reviewers should expect the reference/api + reference/release-notes diff in
the release PR alongside the changelog.
Release Target Dual-PR Flow
Trigger: the just-created PR's base is release-<pkg>-<x.y.z> for any SDK pod package.
When triggered, automatically chain into the sdk-backmerge skill so a follow-up PR is also opened against main with the same version-bump + changelog metadata. This applies the gitflow.md "Keep main aligned" rule at PR-creation time so nobody has to remember a follow-up step after the release PR merges.
Steps (after Step 5 of gh CLI Integration above)
Capture context for the backmerge:
Just-created release PR number and URL
Release branch name (release-<pkg>-<x.y.z>) and parsed <pkg> / <x.y.z>
Source fork branch (the head of the release PR)
Ticket number from the title
Invoke the sdk-backmerge workflow inline with these inputs (read .cursor/skills/qv-sdk-backmerge/SKILL.md and follow it).
Fail-stop policy — if the backmerge cherry-pick produces a conflict outside sdk-backmerge's auto-resolve list, STOP. Print:
The release PR URL (success — PR #1 is open)
The current git status -sb from the conflicted cherry-pick
Resume instructions: git add <files> && git cherry-pick --continue, then run /qv-sdk-backmerge --resume
On success, print both PR URLs as clickable hyperlinks, ordered:
Release PR (target: release-<pkg>-<x.y.z>)
Backmerge PR (target: main)
Opt-out
To skip the backmerge for a single run, the user can invoke /qv-sdk-pr-create --no-backmerge. The skill still creates PR #1 normally and prints a reminder pointing to /qv-sdk-backmerge for later.
Quality Checklist
Before outputting the PR description, verify:
Title follows format: TICKET prefix[tags]: subject
"What problem" describes user impact, not implementation
"How it solves" is high-level approach, not line-by-line
Unused sections are deleted
[bc] tag has BEFORE/AFTER code examples
[api] tag has usage example
[mod] tag has Added/Removed models list
Description is concise - bullet points, no fluff
Generated helper notes, template instructions, and tool footers are removed from the PR body
If diff touches packages/sdk/package.json deps/version, the sync skill ran (or --no-sync was set with a reminder emitted), and check:deps-vs-sdk passes
For sdk releases with generated docs, git status shows only reference/api/**, reference/release-notes/**, and src/lib/versions.ts as committable docs changes — disposable byproducts (api-data.json, out/, .next/, dist/, etc.) are gitignored
If base is release-<pkg>-<x.y.z>, the dual-PR flow ran (or --no-backmerge was set), and both PR URLs are reported
References
SDK pod packages: .cursor/rules/sdk/sdk-pod-packages.mdc
