Wio

WIO

WIO is one testing workflow skill with five command modes:

• scan: find the highest-value test candidates for a codebase, change, or scope.
• test: write one focused high-value test for a selected behavior, code path, or regression risk.
• workload: generate a realistic, adversarial workload that adds a new failure surface, oracle, sequence, or coverage dimension with controlled variance, replay, and correctness invariants.
• review: review a newly written or existing test for customer value, developer value, signal quality, and maintainability.
• doctor: diagnose test-suite health problems in a codebase or scope.

Commands are accessed through $wio:

Use references/index.md to route from code evidence and candidate failure modes to the right strategy references.

Reference Loading

Do not pick a test strategy from memory or from the nearest existing test alone. First inspect the target code, public behavior, existing tests, fixtures, and test commands. Then identify candidate behaviors or workloads and their likely failure mechanisms. Only after candidates exist, load the references needed to choose the strategy.

For every selected candidate, load at least one strategy reference that matches the failure mechanism before recommending or writing a test:

• Load Risk-Based Testing when priorities, customer impact, security/business risk, or limited test capacity decide what comes first.
• Load User Behavior Testing when the behavior is a user journey, product workflow, API consumer flow, or operator task.
• Load Test Level Selection before choosing unit, component, integration, contract, E2E, workload, synthetic, or monitoring coverage.
• Load Test Oracles And Assertions before writing or reviewing assertions, invariants, snapshots, workload checks, or any test whose failure signal is unclear.
• Load Test Data And Fixtures when state setup, seeds, factories, cleanup, permissions, or data realism affect signal.
• Load Mocking And Test Doubles when a mock, fake, stub, emulator, or real dependency decision could change what risk is preserved.
• Load Test Feedback Loops when choosing local, PR CI, nightly, release, canary, synthetic, or production-monitoring placement.
• Load specialized references only when the fault mechanism calls for them: property-based testing for broad deterministic input spaces, fuzzing for parsers/untrusted input, mutation testing for weak assertions, performance testing for latency/saturation, resilience testing for dependency failure, security testing for abuse or tenant/auth risk, static analysis for code/config-shape defects, and regression selection when the full suite is too slow.

For commands and repo signals in a topic, load the sibling tools.md after the matching overview.md shows that topic is relevant. State which reference files informed the chosen strategy.

Command Selection

Use scan when the user asks what to test next, where coverage would matter, how to prioritize testing work, or which tests would reduce user, production, support, or team risk.

Use test when the user asks to add a test, improve a specific test, cover a bug, or validate a change with a meaningful automated test.

Use workload when the user asks for a realistic user-session workload, scenario generator, traffic model, load/performance scenario, browser journey mix, synthetic user flow, or varied workload that still preserves a stable task goal.

If the user asks to generate a workload, treat existing workloads as evidence and reusable infrastructure, not as the deliverable. A generated workload must add at least one new failure surface, adversarial class, oracle/invariant, state model, dependency fault, user/session path, or coverage dimension. A wrapper, runner, seed sweep, parameter expansion, or documentation-only change around an existing workload is not a generated workload unless the user explicitly asked for a runner or the wrapper adds a new oracle or adversarial model.

Use review when the user asks whether a test is worth keeping, asks for test review, or after $wio test writes or changes a test.

Use doctor when the user asks to audit tests, review suite quality, find flaky or low-value tests, inspect CI test health, or explain why a test suite is slow, noisy, or low-signal.

If the user explicitly names a WIO command, follow that mode. If the command is omitted, infer the mode from the request. If no command or target is provided, show the command table and ask what they want to do. If multiple modes apply, start with scan before test or workload, and use doctor only for existing suite health.

Shared Rules

