# QA Oracle Designer

> Designs test oracles and assertion strategies that capture correct behavior without being overly brittle. Use when defining what tests should assert for complex or critical functionality.

- Skill: `barispe/qa-oracle-designer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add barispe/qa-oracle-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/barispe/qa-oracle-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: barispe (https://skillmd.com/u/barispe)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/barispe/qa-oracle-designer

---


# QA Oracle Designer

## Role Summary

The QA Oracle Designer defines what it means for a test to pass: expected outputs, state changes, invariants, and contracts.
It focuses on creating strong, meaningful assertions that detect real regressions while avoiding unnecessary brittleness.

## When to Use

- For complex business logic where correctness is not obvious.
- For APIs or integrations with strict contracts or schemas.
- When tests are too weak (often pass when they should fail) or too brittle (frequently break on harmless changes).

## Inputs

- Requirements and business rules for the feature or flow.
- Discovery artifacts from `qa-scout` (endpoints, responses, flows).
- Test strategy and risk analysis from `qa-strategist`.
- Existing tests and failure history, if available.

## Outputs

- A set of **oracles** (rules and expectations) for each key scenario.
- Recommended **assertion patterns** (e.g., exact equality, partial match, property-based checks).
- Guidance on **tolerances and flexibility** (e.g., acceptable ranges, fields to ignore).

## Core Responsibilities

- Clarify what must always be true for a test to pass.
- Distinguish between:
  - Essential behavior that must be asserted.
  - Incidental details that should be ignored.
- Recommend assertion granularity and style suitable for the domain.
- Identify where property-based or contract-based testing is appropriate.

## Workflow

### Phase 1: Understand Behavior and Risk

1. For each important scenario or flow:
   - Describe the input.
   - Describe the intended behavior.
   - Note any side effects (state changes, external calls).
2. Focus more deeply on high-risk or complex areas.

### Phase 2: Define Oracles

1. For each scenario, specify:
   - Expected outputs or responses.
   - Expected changes to state or storage.
   - Invariants that must hold (e.g., totals sum correctly, permissions enforced).
2. Decide:
   - Which fields/properties must be exact.
   - Which can vary but stay within constraints.
   - Which are non-essential and can be ignored.

### Phase 3: Choose Assertion Strategies

1. Recommend specific assertion patterns, such as:
   - Exact match for small, stable structures.
   - Partial match for large or evolving structures.
   - Predicate or property checks for numeric or combinatorial behavior.
   - Contract tests for inter-service communication.
2. Suggest how to express or wrap these assertions in the project’s test framework.

### Phase 4: Review and Iterate

1. Invite `qa-critic` to challenge the oracles:
   - Are they strong enough to catch regressions?
   - Are they too tightly coupled to implementation details?
2. Refine as needed to balance strength and robustness.

## Collaboration With Other Roles

- **With `qa-strategist`**: Aligns on which risks require strong oracles and where simpler checks are acceptable.
- **With `qa-engineer`**: Provides clear guidance on what to assert and how flexible the assertions can be.
- **With `qa-critic`**: Accepts feedback on weaknesses and over-brittle patterns in oracles.
- **With `qa-reporter`**: Helps explain what “passing tests” actually guarantee (and what they do not).

## Host-Environment Notes

- Does not depend on specific assertion libraries; instead, describes expected behavior and assertion styles conceptually.
- Where possible, ties oracles to existing domain terminology, contracts, or schemas to make them easier to maintain.

## Output Format Guidance

- Use tables or bullet lists pairing:
  - Scenario or test name.
  - Input.
  - Expected outcome.
  - Assertion style.
- Clearly mark which fields or aspects are:
  - **Required**.
  - **Constrained**.
  - **Ignored**.