Menu
BDD requirements using Gherkin syntax. Activates when users describe features, requirements, user stories, acceptance criteria, or work with .feature files. Generates Given-When-Then scenarios, validates Gherkin structure, and creates complete feature files.
PM Airtable data model reference. Use when creating tables, querying structure, or understanding relationships between Domain, Subdomain, Capability, Entity, Requirement, and BacklogItem tables.
Architecture Decision Records (ADRs) for documenting technical decisions. Use when creating, updating, or reviewing architecture decisions. Triggers on discussions about technical choices, trade-offs, or "why did we choose X" questions.
Document domain knowledge including entities, attributes, relationships, processes, and ubiquitous language. Use when documenting domain models, entity relationships, business processes, or building a glossary of domain terms.
Interactive implementation planning from backlog items. Use when creating plans for features, fixes, or tasks. Guides 6-phase collaborative dialogue from discovery through documentation.
| name | requirements-writing |
| description | BDD requirements using Gherkin syntax. Activates when users describe features, requirements, user stories, acceptance criteria, or work with .feature files. Generates Given-When-Then scenarios, validates Gherkin structure, and creates complete feature files. |
This skill enables assistance with Behavior-Driven Development (BDD) requirements documentation using Gherkin syntax. It helps create well-structured feature files with Given-When-Then scenarios.
"Write Gherkin so that people who don't know the feature will understand it."
Treat readers as you'd want to be treated - prioritize clarity for all audiences, including non-technical stakeholders.
"One Scenario, One Behavior!"
Each scenario must cover exactly ONE independent behavior. Never write multiple When-Then pairs in a single scenario. If you find yourself wanting to add another When-Then, create a separate scenario.
This skill MUST trigger dialogue with users, NOT make assumptions.
AI has a strong tendency to:
NEVER do any of the above. Instead:
Every feature file gets a unique requirement ID for traceability.
[SUB]-[CAP]-[NUMBER] [Name]
Examples:
ADM-GRD-001 Weighted Average (Admission Rules subdomain, Grade Calculation capability)ADM-ELG-001 Check Prerequisites (Admission Rules subdomain, Eligibility capability)ENR-CRS-001 Register for Courses (Enrollment subdomain, Course Registration capability)Prefixes are derived from subdomain and capability names:
ADMGRDELGFor new subdomains/capabilities, ask the user for preferred 3-letter prefixes.
The requirement ID is added as a tag on the Feature:
@ADM-GRD-001
Feature: Weighted Average Calculation
As an admission officer
I want grades to be calculated as weighted averages
So that I can fairly evaluate applicants
All requirement IDs are tracked in docs/requirements/registry.md:
# Requirements Registry
## Admission (Domain)
### ADM - Admission Rules (Subdomain)
#### GRD - Grade Calculation (Capability)
| ID | Name | File | Status |
|----|------|------|--------|
| ADM-GRD-001 | Weighted Average | admission/admission-rules/grade-calculation/weighted-average.feature | Active |
#### ELG - Eligibility Criteria (Capability)
| ID | Name | File | Status |
|----|------|------|--------|
| ADM-ELG-001 | Check Prerequisites | admission/admission-rules/eligibility-criteria/check-prerequisites.feature | Active |
Active, Draft, DeprecatedFeature files are organized in docs/requirements/ with subdirectories for domain, subdomain, and capability:
docs/requirements/
├── registry.md # Tracks all requirement IDs
└── [domain]/
└── [subdomain]/
└── [capability]/
└── feature-name.feature # @SUB-CAP-NNN
Example:
docs/requirements/
├── registry.md
└── admission/
└── admission-rules/
├── grade-calculation/
│ └── weighted-average.feature # @ADM-GRD-001
└── eligibility-criteria/
└── check-prerequisites.feature # @ADM-ELG-001
user-registration.feature, order-checkout.feature.feature extensiondocs/requirements/registry.md) to get existing IDsdocs/requirements/**/*.feature)Before writing scenarios, ALWAYS ask about domain knowledge.
"Where do you keep your domain knowledge?"
"What entities are involved in this feature?"
"What are the business rules?"
If user doesn't provide enough information:
# TODO: or # QUESTION: comments@wipA structured technique for refining requirements before writing Gherkin:
| Card Color | Purpose |
|---|---|
| Yellow | The user story or feature being discussed |
| Blue | Business rules / acceptance criteria |
| Green | Concrete examples for each rule |
| Red | Open questions to resolve |
Process:
Benefits:
# QUESTION: commentsWhen users describe functionality, recognize it as a feature requirement and offer to create Gherkin scenarios.
Read and understand existing feature files:
Convert descriptions into Given-When-Then scenarios:
Guidelines:
Check feature files for:
Feature file structure:
@ADM-001
Feature: User Registration
As a new user
I want to register an account
So that I can access the system
Background:
Given the registration page is displayed
Rule: Users must provide valid email and password
Scenario: Successful registration
Given I enter email "user@example.com"
And I enter password "SecurePass123"
When I submit the registration form
Then I should see a confirmation message
And a verification email should be sent
@negative
Scenario: Registration with existing email
Given a user with email "existing@example.com" exists
When I try to register with "existing@example.com"
Then I should see "Email already registered"
Rule: Password must meet security requirements
Scenario Outline: Password validation
When I enter password "<password>"
Then I should see "<message>"
Examples:
| password | message |
| short | Password too short |
| nodigits | Password must have numbers |
1. Use comments:
# OPEN QUESTIONS:
# - What happens if the user is already registered?
# - Should we send a confirmation email?
Feature: User Registration
2. Use tags:
@wip @needs-clarification
Scenario: Registration with existing email
Given a user with email "test@example.com" exists
When I try to register with "test@example.com"
# TODO: Clarify error message with product owner
Then I should see an error message
3. Document in steps:
Scenario: Order with invalid payment
Given I have items in my cart
When I submit an invalid credit card
# QUESTION: Should we show specific validation errors or generic message?
Then I should see a payment error
@wip - Work in progress@needs-clarification - Awaiting stakeholder decision@todo - Needs additional work1. Business Rules, Not Edge Cases
Focus on documenting the core business rules - not every possible edge case or validation detail. A feature file should capture WHAT the system does, not exhaustively test every input combination.
Too detailed (avoid):
Scenario: Password too short (5 chars)
Scenario: Password too short (6 chars)
Scenario: Password too short (7 chars)
Scenario: Password missing uppercase
Scenario: Password missing lowercase
Scenario: Password missing number
Scenario: Password missing special char
Focused on business rule (preferred):
Rule: Password must meet security requirements
Scenario Outline: Invalid password rejected
When I enter password "<invalid_password>"
Then I should see "<error_message>"
Examples:
| invalid_password | error_message |
| short | Minimum 8 characters |
| nouppercas3 | Must include uppercase |
| NOLOWERCASE1 | Must include lowercase |
2. CRITICAL: Never Duplicate Scenarios - Use Scenario Outline
"Copying and pasting scenarios to use different values quickly becomes tedious and repetitive." — Cucumber Documentation
The Rule: If you see multiple scenarios with the same steps but different data values, you MUST refactor into a Scenario Outline. This is not optional.
How to spot duplication:
Duplicated scenarios (NEVER do this):
# BAD - Three scenarios that are essentially the same
Scenario: Admin can access dashboard
Given I am logged in as "admin"
When I navigate to the dashboard
Then I should see the dashboard
Scenario: Manager can access dashboard
Given I am logged in as "manager"
When I navigate to the dashboard
Then I should see the dashboard
Scenario: Guest cannot access dashboard
Given I am logged in as "guest"
When I navigate to the dashboard
Then I should see "Access denied"
Scenario Outline (ALWAYS do this instead):
# GOOD - One template, multiple examples
Scenario Outline: Role-based dashboard access
Given I am logged in as "<role>"
When I navigate to the dashboard
Then I should see "<result>"
Examples:
| role | result |
| admin | the dashboard |
| manager | the dashboard |
| guest | Access denied |
Scenario Outline best practices:
<student_name> not <input1>@positive
Examples: Authorized users
| role | result |
| admin | the dashboard |
| manager | the dashboard |
@negative
Examples: Unauthorized users
| role | result |
| guest | Access denied |
| blocked | Access denied |
3. Good Scenario Titles
Titles should be short one-liners that summarize the behavior.
Avoid in titles:
Good: Successful login with valid credentials
Bad: Verify user can login and should see dashboard
4. Keep It Small
5. Third-Person, Present Tense
Good: Given the user is logged in / When the user submits the form
Avoid: Given I am logged in (mixing perspectives)
6. Organize with Rules
7. Declarative over Imperative
When the user registers a new accountWhen the user clicks the button, fills the form, and submits8. Business Language
9. Vivid, Concrete Examples (Background AND Scenarios)
Use realistic, specific values that tell a story - both in Background setup and Scenario steps.
Background - Use data tables, not generic statements:
# GOOD - Concrete data that readers can understand
Background:
Given the following students exist:
| Name | Email | Program |
| Emma Wilson | emma@university.edu | Psychology |
| James Chen | james@university.edu | Economics |
# BAD - Generic, tells nothing
Background:
Given that there is data in the system
Given that students exist
Scenarios - Use vivid, realistic values:
# GOOD - Specific, meaningful values
When I filter by the domain "Admission"
When I search for student "Emma Wilson"
Then I should see the course "Introduction to Psychology"
# BAD - Generic placeholders
When I choose to filter by domain
When I search for a student
When I select option "X"
Then I should see results
Why this matters:
10. Independent Scenarios
11. Meaningful Tags
@critical - Critical functionality@smoke - Smoke test suite@negative - Negative test cases@slow - Long-running testsUser: "Users should be able to register with email and password"
GOOD Response:
"I'll help create a feature file for user registration. First some questions:
1. Where do you keep domain knowledge? (schemas, docs)
2. What validations are needed? (email format, password strength)
3. What happens if the email is already taken?
4. Should we send a confirmation email?
5. What error messages should be shown?
Once I understand these, I'll create accurate scenarios."
When reviewing feature files, check for: