SmidigStorm /requirements
Write new BDD requirements in Gherkin format.
Workflow
0. Read Conventions
First: Read bdd-guide.md to understand:
- BDD best practices
- Folder structure (Domain → Subdomain → Capability)
- Feature ID format (
@DOM-SUB-CAP-NNN) - Tags (priority, status)
- Actors
1. Read Domain Knowledge
Before writing requirements, search for and read existing domain documentation:
- Look for entity definitions in
docs/domains/*/entities/or similar paths - Read the
_overview.mdif it exists - Read entity files relevant to the feature being specified
- Understand existing attributes, relationships, and business rules
This ensures requirements align with the established domain model and use correct terminology.
2. Understand the Need
Ask the user:
- What should the functionality do?
- Who are the actors?
- What terms/expressions should be used?
3. Define Scenarios
For each scenario, ask about:
- Precondition (Given)
- Action (When)
- Expected result (Then)
NEVER assume error messages or business logic - ask!
4. Generate Feature File
Location: Follow the folder structure in bdd-guide.md:
requirements/[NN] [Domain]/[NN] [Subdomain]/[NN] [Capability]/feature-name.feature
Format:
@[ID] @[priority]
Feature: [ID] [Name]
As a [actor]
I want to [action]
So that [value].
# OPEN QUESTIONS:
# - [Any uncertainties are documented here]
Background:
Given [common precondition]
Rule: [Business rule]
Scenario: [Descriptive name]
Given [precondition]
When [action]
Then [expected result]
When uncertain: Document with # OPEN QUESTIONS: right after the feature description (after "So that...").
5. Update Overview
Run the markdown generator to update requirements/requirements-overview.md:
cd requirements-parser && npm run generate-overview
This scans all .feature files and generates an updated overview with ID, feature name, tags, and statistics.
Resources
- bdd-guide.md - BDD best practices and project conventions
- examples/gherkin-example.feature - Complete example