Scenario Design

Turn a change spec into adversarial, real-life test scenarios — designed to break the system, not confirm it works. A scenario is only as good as it is concrete and executable. If the spec can't supply the concrete bits, that is a spec defect, surfaced as a clarification — not a guess.

Input: A change/feature spec. --change <name> (OpenSpec), or infer from context / point the skill at any spec doc. Mode: --stage proposal|design|apply (default: infer — see Gate). Output: a standalone test-plan.md catalog written to your change/spec's test-plan location (OpenSpec: openspec/changes/<name>/test-plan.md).

Core mechanism — the Triple

Every scenario MUST resolve three concrete slots:

   ┌─────────────┬──────────────────────┬────────────────────────────┐
   │  INPUT      │  TRIGGER             │  EXPECTED OBSERVABLE OUTCOME │
   │  concrete   │  the condition /     │  a measurable, visible fact  │
   │  data /     │  action that fires   │  (status, value, latency,    │
   │  state      │  the behaviour       │   DOM, log line, exit code)  │
   └─────────────┴──────────────────────┴────────────────────────────┘

Rule (from spec-coding edge-case practice): if any slot is a verb without a noun, or an adjective instead of a number, the slot is unfillable → spec gap. "Handles errors gracefully" is not a Triple. "POST /api/restart while server already restarting (input) → second caller (trigger) → receives 409 within 500ms, no second orchestrator spawned (observable)" is.

Stance: falsify, don't confirm. For each requirement, the job is to find the input+trigger that makes the observable wrong. Happy path is table stakes; the scenario value is in the boundaries and failures.

Phase 1 — Read the spec, classify requirements

1. Read what exists (OpenSpec layout shown; in a non-OpenSpec project read whatever spec/design/task docs the user points at — do not fail on a missing openspec/ dir or CLI):

   • openspec/changes/<name>/proposal.md (always)
   • openspec/changes/<name>/design.md (if present — decisions, invariants)
   • openspec/changes/<name>/specs/**/spec.md (requirement deltas)
   • openspec/changes/<name>/tasks.md (if present — to align section numbers)

2. Extract every testable requirement (each SHALL/MUST, each scenario block, each acceptance criterion). For each, tag its shape — this picks the technique:

   Requirement shape	Technique to apply	Scenario class
   Input range / numeric / size / count	Equivalence Partitioning + Boundary Value Analysis	edge-case
   Multiple boolean/enum flags combine	Decision Table	edge-case
   Lifecycle / status transitions / reconnect / restart	State-Transition	frontend-quirk + error-handling
   Async / WebSocket / polling / optimistic UI	State-convergence + invariant assertions (not UI-visibility)	frontend-quirk
   Latency / throughput / memory / long-run	tail-latency (p95/p99) + soak + threshold	performance
   Depends on network / disk / subprocess / other service	fault injection (delay + abort)	error-handling

   See references/technique-cheatsheet.md for how to apply each.

Phase 2 — Generate scenarios via the Triple (or a gap)

For each requirement, walk its technique and try to emit one or more Triples.

• EP+BVA: emit min, just-below-min (invalid), nominal, just-below-max, max, just-above-max (invalid). Six Triples from one numeric requirement.
• Decision table: one Triple per reachable flag combination; mark impossible combos.
• State-transition: one Triple per legal edge AND per illegal edge (event fired in a state that shouldn't accept it).
• Async/convergence: assert the eventual invariant and the intermediate states, never "element is visible after N ms".
• Performance: state the workload, the metric (p95/p99/RSS), the threshold, and the measurement window. No threshold in spec → gap.
• Fault injection: for each dependency, a delay Triple and an abort Triple; assert retry/timeout/degradation behaviour.

When a slot won't fill → STOP generating that scenario. Record a gap with the unfillable slot named (see Gate). Do not invent the missing value.

Phase 3 — The clarification Gate (configurable)

Whether an unfillable Triple blocks or just annotates depends on stage:

   stage = proposal | design   →  HARD gate
   stage = apply               →  SOFT gate
   (no --stage)                →  infer: tasks.md absent ⇒ proposal/design (hard)
                                          tasks.md present ⇒ apply (soft)

• HARD gate: collect all gaps, then call ask_user with decision-forcing questions and STOP. Do not write test-plan.md until answered. The spec is not yet testable; clarify before locking scenarios.
• SOFT gate: write the scenario row with a [NEEDS CLARIFICATION: <slot> — <question>] marker, continue, and list all markers in a banner at the top of test-plan.md.

Decision-forcing question rules (from ambiguity-detection practice):

• Name the missing slot and why it blocks a scenario.
• Offer concrete candidate answers, never propose a solution/implementation.
• One question per genuine decision; do not pad.

Example: "Restart quiesce window: tasks say bridges 'suppress auto-start for the quiesce window'. To test the boundary I need the exact value — is it 5s (restart) / 60s (shutdown) per AGENTS.md, or spec-defined elsewhere? Without a number I cannot write the just-after-window re-spawn scenario."