• Protect meaningful behavior, not coverage numbers.
• Ask what could go wrong before asking what already broke; use that answer to choose tests while the design is still cheap to change.
• Establish product, user, production, support, debugging, review, or release risk before recommending or writing tests.
• Prefer targets where bugs usually occur: boundaries, permissions, state transitions, persistence, external dependencies, concurrency/time, validation/parsing, migrations, configuration, caching, retries/idempotency, UI workflow joins, and recent churn.
• A test is valuable only if it would catch a meaningful regression, save developer time, improve release confidence, or expose a real operational/customer failure mode.
• Before keeping a test or workload, name at least one plausible bug it would catch and the assertion or invariant that would fail.
• Prefer assertions and invariants that encode the mental model of the behavior, including valid cases, invalid cases, and boundary transitions between them.
• Prefer repo-native frameworks, helpers, fixtures, commands, and naming.
• Choose the narrowest test level that preserves the real failure mechanism.
• Read code and tests before choosing strategy; load targeted references after candidate failure modes are known.
• State evidence inspected, commands run, commands not run, and residual risk.
• Mark low-value tests REDO or REMOVE, not KEEP.

Gotchas

• Do not write or keep tests just to increase coverage. Covered code with weak assertions is false confidence.
• Do not mock away the boundary, state, permission, timing, data, or dependency behavior that creates the real risk.
• Do not accept broad snapshots unless the reviewed snapshot is the protected contract and the update path is disciplined.
• Do not use a full-suite command when a smaller command validates the changed behavior with the same signal.
• Do not weaken assertions to fix flakes. First look for nondeterminism, shared state, timing, retries, order dependence, or external services.
• Do not treat green CI as proof the test is valuable. The question is whether the test would fail for the meaningful regression.
• Do not accept tests or workloads that only prove completion, truthiness, object existence, status 200, broad snapshot equality, or mock call counts unless that weak signal is explicitly the protected contract.
• Do not present a thin wrapper around an existing workload as $wio workload generate. If the change only reruns, parameterizes, documents, or sweeps an existing workload, call it a runner and explain the missing new failure surface.
• Do not let subagents write tests or make the final value decision; the main agent owns edits and the final KEEP, REDO, or REMOVE.

Available Scripts

• scripts/test-review-reminder.py: hook helper that reminds the active agent to validate and apply $wio review after test files change.
• scripts/check-wio-report.py: optional checker for saved markdown reports. Use python3 scripts/check-wio-report.py review report.md when a WIO output is written to a file and you need a quick structure check.

Subagent Workflow

When the host supports subagents or parallel agents and user/host policy permits them, use the WIO subagent specs from the official host locations to improve quality without duplicating guidance:

• wio-candidate-scout: read-only discovery of high-value test candidates and real risk.
• wio-strategy-critic: read-only challenge of the chosen test level, oracle, doubles, fixtures, and validation loop before implementation.
• wio-test-reviewer: post-implementation review that returns KEEP, REDO, or REMOVE.

Subagents must inspect targeted code and tests before loading targeted WIO references. They return findings to the main agent; they do not write reports or copy reference content. Claude plugin subagents live in plugins/wio/agents/; Claude project subagents can live in .claude/agents/; Codex custom agents live in .codex/agents/. Installing WIO with skills add does not create those runtime files.

For $wio test, use this sequence:

1. Inspect the repo and target code: public behavior, changed paths, existing tests, fixtures, commands, dependencies, state, side effects, and boundaries.
2. Discover valuable candidates from behavior, risk, bug-prone areas, existing coverage gaps, and code evidence. Use wio-candidate-scout if available.
3. Load the references that match the selected candidate's failure mechanism, then pick the strategy: test level, oracle, fixture/data setup, doubles, adversarial edge coverage, and validation command.
4. Use wio-strategy-critic to challenge the proposed strategy before editing when available.
5. Write one focused test in the main agent, using repo-native patterns.
6. Validate with the smallest relevant command.
7. Review the written test. Use wio-test-reviewer if available.
8. Keep the test only if review returns KEEP; otherwise revise (REDO) or remove (REMOVE).

If subagents are unavailable, perform the same stages in the main agent and explicitly label the review stage.