gh-dgomezs-claude-code-plugins-tdd-specflow/commands/test-scenarios.md

allowed-tools, argument-hint, description

allowed-tools	argument-hint	description
Task(*), Read(*), Glob(*), Write(*), Edit(*), Bash(mkdir:*)	<task-directory> [operation-prompt]	Create or manage test scenarios from requirements.md using the qa-engineer agent. Supports creating, adding, modifying, or discovering scenarios.

Test Scenarios Command

Execute test scenario creation or management for: $ARGUMENTS

Overview

This command creates and manages test scenarios from a requirements.md file containing high-level acceptance criteria.

It orchestrates scenario generation by:

1. Determining what operation to perform (create all, add one, modify one, discover gaps)
2. Reading requirements.md and preparing context
3. Calling qa-engineer agent to generate scenario content
4. Handling all file operations (writing, numbering, organizing, linking)

The qa-engineer agent ONLY generates scenario content. This command handles everything else.

Step 1: Parse Arguments and Determine Operation

Operation Detection

Analyze $ARGUMENTS to determine the operation:

EXPAND Mode - Create comprehensive scenarios from requirements.md:

• Single argument: directory path containing requirements.md
• Example: /test-scenarios apps/feature/task-001/

ADD Mode - Add single scenario to existing set:

• First argument: directory path
• Second argument contains "add"
• Example: /test-scenarios apps/feature/task-001/ "add scenario for null input to AC-1"

MODIFY Mode - Edit existing scenario:

• First argument: directory path
• Second argument contains "modify" or "edit"
• Example: /test-scenarios apps/feature/task-001/ "modify scenario 1.2 to test empty string"

DISCOVER Mode - Find gaps in existing scenarios:

• First argument: directory path
• Second argument contains "discover" or "gaps"
• Optional: Tag additional context files (e.g., @research.md, @tech-design.md) for deeper analysis
• Example: /test-scenarios apps/feature/task-001/ "discover gaps"
• Example with context: /test-scenarios apps/feature/task-001/ "discover gaps" @research.md @tech-design.md

DELETE Mode - Remove a scenario:

• First argument: directory path
• Second argument contains "delete" or "remove"
• Example: /test-scenarios apps/feature/task-001/ "delete scenario 1.3"

Step 2: Gather Context

All modes use requirements.md as the base input containing high-level acceptance criteria.

Read relevant files from the task directory:

For EXPAND Mode:

Required:
- <directory>/requirements.md (high-level acceptance criteria)

For ADD/MODIFY/DISCOVER/DELETE Modes:

