Qv PR Test

PR Test

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:

1. Discover package-local setup, examples, tests, and related validation targets from committed PR state.
2. Present a recommended tier plus any related examples/tests as part of the same proposal.
3. Execute agent-owned steps inside the isolated PR worktree when safe.
4. For validation that must be user-run, print exact commands and inspect reports/logs afterward.

When to use this skill

Use when:

• User asks to test a PR or provides a PR URL for validation.
• User invokes /qv-pr-test.
• A PR review/status flow needs local verification before reviewers are pinged.

Inputs

• Required: PR URL, e.g. https://github.com/tetherto/qvac/pull/1234.
• Optional: user focus area, preferred mobile platform (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.

Safety rules

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 restore
• git stash, git pull, git merge, git rebase, git cherry-pick
• git clean
• gh pr checkout
• Any package manager, build, or test command

Worktree carve-out

The 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.

Workflow

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

0a. Prepare worktree

Run:

node .agents/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:

• Fetch/read files via GitHub API if needed.
• Let pr-test-discover.mjs fetch the patch with gh pr diff --patch into the platform temp directory when PATCH_PATH is unavailable.
• Tell the user that worktree preparation failed and local command execution is unavailable unless they want to retry.

0b. Discover test options

Run:

node .agents/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.recommendedTier
• recommendation.recommendationReason
• touchedPackages[]
• touchedPackages[].scripts
• touchedPackages[].commands
• touchedPackages[].addedOrModifiedExamples
• touchedPackages[].exampleCommands
• touchedPackages[].relatedExampleCommands
• touchedPackages[].addedOrModifiedTests
• touchedPackages[].relatedTests
• touchedPackages[].sdkE2eSetup — on the SDK package, and also on packages/inference if it's touched (a local inference build only reaches e2e through the SDK's setup, not a standalone inference build)

Discovery 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.

Tier Ladder

All tiers include necessary install/build setup for the touched package roots.

• T1 - examples: run package-root install/build setup, then added/modified examples. If no examples were added or modified, mark the examples step not applicable.
• T2 - changed e2e/tests on desktop: SDK runs changed e2e tests on desktop. Non-SDK runs the smallest unit-level package script (test:unit or test), or first available test:*.
• T3 - changed e2e/tests on mobile: SDK adds changed e2e on selected mobile platform (android or ios). Non-SDK uses mobile scripts only if package.json exposes them.
• T4 - smoke desktop: SDK runs --suite smoke on desktop. Non-SDK advances to the next least-to-most-complete script if one exists.
• T5 - smoke mobile: SDK runs --suite smoke on selected mobile platform. Non-SDK uses mobile scripts only if package.json exposes them.
• T6 - full desktop: SDK runs the full desktop suite. Non-SDK runs test:all if present, otherwise all applicable test:* scripts in increasing completeness order.
• T7 - full mobile: SDK runs the full selected mobile suite. Non-SDK uses mobile/full scripts only if package.json exposes them.

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.
• Example: a transcription SDK change should propose transcription examples and the 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.

Recommendation policy

Always show the recommendation before the tier prompt. The user can override it.

• SDK (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.
• Non-SDK default: recommend the smallest tier that includes at least unit-level validation. Usually T2.
• packages/inference touched: discovery attaches sdkE2eSetup / sdkE2eCwd to it, but inference has no e2e or examples of its own, so the non-SDK default above would leave the setup command with nothing to run after it. Pair it with an SDK e2e run in sdkE2eCwd and recommend T4 (--suite smoke on desktop) — that is what CI runs for an inference change, and with no changed e2e files T2 has no filter to work from. If the PR also touches packages/sdk/e2e, use that package's changed tests / relatedTests filter instead.
• No examples: if no changed or related examples are discovered, mark examples not applicable.
• No tests discovered: recommend install/build only and ask the user to confirm build-only validation.
• Mixed PRs: recommend the highest minimum required by any touched package. Example: SDK + addon changes means SDK T3 plus addon unit scripts.

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.