/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:

1. Look for entity definitions in docs/domains/*/entities/ or similar paths
2. Read the _overview.md if it exists
3. Read entity files relevant to the feature being specified
4. 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