Nw Bdd RequirementsSAFE

AI agents that guide you from idea to working code, with you in control at every step.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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.

## 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: "Is there context that produces a different outcome?"
Developer: "What if the item is out of stock?"
BA: "Then the order goes to backorder status."
Tester: "What if payment is declined?"
BA: "Then the order is pending payment."
```

Result: three rules discovered from one statement.

### Pattern 2: Outcome Questioning

Template: "Given this context, when this event happens, is there another outcome that's important?"

```
BA: "When admin deletes a user account, the account is deleted."
Tester: "Is there another important outcome?"
Developer: "Audit log entry for the deletion."
BA: "Email notification to the user."
Tester: "GDPR -- delete all personal data."
Developer: "What about resources owned by the user?"
```

Result: one simple statement revealed five important outcomes.

### Pattern 3: Concrete Examples

Template: "Can you give me a concrete example?"

Abstract rules hide assumptions. Concrete examples force decisions.

```
BA: "User can search products by category."
Developer: "Concrete example?"
BA: "User selects 'Electronics' category."
Tester: "What if Electronics has 10,000 products?"
BA: "We paginate. Show 20 per page."
Developer: "Default sort order?"
BA: "I need to ask stakeholders."
[Red card: "Default sort order for category browsing?"]
```

## From Examples to Given-When-Then

### Translation Rules
- **Given** = context (preconditions, system state)
- **When** = event/action (user action, system trigger)
- **Then** = outcome (observable results, state changes)

### Scenario Titles: Business Outcomes Only

Scenario titles describe WHAT the user achieves, never HOW the system implements it.

| BAD (implementation) | GOOD (business outcome) |
|---|---|
| FileWatcher triggers TreeView refresh | Dashboard updates in real-time |
| Observer writes state.json on event | Wave progress is captured when a phase completes |
| Debounce prevents rapid writes | Rapid progress changes render smoothly |
| Atomic write prevents partial reads | Dashboard always sees consistent data |

**Rule**: If the title contains a class name, method name, file name, or protocol detail, rewrite it as the user-observable outcome.

### Example Translation

Example card: "Balance $500, transfer $300 -> succeeds"

```gherkin
Scenario: Successful transfer with sufficient balance
  Given my checking account balance is $500.00
  And my savings account balance is $100.00
  When I transfer $300.00 from checking to savings
  Then my checking balance is $200.00
  And my savings balance is $400.00
  And I receive a confirmation message
```

### For Each Rule, Create 2-3 Examples
1. Typical/happy path | 2. Boundary condition | 3. Error/alternative path

## Business Outcome Focus: Five Whys

Apply Five Whys to connect stories to business value:

```
Story: "Add CSV export for reports"
Why? "Users can export data"
Why? "Analyze in Excel"
Why? "No pivot tables in our app"
Why? "Need to slice data by dimensions"
Why? "Identify trends for business decisions"

Real need: better analytical capabilities, not CSV export
```

Focus on behaviors contributing to business results. Challenge features la

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.