nw-bdd-requirements
BDD requirements discovery methodology - Example Mapping, Three Amigos, conversational patterns, Given-When-Then translation, and collaborative specification
Install / Use
npx skills add nWave-ai/nWave --skill nw-bdd-requirementsInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of nw-bdd-requirements
nw-bdd-requirements scores 92/100 on our quality scale, 953rd of 4,702 Development & Engineering skills we index (top 21%).
Its SKILL.md is 13 KB long, well organised into 38 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.
It has 617 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so nw-bdd-requirements is actively maintained.
- Our last check on 2026-10-28 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
nw-bdd-requirements compared with similar skills
All 4 of these similar skills score higher than nw-bdd-requirements; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| nw-bdd-requirements (this skill)by nWave-ai | 92 | 617 | 2mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 117.6k | 9d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.3k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.4k | 3d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.7k | today | MCP Server |
Frequently asked questions
- How do I install nw-bdd-requirements?
- Run
npx skills add nWave-ai/nWave --skill nw-bdd-requirements. The install tabs above show the steps for each supported agent. - Which AI agents does nw-bdd-requirements work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is nw-bdd-requirements safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is nw-bdd-requirements still maintained?
- The repository was last updated about 2 months ago, so nw-bdd-requirements is actively maintained.
Skill content
View source on GitHubname: 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:
- Problem Owner (PO, BA, Domain Expert): business need | acceptance criteria | domain knowledge
- Problem Solver (Developer, Engineer): technical constraints | implementation complexity | technical edge cases
- Skeptic (Tester, QA): failure modes | edge cases and boundaries | challenge assumptions
Session Structure (25-minute timebox)
- Read user story aloud (2 min) -- shared context
- Identify acceptance criteria/rules (8 min) -- "what must be true for done?"
- Explore examples per rule (12 min) -- concrete scenarios, edge cases
- Capture questions (ongoing) -- unknowns on red cards
- 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"
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
- 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 lacking clear business value.
Acceptance Criteria Style
Traditional (implementation-focused) -- avoid:
- "API endpoint accepts POST requests" | "Response returns JSON with 201 status"
BDD-style (outcome-focused) -- use:
- "Customer can submit order even when offline" | "Order confirmed within 2 seconds" | "Customer receives email confirmation"
Shift from "system does X" to "user achieves Y."
Confirmation Bias Defense
Technique 1: Reverse Assumptions
Assumption: "Users fill out the form correctly." Reverse: empty form | garbage data | 50,000 characters | 100 submissions in 10 seconds.
Technique 2: Evil User Persona
"Malicious Mike" tries SQL injection, URL manipulation, unauthorized access. "Careless Cathy" never reads instructions, clicks back mid-process, refreshes constantly.
Technique 3: Force Example Diversity
For each rule, require examples from three categories:
- Happy path (typical success) | 2. Edge case (boundary, unusual but valid) | 3. Error case (invalid, failure condition)
Forcing diversity prevents echo chamber thinking.
Red Card Management
Red cards are blockers. Never proceed to development with unresolved questions.
Resolution process:
- Capture during session | 2. Assign owner (usually BA/PO) | 3. Set deadline (before dev starts) | 4. Follow-up session if answer reveals new complexity
Good red cards: "Character limit for product descriptions?" | "PDFs or only images?" | "What happens to orders if payment gateway is down?"
Requirements Document Structure
BDD hierarchy:
Business Capability (Epic)
+-- Feature (Theme)
+-- User Story
+-- Acceptance Criteria (Rules)
+-- Scenarios (Examples)
Each level includes: business value | user context | concrete examples | Given-When-Then scenarios | tracked questions with resolution status.
Bridging Business and Technical Perspectives
Same scenario, understood differently by each role:
Scenario: High-value customer receives priority support
Given I am a customer with "Platinum" membership
And I submit a support ticket with priority "urgent"
When the support team reviews new tickets
Then my ticket appears at the top of the queue
And I receive automated acknowledgment within 1 minute
- Executive sees: "Platinum customers get priority" (business rule)
- Customer sees: "My urgent issues get fast response" (user benefit)
- Developer sees: "Filter by membership tier and priority" (implementation)
- Tester sees: "Verify queue ordering and SLA compliance" (test case)
Same scenario, multiple valid interpretations, zero translation loss.
Discovery Workshop Format (90 minutes)
Participants: 6-8 people (PO, BA as facilitator, 2-3 developers, 1-2 testers, optional SME).
- Context Setting (10 min) -- business problem, success criteria
- Story Writing (15 min) -- brainstorm, write on yellow cards, prioritize
- Example Mapping Round 1 (25 min) -- top priority story
- Break (5 min)
- Example Mapping Round 2 (25 min) -- second priority story
- Review and Next Steps (10 min) -- summarize, assign red cards, schedule follow-up
Output: 2-3 stories mapped | 10-15 scenarios drafted | red cards assigned.
Example Mapping Anti-Patterns
- No examples, just rules: Blue cards without green cards. Rules are abstract. Force concrete examples for each rule.
- Too many rules (story too big): >5-6 blue cards means split needed.
- Implementation details in examples: "POST to /api/users with JSON" instead of "I register with email." Describe user-observable behavior.
- Ignoring red cards: Proceeding with unresolved questions leads to rework.
User Story Mapping
Decompose epics into stories by tracing the complete user workflow.
Process
- Map workflow end-to-end: Walk complete user journey from trigger to outcome. Each step becomes a column.
- Identify touchpoints: List system interactions, decisions, and information needs at each step.
- Break into stories: Group touchpoints into coherent user stories delivering demonstrable slices.
- Prioritize by value: Top row = minimum viable workflow (walking skeleton). Lower rows = enhancements.
Visual Layout
Workflow: [Discover] --> [Evaluate] --> [Purchase] --> [Receive]
| | | |
Row 1: Search by View details Add to cart Track order
keyword + price + checkout status
| | | |
Row 2: Filter by Compare Apply Delivery
category products coupon notifications
| |
Row 3: Save search Read reviews
Row 1 = MVP release. Row 2 = second release. Row 3 = future.
Story mapping complements Example Mapping: use story mapping to identify WHICH stories, then Example Mapping to explore EACH story in depth.
Requirements Completeness Check
During Phase 1 (GATHER), verify all three requirement types. Stories covering only functional requirements produce incomplete handoffs.
Functional Requirements
- Business capabilities and features | User interactions and system responses
- Data processing and transformation rules | Integration and interface requirements
- Validation: testable through acceptance tests | traceable to business objectives | complete and unambiguous
Non-Functional Requirements (NFRs)
- Performance: response time, throughput, scalability | Security: authentication, authorization, data protection
- Usability: user experience, accessibility | Reliability: availability, fault tolerance, recovery
- Validation: quantifiable metrics and thresholds | testable through automated validation
Business Rules
- Business policy enforcement | Data validation and integrity rules
- Workflow and process constraints | Compliance and regulatory requirements
- Validation: clear rule specification with examples | excepti
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
117.6kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.3kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.4kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.7k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
