How To: Deliver a Slice with Scenario-to-Row Mapping
Document Type: How-to Guide Last Updated: 2026-10-23 Related: Outside-In TDD: Scenario-to-Row Mapping Principle
Audience. The steps are run by the root assistant — the session you talk to: it executes the nwdes verbs and the test runs below. The person reads along, decides scope and trade-offs, and points the assistant at this guide — the sentence to paste is in For your assistant.
Goal
Successfully deliver a slice through the nwdes route where each acceptance test scenario is recorded as exactly one acceptance row and observed RED, then GREEN, following Outside-In TDD discipline.
Before You Start
You will need:
- A completed acceptance test file with scenarios (from the DISTILL wave or the acceptance designer)
- The nWave framework installed via
sh -c "$(curl -fsSL https://raw.githubusercontent.com/nWave-ai/nWave/main/scripts/install/install.sh)" - A feature created with
nwdes feature new, so itshandoff.json($Hbelow) exists - The slice you are delivering (for example
S1)
Run every nwdes command from the top level of the checkout. Roots default to cwd and the repository root, and the first add, set or remove creates the draft.
Step 1: Count Your Acceptance Test Scenarios
First, determine how many acceptance test scenarios exist in your slice.
Location: tests/acceptance/test_us00X_*.py
Command:
grep 'def test_' tests/acceptance/test_us001_*.py | wc -l
Expected Output:
4
This tells you that the slice needs exactly 4 acceptance rows (one per scenario).
Step 2: Verify the Scenario-to-Row Mapping Principle
Before proceeding, review the mapping rule:
The Rule: num_acceptance_rows == num_acceptance_scenarios
Example:
- 4 acceptance test scenarios = 4 acceptance rows in the slice's
### S1section ofacceptance.md - Each row names one test locator through
--testand the promises it covers through--covers - Each scenario goes RED → GREEN on its own declared command
Step 3: Record the Acceptance Rows
Run /nw-deliver to route the Request. When the slice reaches its acceptance stage, give the acceptance designer the complete bundle that nwdes builds:
nwdes prompt --role nw-acceptance-designer --handoff "$H" --slice S1
Pre-Check (the designer verifies this):
- The designer reads the acceptance tests:
tests/acceptance/test_us00X_*.py - It counts scenarios and records one row per scenario
- It flags a count mismatch before closing
Recording: the designer records one row per scenario with nwdes acceptance row add and ends the draft with nwdes acceptance close.
nwdes acceptance row add --slice S1 \
--stimulus 'The user runs the command' \
--expected 'The command output is shown' \
--user-result 'The user sees the result' \
--disposition Tested \
--test 'tests/acceptance/test_us001_x.py::test_scenario_001_execute_command'
Critical Fields (must include):
--test: the exact test function locator for a Tested row--covers: the promise or design identities the scenario covers--stimulus,--expected,--user-result: the observation the scenario makes
Output Location: docs/feature/{project_id}/handoff.json, with the rendered acceptance.md beside it.
Step 4: Verify the Rows
nwdes renders the rows into acceptance.md. Verify them before crafting.
Validation:
assert num_rows == num_acceptance_scenarios- Each Tested row references exactly one scenario locator
- Each row cites known identities in
--covers; an unknown reference is refused asDanglingReference
Step 5: Craft with RED → GREEN Discipline
The crafter implements the slice against the immutable oracle and records its files and commands with nwdes craft. The host runs the declared commands and observes the actual results.
nwdes prompt --role nw-software-crafter --handoff "$H" --slice S1
For Each Scenario:
Acceptance Test (RED)
Run only the mapped scenario:
pytest tests/acceptance/test_us001_*.py::test_scenario_001_* -v
Expected: FAIL (RED state)
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 earlier scenarios aren't broken:
pytest tests/acceptance/ -v
Expected: All previously passing tests still pass, new test now passes
Step 6: Review, Examine and Integrate
After every slice is GREEN, run one review and one examination of the whole candidate, then integrate.
Command:
nwdes lane compose --feature "{project_id}"
nwdes lane integrate --feature "{project_id}" --expected "$EXPECTED" --candidate "$CANDIDATE"
Deliverables:
- Accepted whole-candidate review and examiner verdicts
- Craft and review run records under
docs/feature/{project_id}/runs/ - Trunk fast-forwarded to the candidate and the lane removed
See Deliver a feature with nwdes for the complete route, including the lane-free variant.
Validation Checklist
Before declaring the delivery complete:
Common Issues
Issue: "Count Mismatch"
Problem: The slice has 11 acceptance rows but only 4 acceptance test scenarios.
Solution:
- Verify the acceptance test file:
tests/acceptance/test_us001_*.py - Count scenarios:
grep 'def test_' file.py | wc -l - Remove surplus rows with
nwdes acceptance row remove, or revise published rows withnwdes acceptance open --from-current - Record a requirement with no scenario as a
NotTestedrow (see below)
Reference: See the Scenario-to-Row Mapping sections above
Issue: Multiple Scenarios Pass in One Change
Problem: Implementing for scenario 1 also makes tests 2 and 3 pass.
Solution:
- This violates Outside-In TDD discipline
- Split the implementation so each scenario is observed RED before its own implementation
- Each scenario should be observed going from RED to GREEN on its own
- Refactor to isolate concerns per scenario
Issue: "Infrastructure" Requirement Without a Scenario
Problem: Need a database migration or environment setup (no acceptance test).
Solution:
- Record a row with
--disposition NotTested - Give its
--reasonand its--owner - Document manual verification in that reason
- Do NOT count it toward the scenario mapping