// Plan and run local PR validation for tetherto/qvac PRs. Reuses the shared PR worktree, discovers touched packages and package.json scripts, recommends a test tier, and analyzes results. Use when testing a PR or invoking /qv-pr-test.
| name | qv-pr-test |
| description | Plan and run local PR validation for tetherto/qvac PRs. Reuses the shared PR worktree, discovers touched packages and package.json scripts, recommends a test tier, and analyzes results. Use when testing a PR or invoking /qv-pr-test. |
| disable-model-invocation | true |
Manual-trigger local PR validation for any GitHub PR in tetherto/qvac.
The skill prepares an isolated PR worktree, discovers changed packages and test options, recommends a tier, and then runs or proposes the selected validation steps according to package type.
High-level flow:
Use when:
/qv-pr-test.https://github.com/tetherto/qvac/pull/1234.android or ios), desired tier.If PR URL is missing, ask for it. Do not ask other questions until discovery has produced a concrete recommendation.
This skill must not touch the user's local working tree.
Forbidden against the user's main repo:
git switch, git checkout, git reset, git restoregit stash, git pull, git merge, git rebase, git cherry-pickgit cleangh pr checkoutThe shared script worktree-prepare.mjs is allowed to operate only inside ~/.cache/qvac-pr-review/pr-<num>/. It may fetch PR refs, add/remove worktrees, reset tracked files, and clean untracked artifacts on SHA drift.
The agent may run non-e2e package manager/build/test commands only inside the prepared worktree path printed by worktree-prepare.mjs.
For every selected tier, agent-owned package validation must prepare the touched package root before examples or non-e2e tests run. If discovery reports commands.install or commands.build, include those setup commands first in the proposed command plan and execute them first from the package cwd.
Track this checklist:
- [ ] 0a. Prepare worktree with worktree-prepare.mjs
- [ ] 0b. Discover packages/scripts/tests with pr-test-discover.mjs
- [ ] 1. Present recommendation and tier menu
- [ ] 2. Ask user to select tier and mobile platform when needed
- [ ] 3. Print proposed command sequence
- [ ] 4a. Run agent-owned setup/examples when safe and applicable
- [ ] 4b. If SDK e2e is included: stop and ask user to run the printed e2e setup + e2e command block
- [ ] 4c. If SDK e2e is not included: ask approval, then execute remaining commands
- [ ] 5. Analyze logs/reports
- [ ] 6. Summarize pass/fail and next action
Run:
node .cursor/skills/_lib/pr-skills/worktree-prepare.mjs <PR-URL>
Parse stdout:
WORKTREE_PATH=<absolute path>
HEAD_SHA=<sha>
PATCH_PATH=<absolute path to patch>
BASE_REF=<remote>/<baseRefName>
If stderr contains WORKTREE_FALLBACK=<reason>, use fallback mode:
pr-test-discover.mjs fetch the patch with gh pr diff --patch into the platform temp directory when PATCH_PATH is unavailable.Run:
node .cursor/skills/_lib/pr-skills/pr-test-discover.mjs <PR-URL> --worktree <WORKTREE_PATH> --head-sha <HEAD_SHA> --patch <PATCH_PATH>
The helper emits a JSON manifest with:
recommendation.recommendedTierrecommendation.recommendationReasontouchedPackages[]touchedPackages[].scriptstouchedPackages[].commandstouchedPackages[].addedOrModifiedExamplestouchedPackages[].exampleCommandstouchedPackages[].relatedExampleCommandstouchedPackages[].addedOrModifiedTeststouchedPackages[].relatedTestssdkE2eSetupDiscovery is based on committed PR state only. Do not run git diff, git status, or git ls-files --modified inside the worktree for classification.
Use touchedPackages[].commands.install and touchedPackages[].commands.build as package-root setup steps for all executable tiers. These setup commands belong before changed examples, related examples, non-SDK tests, or SDK manual e2e command blocks.
All tiers include necessary install/build setup for the touched package roots.
not applicable.e2e tests on desktop. Non-SDK runs the smallest unit-level package script (test:unit or test), or first available test:*.android or ios). Non-SDK uses mobile scripts only if package.json exposes them.--suite smoke on desktop. Non-SDK advances to the next least-to-most-complete script if one exists.--suite smoke on selected mobile platform. Non-SDK uses mobile scripts only if package.json exposes them.test:all if present, otherwise all applicable test:* scripts in increasing completeness order.T2 and every higher tier are additive over T1. If exampleCommands is non-empty, the proposed command plan for T1/T2/T3/T4/T5/T6/T7 MUST include package-root install/build setup first, then every changed example command before the e2e/smoke/full test command. Do not summarize examples as "applicable" without emitting runnable commands. Changed helper files under examples, such as shared.ts or utils.ts, should be listed as supporting files but not emitted as runnable commands.
Related examples and tests are bundled into the existing tiers as proposal items, not separate options:
relatedExampleCommands are examples that appear semantically related to the changed paths. Prefer safe examples first: no obvious required input/device and no obvious output-file generation. Present them after changed examples as "related examples proposed by discovery", and let the user deselect them before agent execution.relatedTests are existing SDK e2e filters related to the changed paths. If no e2e files changed, use the highest-scoring related filter as the proposed T2 filter. If e2e files did change, show related filters as optional additions.transcription e2e filter even if the PR did not edit those files directly.Changed examples are agent-run steps after package-root install/build setup succeeds. SDK e2e setup is not agent-run; hand it to the user together with the e2e command because it requires npm auth.
T6/T7 replace the smoke step from T4/T5. T1-T3 still run unchanged.
Always show the recommendation before the tier prompt. The user can override it.
packages/sdk) default: recommend T2. This covers install/build, changed examples if present, and changed e2e on desktop. Mobile is opt-in because it is slower and usually covered by CI.not applicable.Use AskQuestion for tier selection. Ask for android or ios only when the recommended or selected tier includes mobile (T3, T5, or T7).
The tier prompt MUST include T1 whenever exampleCommands or relatedExampleCommands is non-empty, even when the recommended tier is higher. Do not hide lower additive tiers. If examples are absent, show T1 as not applicable or omit it with an explicit "no changed or related examples" note in the plan.
Before executing examples, show both changed and related example commands. Related examples are proposed, not mandatory; use AskQuestion to let the user choose which related examples to include when any are present.
SDK changed examples may be agent-run inside the prepared worktree after the SDK package root has been installed and built.
SDK e2e setup and e2e commands are manual/user-run:
npm run install:buildnpm run install:build:fullnpx qvac-test run:local:*Do not execute those agentically. e2e setup needs npm/GitHub Packages auth that is not available in the agent context, and SDK e2e commands are device/broker-dependent and may run for a long time.
For any SDK e2e command, run setup from packages/sdk/e2e first.
SDK source outside packages/sdk/e2e/ changed:
npm run install:build:full
Only packages/sdk/e2e/ changed:
npm run install:build
Do not skip setup based on assumed previous state. The PR worktree is treated as clean/synchronized, and SDK e2e validation must prepare the test package explicitly.
Do not separately run bun install or bun run build in packages/sdk before SDK e2e unless the chosen tier also includes non-e2e SDK example validation that specifically needs it.
For SDK e2e tiers, print the e2e setup command and e2e command for the user to run manually. The agent must not run npm run install:build, npm run install:build:full, or npx qvac-test run:local:* from packages/sdk/e2e.
Generate commands for the user's shell/OS. Do not assume POSIX-only utilities or paths. In particular:
mkdir -p only for POSIX shells. For PowerShell, use New-Item -ItemType Directory -Force.export NAME=... for POSIX, $env:NAME = "..." for PowerShell).Run ID format:
pr-<num>-<headSha7>-<tier>-<platform-or-desktop>
Report directory:
<WORKTREE_PATH>/packages/sdk/e2e/reports/<runId>/
Manual command block shape for POSIX shells:
export QVAC_PR_TEST_RUN_ID=pr-1234-abcdef0-t3-android
export QVAC_PR_TEST_REPORT_DIR=<WORKTREE_PATH>/packages/sdk/e2e/reports/$QVAC_PR_TEST_RUN_ID
mkdir -p $QVAC_PR_TEST_REPORT_DIR/logs
cd <WORKTREE_PATH>/packages/sdk/e2e
npm run install:build:full
npx qvac-test run:local:desktop --filter vision- --runId $QVAC_PR_TEST_RUN_ID --report-dir $QVAC_PR_TEST_REPORT_DIR
npx qvac-test run:local:android --filter vision- --runId $QVAC_PR_TEST_RUN_ID --report-dir $QVAC_PR_TEST_REPORT_DIR
Manual command block shape for PowerShell:
$env:QVAC_PR_TEST_RUN_ID = "pr-1234-abcdef0-t3-android"
$env:QVAC_PR_TEST_REPORT_DIR = "<WORKTREE_PATH>/packages/sdk/e2e/reports/$env:QVAC_PR_TEST_RUN_ID"
New-Item -ItemType Directory -Force "$env:QVAC_PR_TEST_REPORT_DIR/logs"
Set-Location "<WORKTREE_PATH>/packages/sdk/e2e"
npm run install:build:full
npx qvac-test run:local:desktop --filter vision- --runId $env:QVAC_PR_TEST_RUN_ID --report-dir $env:QVAC_PR_TEST_REPORT_DIR
npx qvac-test run:local:android --filter vision- --runId $env:QVAC_PR_TEST_RUN_ID --report-dir $env:QVAC_PR_TEST_REPORT_DIR
Agent-owned SDK setup and changed-example command shape for POSIX shells:
cd <WORKTREE_PATH>/packages/sdk
bun install
bun run build
bun run examples/<changed-example>.ts
Agent-owned SDK setup and changed-example command shape for PowerShell:
Set-Location "<WORKTREE_PATH>/packages/sdk"
bun install
bun run build
bun run examples/<changed-example>.ts
The user runs the e2e setup command and the qvac-test run:local:* commands. The agent may run changed examples separately only after the required SDK package-root install/build state exists or has been prepared without e2e npm auth.
Do not use script for log capture. It is not portable in this agent environment. For agent-run example steps, rely on terminal output. For user-run setup/e2e, rely on qvac-test's structured --report-dir output first; ask the user to paste terminal output only if setup fails before report files are produced or report files are missing/incomplete. Keep the --runId unchanged.
When the user says the commands finished:
<WORKTREE_PATH>/packages/sdk/e2e/reports/<runId>/ first. Prefer qvac-test's structured report files over terminal logs.For non-SDK packages, show the proposed command list and ask for approval before execution.
Each step must show:
cwdRun commands one at a time inside the worktree. Capture logs to:
<platform temp dir>/qvac-pr-test/pr-<num>/<package-name-or-path>/<step>.log
Abort on first non-zero exit unless the user explicitly opted into continuing after failures.
Before executing or asking the user to run anything, print:
## PR #<num> - test plan
Recommended tier: <tier>
Reason: <short reason>
Touched packages:
- `<path>` - <kind>, <summary of scripts/examples/tests>
Changed examples:
- `<path>` - runnable/not runnable
Related examples proposed:
- `<path>` - safe/needs input/writes output, include by default? <yes/no>
Related e2e filters proposed:
- `<filter>` - why
Proposed commands:
1. `<cwd>` - `<command>` - <why>
Manual-run required:
<yes/no; if yes, explain SDK e2e must be run by user>
After execution or log analysis, print:
## PR #<num> - test results
### Failed
<failures first, with log file paths and short error snippets>
### Passed
<passed steps>
### Not applicable
<examples/tests/mobile tiers skipped because absent>
Logs: `<path>`
.cursor/skills/_lib/pr-skills/worktree-prepare.mjs.cursor/skills/_lib/pr-skills/pr-test-discover.mjs.cursor/skills/_lib/pr-skills/pr-test-generic.mjs.cursor/skills/_lib/pr-skills/pr-test-sdk.mjs.cursor/skills/_lib/pr-skills/worktree.mjs.cursor/rules/sdk/e2e.mdcpackages/sdk/e2e/package.jsonpackages/sdk/e2e/README.mdGenerate changelogs for SDK pod packages using tag-based GitFlow. Use when preparing a release, generating changelog, or creating CHANGELOG_LLM.md.
Plans and scaffolds e2e tests in packages/sdk/e2e for a new or changed public SDK API. Use when adding or modifying SDK functionality that is exposed to consumers. Enforces happy / sad / error coverage, deterministic model-output assertions, mobile/desktop placement, smoke-suite selection, and local validation with run:local.
Catalog of all repo qv-* custom skills with one-line purpose and when-to-use. Use when the user asks what skills exist, which skill to use, how to invoke a skill, or invokes /qv-skill-list.
Release a package to NPM. Validates version bump, changelog, creates release branch, monitors CI, verifies publish.
Diagnose why CI checks are not running on a PR and/or why a PR cannot be merged, by cross-referencing the live PR state (via gh CLI) against the repo's labels, teams, CODEOWNERS, label-gate trust model, and tier-based approval rules. Read-only by default — proposes labels / re-review comments / unblock actions in plan-then-apply mode. Use when a developer asks "why aren't my checks running", "why can't I merge", "what's blocking my PR", or invokes /qv-devops-why-my-pr-not with a PR URL.
Generate changelog entries for a target add-on package. Use when preparing a new release.