draft-verification-scenarios

name	draft-verification-scenarios
description	Create a scenarios.yaml artifact with grouped scenarios, feature back-links, feature gates, and coverage summary from a features specification
user-invocable	false
model	sonnet
allowed-tools	Read, Write
deprecated	true
deprecated_note	#434 ProductOS realignment — superseded by the command model; retained for Phase E reference, not installed

draft-verification-scenarios

Model-invocable skill for creating verification scenario specifications as structured YAML.

Purpose

Transform a features specification into a structured scenarios.yaml artifact. Every feature behavior in the spec must map to at least one scenario -- full traceability, no gaps. Scenarios back-link to features; features never link back to scenarios.

You DO create the scenarios.yaml artifact. You do NOT validate it, execute the scenarios, or decide what happens next.

Output Schema

The output MUST conform to schemas/scenarios.yaml in this skill's directory. Read the schema before producing output. Every field defined in the schema must be present in the output YAML. The schema is the contract — if it's in the schema, it's in the output.

Input

Receive from agent:

• features_yaml_path — (required) Path to features.yaml
• output_base — (required) Base path for output (e.g., .garura/product/roadmap/)

Process

1. Determine artifact path: {output_base}/scenarios.yaml

2. Read and parse features specification: Read features.yaml at features_yaml_path. Extract:

   • Every feature (F1, F2, ...) with its name, description, behaviors, success_scenarios, and failure_conditions
   • Architectural invariants from features.yaml
   • Scope boundaries (in_scope items that imply testable behavior)

3. Build traceability map: For each feature and each behavior within it (F{N}-B{N}), record the feature ID, behavior ID, and behavior description. This map drives scenario generation -- every behavior entry must produce at least one scenario. Invariants that are testable must also produce scenarios.

4. Plan scenario groups: Organize scenarios by feature area. Each group mirrors a feature or a cluster of related features. Assign a group ID prefix in the format GRP-{NAME} (e.g., GRP-AUTH, GRP-PAYMENTS, GRP-CORE). Each group lists the feature_refs it covers.

5. Generate scenarios: For each entry in the traceability map, produce one or more scenarios. Each scenario must conform to the scenarios.yaml schema:

   • id — SC-{GRP}-{NNN} format, zero-padded 3 digits (e.g., SC-AUTH-001, SC-PAY-003)
   • title — short descriptive title
   • feature_ref — back-link to specific feature ID (e.g., F1) -- REQUIRED
   • behavior_ref — back-link to specific behavior ID (e.g., F1-B1) -- include when scenario covers a named behavior; omit only for invariant-level scenarios
   • description — concrete situation being tested, not abstract
   • expected_behavior — list of observable outcomes the system should produce
   • pass_criteria — explicit, binary conditions that determine pass or fail; no ambiguity
   • automation — automated or hybrid
   • test_type — unit | integration | e2e | acceptance
   • manual_element — (hybrid only) what the human evaluates and why the machine cannot

   Automation classification rules:

Output

scenarios_yaml:
  path: "{full path to scenarios.yaml}"
  scenarios_yaml_path: "{full path to scenarios.yaml}"
  total_count: {number}
  automated_count: {number}
  hybrid_count: {number}
  groups:
    - id: "GRP-{NAME}"
      name: "{group name}"
      feature_refs: ["F1"]
      count: {number}
  coverage: "full"
  uncovered_features: []
  uncovered_behaviors: []
  status: "DRAFT"

IMPORTANT: This skill produces an artifact and returns metadata. The calling agent receives this output and decides what to do next. Do NOT instruct the agent to return or stop.

Constraints

COMPARTMENTALIZATION

• scenarios.yaml is VALIDATOR-FACING. It must never be shared with or referenced by code-builder agents.
• Scenarios know about features (back-links via feature_ref and behavior_ref). Features NEVER link to scenarios.
• feature_gates in this artifact serve as the authoritative mapping for validators -- which scenarios gate each feature.

SCENARIO QUALITY

• NEVER produce a scenario without all required fields (id, title, feature_ref, description, expected_behavior, pass_criteria, automation, test_type)
• NEVER classify a scenario as automated if it requires subjective quality judgment -- use hybrid
• NEVER classify a scenario as hybrid without documenting the manual_element
• NEVER leave a feature behavior uncovered -- every behavior in features.yaml must have at least one scenario
• ALWAYS use SC-{GRP}-{NNN} ID format with zero-padded three-digit numbers
• ALWAYS organize scenarios into groups that mirror features.yaml feature areas

ARTIFACT RULES

• NEVER overwrite a LOCKED scenarios.yaml -- return structured failure
• ALWAYS set status: DRAFT in the written artifact
• ALWAYS include feature_gates section with an entry for every feature in features.yaml
• ALWAYS ensure uncovered_features and uncovered_behaviors are empty before writing
• Audience is validators (quality-validator agent, human QA) -- scenarios must be independently testable without implementation knowledge

Version

Field	Value
Version	2.0.0
Category	analysis