Required:
- <directory>/requirements.md (high-level acceptance criteria - for context)
- <directory>/scenarios.md (existing scenarios with implementation tracking)
- <directory>/test-scenarios/*.md (existing scenario details)

Optional (if tagged in user prompt):
- Any additional context files (research.md, tech-design.md, code files, etc.)
- These provide deeper context for scenario discovery and analysis

Step 3: Prepare Agent Request

Based on operation mode, formulate a simple request for qa-engineer:

EXPAND Mode Request:

Generate comprehensive test scenarios for these acceptance criteria:

[paste requirements.md content - high-level acceptance criteria]

Generate multiple scenarios per acceptance criterion, ordered by implementation priority.

ADD Mode Request:

Generate ONE scenario for AC-[N] to test: [specific behavior]

Acceptance Criterion:
[AC-[N] from requirements.md]

Existing scenarios for AC-[N]:
[list existing scenarios with names only]

Check for duplicates against existing scenarios.

MODIFY Mode Request:

Modify scenario [N.M]:

Current scenario:
[paste current scenario]

Current implementation progress: [checkboxes state]

Requested change: [what user specified]

Preserve structure and warn if existing tests/implementation may need updates.

DISCOVER Mode Request:

Analyze existing scenarios for gaps and generate NEW scenarios to fill those gaps.

Acceptance Criteria:
[paste all ACs from requirements.md]

Existing Scenarios:
[paste organized list of scenarios by AC with their types]

[IF additional context files were tagged, include them here:]
Additional Context:

[For each tagged file, include a section:]
File: [filename]
[paste file content]

[Repeat for all tagged files]

Generate new scenarios to fill any gaps. If no gaps found, return: "No gaps found - coverage is complete"

Step 4: Invoke qa-engineer Agent

Use Task tool to launch qa-engineer with the prepared request:

Task: qa-engineer
Description: Generate test scenario content

[Paste the request from Step 3]

The agent is the QA domain expert. It will:

• Ask clarification questions if needed (wait for answers)
• Apply its QA heuristics automatically
• Assign scenario types and priorities based on QA expertise
• Generate scenario content in Given-When-Then format
• Return structured JSON with scenarios, warnings, and optional context requests

Expected JSON Response:

{
  "scenarios": [...],
  "warnings": {
    "duplicates": [...],
    "gaps": [...],
    "implementation_impact": [...]
  },
  "context_requests": [...]  // Optional, for DISCOVER mode
}

Handle Context Requests (DISCOVER mode only): If agent returns context_requests array:

1. Read each requested file
2. Append to the original request with section: "Additional Context:\n[file content]"
3. Re-invoke agent with updated request
4. Repeat until agent returns scenarios or "No gaps found"

Step 5: Common File Operations

All modes (except DELETE) use these common operations after receiving agent JSON output.

5.1: Parse Agent JSON Response

const response = JSON.parse(agent_output);
const scenarios = response.scenarios || [];
const warnings = response.warnings || {};
const contextRequests = response.context_requests || [];

5.2: Display Warnings

if (warnings.duplicates?.length > 0) {
  Display: ⚠️  Duplicate warnings: [list warnings.duplicates]
}
if (warnings.gaps?.length > 0) {
  Display: ℹ️  Identified gaps: [list warnings.gaps]
}
if (warnings.implementation_impact?.length > 0) {
  Display: ⚠️  Implementation impact: [list warnings.implementation_impact]
  Display: "Review existing tests/code for needed updates"
}

5.3: Write Scenario Content to Type File

For any scenario that needs to be written or updated:

# Determine target file from scenario.type:
target_file = test-scenarios/{scenario.type}.md
# Where scenario.type is one of: "happy-path", "error-case", "edge-case"

# Write scenario.content exactly as received from agent:
[Paste scenario.content]

# Agent's content includes:
# - ## Scenario N.M: [Name] heading
# - Proper blank lines (MD022/MD032 compliance)
# - Trailing --- separator

5.4: Update scenarios.md Tracking

For any scenario that needs tracking entry:

### Scenario N.M: [scenario.name]
- **Type**: [scenario.type]
- **Details**: [test-scenarios/{scenario.type}.md#scenario-nm](test-scenarios/{scenario.type}.md#scenario-nm)
- **Implementation Progress**: [ ] Test Written [ ] Implementation [ ] Refactoring

Important: When modifying existing entry, PRESERVE checkbox states.

5.5: Determine Next Scenario Number

When adding new scenarios, find the next available number for an AC:

# Read scenarios.md
# Find all scenarios for the target AC (e.g., "AC-2")
# Find highest number (e.g., if 2.1, 2.2, 2.3 exist → next is 2.4)
# Return next_number

Step 6: Mode-Specific Workflows

After receiving JSON output from qa-engineer, perform mode-specific operations:

For EXPAND Mode:

Creates all scenario files from scratch.

Your tasks:

1. Use Step 5.1 to parse JSON response

2. Use Step 5.2 to display warnings

3. Group scenarios by type:

   • Filter scenarios where type === "happy-path" → happy-path.md
   • Filter scenarios where type === "error-case" → error-cases.md
   • Filter scenarios where type === "edge-case" → edge-cases.md

4. Create directory:

   mkdir -p <directory>/test-scenarios
   

5. Assign scenario numbers:

   • Group scenarios by acceptance_criterion field (e.g., "AC-1")
   • Sort within each AC by priority field (1, 2, 3...)
   • Assign numbers: AC-1 → 1.1, 1.2, 1.3...; AC-2 → 2.1, 2.2...
   • Agent determines priority (happy-path first, then error-case, then edge-case)

6. Write type files with headers:

   happy-path.md:

   # Happy Path Scenarios
   
   Valid inputs and successful outcomes that represent typical user workflows.
   
   ---
   
   [For each happy-path scenario, use Step 5.3 to write scenario.content]
   

   error-cases.md:

   # Error Case Scenarios
   
   Invalid inputs and failure conditions.
   
   ---
   
   [For each error-case scenario, use Step 5.3 to write scenario.content]
   

   edge-cases.md:

   # Edge Case Scenarios
   
   Boundary values, limits, and unusual but valid conditions.
   
   ---
   
   [For each edge-case scenario, use Step 5.3 to write scenario.content]
   

7. Create scenarios.md with tracking:

   # Test Scenarios
   
   [For each AC in requirements.md:]
   ## AC-N: [Title from requirements.md]
   
   **Source**: [requirements.md#ac-n](requirements.md#ac-n)
   
   [For each scenario for this AC, use Step 5.4 to create tracking entry]
   

For ADD Mode:

Adds one new scenario to existing set.

Your tasks:

1. Use Step 5.1 to parse JSON (get scenarios[0] as the single scenario)

2. Use Step 5.2 to display warnings

3. Check for duplicates - if warnings.duplicates is not empty:

   Ask user: "Proceed anyway? (yes/no)"
   If no, abort
   

4. Use Step 5.5 to determine next scenario number for the AC

5. Use Step 5.3 to append scenario.content to appropriate type file

6. Use Step 5.4 to add tracking entry to scenarios.md under the AC section

7. Display confirmation:

   ✅ Added Scenario N.M: [scenario.name]
   - Type: [scenario.type]
   - AC: [scenario.acceptance_criterion]
   

For MODIFY Mode:

Updates an existing scenario.

Your tasks:

1. Use Step 5.1 to parse JSON (get scenarios[0] as the updated scenario)

2. Use Step 5.2 to display warnings

3. Update type file:

   • Find scenario in test-scenarios/{scenario.type}.md
   • Locate section starting with ## Scenario N.M:
   • Replace entire section (from heading to ---) with Step 5.3 content

4. Update scenarios.md (if name or type changed):

   • Find scenario entry ### Scenario N.M
   • Update name and type using Step 5.4 format
   • PRESERVE existing checkbox states

5. Display confirmation:

   ✅ Modified Scenario N.M: [scenario.name]
   
   If tests/implementation exist, review them for needed updates.
   

For DISCOVER Mode:

Analyzes existing scenarios for gaps and adds missing scenarios.

Your tasks:

1. Use Step 5.1 to parse JSON

2. Handle context requests (if any):

   if (response.context_requests?.length > 0) {
     For each requested file:
       - Read the file
       - Append to original request: "Additional Context:\n\nFile: {filename}\n{content}\n"
     Re-invoke qa-engineer agent with updated request
     Return to step 1 when agent responds
   }
   

3. If scenarios found (response.scenarios.length > 0):

   a. Use Step 5.2 to display warnings (especially gaps identified)

   b. For each new scenario:

   • Use Step 5.5 to determine next scenario number for the AC
   • Use Step 5.3 to append to appropriate type file
   • Use Step 5.4 to add tracking entry to scenarios.md

   c. Display summary:

   ✅ Discovered and added {count} new scenarios:
   - Scenario X.Y: [scenario.name] ({scenario.type})
   [list all new scenarios]
   

4. If no gaps found (response.message === "No gaps found - coverage is complete"):

   Display:
     ✅ No gaps found - scenario coverage is complete
   

For DELETE Mode:

No agent needed - this is a file operation only

Your tasks:

1. Parse scenario number from user request (e.g., "1.3")

2. Remove from scenarios.md:

   # Find and remove the scenario entry:
   ### Scenario N.M: [Name]
   - **Type**: [type]
   - **Details**: [link]
   - **Implementation Progress**: [checkboxes]
   

3. Remove from scenario detail file:

   # Find and remove from <directory>/test-scenarios/{type}.md
   ## Scenario N.M: [Name]
   [entire scenario content]
   ---
   

4. Display confirmation:

   ✅ Deleted Scenario N.M: [Name]
   - Removed from scenarios.md
   - Removed from test-scenarios/{type}.md
   
   ⚠️ Note: If this scenario had implementation (tests/code), you may need to remove those manually.
   

Expected File Structure

After EXPAND mode, the directory structure will be:

<task-directory>/
├── requirements.md            (INPUT - read-only, contains acceptance criteria)
├── scenarios.md               (OUTPUT - all scenarios with Implementation tracking)
└── test-scenarios/
    ├── happy-path.md         (OUTPUT - success cases)
    ├── error-cases.md        (OUTPUT - failure cases)
    └── edge-cases.md         (OUTPUT - boundary cases)

Usage Examples

Example 1: Create comprehensive scenarios from requirements.md

/test-scenarios apps/snyk-cmd/docs/features/bulk-ignore/tasks/task-001/

Creates all scenarios from requirements.md in that directory.

Example 2: Add single scenario

/test-scenarios apps/feature/task-001/ "add scenario for null organization name to AC-3"

Adds one scenario to existing set for AC-3.

Example 3: Modify existing scenario

/test-scenarios apps/feature/task-001/ "modify scenario 2.1 to test empty string instead of null"

Updates scenario 2.1 with new behavior.

Example 4: Discover and add missing scenarios

/test-scenarios apps/feature/task-001/ "discover gaps in existing scenarios"

Analyzes scenarios for gaps and automatically generates and adds missing test scenarios.

Example 4a: Discover gaps with additional context

/test-scenarios apps/feature/task-001/ "discover gaps" @research.md @tech-design.md

Uses additional context files to discover edge cases, technical constraints, and integration scenarios that may not be obvious from requirements alone. The qa-engineer agent may ask clarifying questions, then generates and adds the missing scenarios automatically.

Example 5: Delete scenario

/test-scenarios apps/feature/task-001/ "delete scenario 1.3"

Removes scenario 1.3 from scenarios.md and test-scenarios files.

Key Principles

This command is the orchestrator:

• ✅ Determines what to do (mode selection)
• ✅ Prepares context for agent
• ✅ Calls agent with simple request
• ✅ Parses structured JSON output
• ✅ Handles all file operations
• ✅ Manages scenario numbering based on agent's priority
• ✅ Creates links and tracking
• ✅ Displays warnings to user
• ✅ Handles context requests from agent (DISCOVER mode)

The qa-engineer agent is the QA expert:

• ✅ Applies QA heuristics
• ✅ Classifies scenarios by type (happy-path/error-case/edge-case)
• ✅ Assigns priority based on QA expertise
• ✅ Links scenarios to acceptance criteria
• ✅ Generates Given-When-Then scenarios
• ✅ Uses business-friendly language
• ✅ Warns about duplicates and implementation impact
• ✅ Requests additional context if needed (DISCOVER mode)
• ✅ Returns structured JSON for easy parsing
• ❌ Does NOT handle files, numbering, or organization