qa-router v1.0.0A

Immutable. This exact content is served forever at /api/v1/blob/d644f9e92b2d2a8a.

---
name: qa-router
description: "Validation routing and test-failure triage for any repository. Use to select the right gates, author deterministic tests, reproduce CI failures, or diagnose flaky suites."
license: MIT
metadata:
  version: "1.0.0"
  companion-skills:
    - vitest-dev
    - pytest-dev
    - bun-dev
---

# 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

```markdown
## 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.