Agent Skills: QA Router

QA Router

Route validation work through the repository's actual test and CI contracts. Use this skill to choose gates, write deterministic tests, reproduce CI, and triage flakes without inventing a parallel testing workflow.

First Reads

Before invoking a runner or editing configuration, read:

1. root and nested AGENTS.md or equivalent contributor instructions;
2. README.md, testing docs, and setup/runbook prerequisites;
3. root and relevant package package.json scripts or language task config;
4. CI workflow files and validation/routing manifests;
5. runner configuration, test setup, fixtures, and the nearest existing tests.

Discover the repository's package manager and task runner. Do not assume Bun, npm, uv, Cargo, Make, or another tool from file extensions alone.

Rules

• Prefer repository scripts over raw runner binaries. Scripts may own env, project selection, code generation, sharding, setup, or cleanup.
• Start with the narrowest command that reproduces the changed behavior or failure, then run the wider gate selected by touched files and CI policy.
• A command not run is UNVERIFIED, never passed.
• Tests must be deterministic: no live providers, wall-clock sleeps, order dependence, uncontrolled randomness, or shared mutable leakage.
• Do not add test-only branches, flags, or exports to production code. Extract a real pure seam only when it improves production design too.
• Test behavior and contracts, not incidental implementation details.
• Restore mocks, timers, environment, network interception, files, databases, and global state after each test.
• Never weaken an assertion, add retries, serialize a suite, or increase a timeout until the nondeterminism is understood.
• Official runner docs and source are authority for configuration or current API behavior. Refresh them through context7-research or opensrc when installed (otherwise use the runner's local docs, --help, and source); use deep-researcher only for broader, evidence-heavy uncertainty.
• Preserve authorization, denied-path, tenant/account-isolation, destructive, migration, and public-contract coverage.

Lanes

Gate selection

Read references/validation-routing.md. Map touched files and risk to the repository's named lint, format, type, unit, integration, E2E, build, docs, security, generated-output, platform, and release gates. Never derive a new matrix when the repo already owns one.

Test authoring

• Read neighboring tests and runner setup before adding a file.
• Use the existing naming, project, environment, fixture, and location rules.
• Build minimal deterministic fixtures with explicit identities, time, random seeds, locale, timezone, and network boundaries when relevant.
• Cover the success path plus the material denial, invalid-input, empty/error, retry/idempotency, and cleanup behavior introduced by the change.
• Prefer public behavior or stable boundary assertions over private calls and snapshots of irrelevant markup.
• For browser tests, wait for user-visible state or network completion rather than sleeping. Keep auth and storage state generated by repository tooling.
• For integration tests, use local emulators/fakes/transactional fixtures; do not mutate live services.

CI reproduction

1. Capture the exact workflow, job, step, command, environment, shard/project, runner version, and first actionable error.
2. Reproduce the owning script locally with equivalent committed config.
3. Match CI-specific environment only as needed; never print secrets.
4. Separate code failure from missing prerequisite, platform drift, generated output drift, resource pressure, and provider outage.
5. Patch the verified cause, rerun the narrow command, then rerun the owning CI gate or closest safe local equivalent.

Flake triage

Read references/failure-triage.md and classify evidence before fixing:

• Timing: race, fake-timer misuse, animation/eventual state, missing await.
• Order: state leaked between tests or suite-order assumptions.
• Parallelism: shared ports/files/database rows, unsafe global fixtures, resource contention, or shard collisions.
• Network: uncontrolled request, provider variability, DNS/rate limit, or incomplete interception.
• Leak: timers, processes, handles, DOM, mocks, environment, files, or DB state survive cleanup.

Retries are diagnostic evidence, not a default fix.

Companion Routing

• vitest-dev for Vitest architecture, projects, fixtures, performance, and flakes.
• pytest-dev for pytest fixtures, markers, parametrization, speed, and flakes.
• bun-dev for Bun-native test/runtime behavior and Bun repository posture.
• context7-research for current official library/runner documentation.
• opensrc for implementation details, package internals, and version diffs.
• deep-researcher for broad, cited investigation across multiple authorities.

Load only the companion required by the discovered stack.

Failure Procedure

1. Record the exact failure and first actionable error.
2. Reproduce with the narrowest owning command.
3. Classify the failure and test the leading hypothesis.
4. Read the owning script, config, setup, fixture, and production boundary.
5. Patch only the verified cause.
6. Rerun the narrow reproduction until stable.
7. Stress the suspected flake dimension when appropriate: repeat, randomize order, vary workers/shards, or check leaked handles using supported options.
8. Run the wider gate selected by touched files and CI policy.
9. Report commands, results, skipped gates, and residual UNVERIFIED gaps.

Severity

• HIGH: required gate failure; missing proof for security/data/public contract behavior; deterministic reproduction of a release-blocking defect; or a flake that makes required CI untrustworthy.
• MEDIUM: meaningful coverage, isolation, speed, or CI-parity weakness that risks regressions but does not currently block the required gate.
• LOW: localized test clarity or maintenance issue with bounded risk.

Review Output Format

## QA Report
- Scope and touched risk:
- Repository authorities read:
- Selected gates and why:
- Failure reproduction / tests authored:
- Root cause and classification:
- Files changed:
- Narrow verification:
- Wider verification:
- Skipped gates and why:
- Flake confidence:
- UNVERIFIED gaps:

Do not report a flake fixed from one passing rerun. State the repetition or stress evidence used and the remaining confidence limit.