/nw-bdd-requirements

name: nw-bdd-requirements
description: BDD requirements discovery methodology - Example Mapping, Three Amigos, conversational patterns, Given-When-Then translation, and collaborative specification
user-invocable: false
disable-model-invocation: true

BDD Requirements Discovery

"If you're not having conversations, you're not doing BDD." -- Liz Keogh

BDD discovers "what we don't know we don't know" through collaborative exploration with concrete examples, not tools or formats.

Facilitate product understanding

The PO owns DISCUSS, not merely story decomposition. Start from one actor, concrete situation and intended benefit. Ask one consequential question or a small related group; reflect the answer in the actor's language and invite correction. Use existing answers instead of repeating discovery. Make alternatives and their consequences clear without leading the human toward your preferred formal property. Offer an example when abstraction prevents understanding.

Separate confirmed decisions, proposals, assumptions and open questions. Silence is not agreement; a repeated answer supports those examples, not general model fidelity. Honor interactive, final-review or explicitly delegated work. A delegated PO relays questions through its host; it does not pretend to have interviewed a person. Stop exploring when remaining questions do not change the current scope, observable behavior or material trade-off; retain relevant unknowns visibly.

Natural questions that can reveal properties

Use only questions relevant to the operation and current uncertainty. These are candidate distinctions, not a completeness theorem or a compulsory checklist. Do not name the algebra to the human unless it helps them.

| Ask in the domain | Distinction for downstream design | |---|---| | If the person submits twice, what should happen? | Repetition / idempotence | | If these actions arrive in the opposite order, what changes? | Order dependence / commutativity | | Can they undo it, and until when? | Reversibility / terminal state | | When this amount is moved or split, what total must stay the same? | Conservation | | Can both of these be true at once? | Mutual exclusion | | If it stops halfway, what does the person see and what can they do? | Failure / recovery / compensation | | Could doing this leave them with no safe next action? | Progress / non-trapping |

Accept answers such as “order matters” or “we have not decided”. Select operation pairs that share a resource or rule; do not enumerate every mathematical pairing. Record the answer and conditions before deriving a law. Examples remain product choices; the architect determines the appropriate types, laws and proof bounds.

Visual exploration and human view

For a changed human interface, offer a proportionate sketch, wireframe or navigable prototype. Explain the uncertainty it resolves; reuse existing components and honor a declined offer. The host can select `nw-ux-designer` and a bounded `nw-spike`; distinguish simulated behavior from real integration. Discuss relevant loading, empty, error, permission and recovery states, without inventing a quota of scenarios. Record what feedback changed, not just that a prototype exists.

Use the brief's nwdes HTML view as the shared reading surface. Put intent, journey, examples, decisions and open questions before formal detail. Ask the human to explain or challenge a concrete consequence when understanding is uncertain; do not turn comprehension checks into an examination or approval ceremony. The renderer cannot repair unclear semantic input.

The Three Amigos

Three perspectives revealing each other's blindspots:

1. **Problem Owner** (PO, BA, Domain Expert): business need | acceptance criteria | domain knowledge 2. **Problem Solver** (Developer, Engineer): technical constraints | implementation complexity | technical edge cases 3. **Skeptic** (Tester, QA): failure modes | edge cases and boundaries | challenge assumptions

Session Structure (25-minute timebox)

1. Read user story aloud (2 min) -- shared context 2. Identify acceptance criteria/rules (8 min) -- "what must be true for done?" 3. Explore examples per rule (12 min) -- concrete scenarios, edge cases 4. Capture questions (ongoing) -- unknowns on red cards 5. Review and summarize (3 min) -- shared understanding check

If unmappable in 25 min: too large (split) | too uncertain (spike) | team needs practice.

Example Mapping

Four Card Types

• Yellow: User Story (1 per session) | Blue: Business Rules/AC | Green: Concrete Examples | Red: Questions/Unknowns (blockers)

Visual Layout

[Yellow] User Story: Transfer money between accounts
  |
  +-- [Blue] Rule: Amount must not exceed source balance
  |     +-- [Green] $500 balance, transfer $400 -> succeeds
  |     +-- [Green] $500 balance, transfer $500 -> succeeds (boundary)
  |     +-- [Green] $500 balance, transfer $501 -> fails
  |     +-- [Red] What happens if balance changes during transfer?
  |
  +-- [Blue] Rule: Both accounts belong to same customer
  |     +-- [Green] Transfer between checking and savings -> succeeds
  |     +-- [Green] Transfer to friend's account -> requires different flow
  |
  +-- [Blue] Rule: Transfer creates transaction records
        +-- [Green] $100 transfer -> 2 transactions (debit + credit)
        +-- [Red] What timezone for timestamps?

When to Use Example Mapping

Use when: story entering sprint | multiple edge cases | team uncertain about scope | cross-functional clarification needed. Skip when: trivial well-understood story | pure technical refactoring with no behavior change | strong shared understanding already.

Conversational Patterns

Pattern 1: Context Questioning

Template: "Is there any other context which, when this event happens, will produce a different outcome?"

Purpose: discover edge cases and alternative scenarios.

BA: "When a customer submits an order, the order is confirmed."
Tester: