GitHub

How To: Execute DELIVER Wave with Step-to-Scenario Mapping

Document Type: How-to Guide Last Updated: 2026-01-24 Related: Outside-In TDD: Step-to-Scenario Mapping Principle

Goal

Successfully execute a DELIVER wave where each roadmap step implements exactly one acceptance test scenario following Outside-In TDD discipline.

Before You Start

You will need:

  • A completed acceptance test file with scenarios (from DISTILL wave)
  • The nWave framework installed via sh -c "$(curl -fsSL https://raw.githubusercontent.com/nWave-ai/nWave/main/scripts/install/install.sh)"
  • A project with user story identification (e.g., us001, us002)

Step 1: Count Your Acceptance Test Scenarios

First, determine how many acceptance test scenarios exist in your feature.

Location: tests/acceptance/test_us00X_*.py

Command:

grep 'def test_' tests/acceptance/test_us001_*.py | wc -l

Expected Output:

4

This tells you that you need exactly 4 steps in your roadmap (one per scenario).

Step 2: Verify the Step-to-Scenario Mapping Principle

Before proceeding, review the mapping rule:

The Rule: num_roadmap_steps == num_acceptance_scenarios

Example:

  • 4 acceptance test scenarios = 4 roadmap steps = 4 step files (01-01, 01-02, 01-03, 01-04)
  • Each step makes exactly 1 scenario pass (RED → GREEN)

Step 3: Start DELIVER Wave (Creates Roadmap with Scenario Mapping)

Start the DELIVER wave, which creates a comprehensive roadmap where each step explicitly maps to one acceptance scenario.

Command:

/nw-deliver

Pre-Check (Agent will verify this):

  1. Agent reads acceptance tests: tests/acceptance/test_us00X_*.py
  2. Agent counts scenarios and creates N steps for N scenarios
  3. Agent flags if count mismatch is detected

Roadmap Structure:

steps:
  - step_id: "01-01"
    name: "Make test_execute_command_includes_des_validation_marker pass"
    acceptance_test_scenario: "test_scenario_001_execute_command"
    acceptance_test_file: "tests/acceptance/test_us001_*.py"
    description: "Implement code to make test_scenario_001 pass (RED → GREEN)"

  - step_id: "01-02"
    name: "Make test_ad_hoc_task_bypasses_des_validation pass"
    acceptance_test_scenario: "test_scenario_002_ad_hoc_task"
    acceptance_test_file: "tests/acceptance/test_us001_*.py"
    description: "Implement code to make test_scenario_002 pass (RED → GREEN)"

  # ... continue for each scenario

Critical Fields (Must include):

  • acceptance_test_scenario: Maps to exact test function name
  • acceptance_test_file: Points to the feature acceptance test file
  • description: Explicitly states "Make test_X pass (RED → GREEN)"

Output Location: docs/feature/{project_id}/roadmap.json

Step 4: Verify Step Files

The roadmap command generates individual step files. Verify them before execution.

Validation:

  • assert num_steps == num_acceptance_scenarios
  • Each step file contains exactly one acceptance test scenario reference
  • Each step maps to roadmap via step_id

Step File Template:

{
  "task_specification": {
    "task_id": "01-01",
    "acceptance_test_scenario": "test_scenario_001_execute_command",
    "acceptance_test_file": "tests/acceptance/test_us001_*.py",
    "description": "Make test_scenario_001 pass (RED → GREEN)",
    "phase_2_acceptance_test_command": "pytest tests/acceptance/test_us001_*.py::test_scenario_001_* -v"
  }
}

Output Location: docs/feature/{project_id}/steps/01-01.json through 01-0N.json

Step 5: Execute Each Step with RED → GREEN Discipline

Execute steps sequentially, with each step focusing on a single acceptance scenario.

Command (execute each step):

/nw-execute "{project_id}" "01-01"
/nw-execute "{project_id}" "01-02"
/nw-execute "{project_id}" "01-03"
/nw-execute "{project_id}" "01-04"

For Each Step:

Phase 2: Acceptance Test (RED)

Run only the mapped scenario:

pytest tests/acceptance/test_us001_*.py::test_scenario_001_* -v

Expected: FAIL (RED state)

Phase 6: Acceptance Test (GREEN)

Run the same scenario again after implementation:

pytest tests/acceptance/test_us001_*.py::test_scenario_001_* -v

Expected: PASS (GREEN state)

Verify No Regression

Run all acceptance tests to ensure previous steps aren't broken:

pytest tests/acceptance/ -v

Expected: All previously passing tests still pass, new test now passes

Step 6: Finalize the Wave

After all steps complete successfully, finalize the wave (archival and reporting).

Command:

/nw-finalize "{project_id}"

Deliverables:

  • Wave completion report
  • Metrics analysis (baseline vs. final state)
  • Archival of step files

Validation Checklist

Before declaring DELIVER wave complete:

Common Issues

Issue: "Count Mismatch" Error

Problem: Roadmap has 11 steps but only 4 acceptance test scenarios.

Solution:

  1. Verify the acceptance test file: tests/acceptance/test_us001_*.py
  2. Count scenarios: grep 'def test_' file.py | wc -l
  3. Reduce roadmap to match scenario count
  4. Mark infrastructure steps as type infrastructure (not feature)

Reference: See the Step-to-Scenario Mapping sections above

Issue: Multiple Scenarios Pass in One Step

Problem: Step 01-01 makes tests 1, 2, and 3 pass instead of just test 1.

Solution:

  • This violates Outside-In TDD discipline
  • Split the implementation into separate steps
  • Each step should make exactly 1 scenario pass
  • Refactor to isolate concerns per scenario

Issue: "Infrastructure Step" Exception

Problem: Need a step for database migration or environment setup (no acceptance test).

Solution:

  1. Create step with type infrastructure
  2. Leave acceptance_test_scenario empty
  3. Document manual verification in step file
  4. Do NOT count toward feature scenario mapping
Edit this page on GitHub