doc-bdd

Purpose

Create BDD (Behavior-Driven Development) test scenarios - Layer 4 artifact in the SDD workflow that defines executable test scenarios using Gherkin syntax.

Layer: 4

Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3)

Downstream: ADR (Layer 5), SYS (Layer 6), REQ (Layer 7)

Prerequisites

Upstream Artifact Verification (CRITICAL)

Before creating this document, you MUST:

1. List existing upstream artifacts:

   ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ 2>/dev/null
   

2. Reference only existing documents in traceability tags

3. Use null only when upstream artifact type genuinely doesn't exist

4. NEVER use placeholders like BRD-XXX or TBD

5. Do NOT create missing upstream artifacts - skip functionality instead

Before creating BDD, read:

1. Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
2. Upstream BRD, PRD, EARS: Read artifacts that drive these test scenarios
3. Template: ai_dev_flow/BDD/BDD-SECTION-TEMPLATE.feature
4. Creation Rules: ai_dev_flow/BDD/BDD_CREATION_RULES.md
5. Validation Rules: ai_dev_flow/BDD/BDD_VALIDATION_RULES.md
6. Splitting Rules: ai_dev_flow/BDD/BDD_SPLITTING_RULES.md

When to Use This Skill

Use doc-bdd when:

• Have completed BRD (Layer 1), PRD (Layer 2), EARS (Layer 3)
• Need to define executable test scenarios
• Validating EARS formal requirements with Given-When-Then format
• Creating acceptance criteria for features
• You are at Layer 4 of the SDD workflow

Section-Based Structure (MANDATORY)

All BDD suites MUST use section-based structure. No backward compatibility with legacy formats.

Directory Structure

docs/BDD/
├── BDD-02_knowledge_engine/           # Suite folder
│   ├── BDD-02.0_index.md              # Index file (MANDATORY)
│   ├── BDD-02.1_ingest.feature        # Section 1
│   ├── BDD-02.2_query.feature         # Section 2
│   ├── BDD-02.3.00_learning.feature   # Aggregator (if 5+ subsections)
│   ├── BDD-02.3.01_learning_path.feature    # Subsection 1
│   ├── BDD-02.3.02_bias_detection.feature   # Subsection 2
│   ├── BDD-02_README.md               # Optional companion
│   └── BDD-02_TRACEABILITY.md         # Optional companion
└── BDD-02_knowledge_engine.feature    # Redirect stub (0 scenarios)

Three Valid File Patterns (ONLY)

Pattern	Example	Use When
Section-Only	BDD-02.14_query_result_filtering.feature	Standard section (≤500 lines, ≤12 scenarios)
Subsection	BDD-02.24.01_quality_performance.feature	Section requires splitting
Aggregator	BDD-02.12.00_query_graph_traversal.feature	Organizing multiple subsections (@redirect, 0 scenarios)

Prohibited Patterns (ERROR)

Pattern	Example	Fix
_partN suffix	BDD-02_query_part1.feature	Use BDD-02.2.01_query.feature
Single-file	BDD-02_knowledge_engine.feature (with scenarios)	Use section-based format
features/ subdirectory	BDD-02_slug/features/	Put .feature files at suite folder root

Critical Rules

1. All .feature files in suite folder - No features/ subdirectory
2. Index file mandatory: BDD-NN.0_index.md for all suites
3. Max 500 lines per .feature file (soft limit: 400)
4. Max 12 scenarios per Feature block
5. Section metadata tags required: @section, @parent_doc, @index

Gherkin Syntax

Feature File Structure

# Traceability Tags (Gherkin-native, NOT in comments)
@section: 2.14
@parent_doc: BDD-02
@index: BDD-02.0_index.md
@brd:BRD.02.01.03
@prd:PRD.02.07.02
@ears:EARS.02.14.01

Feature: BDD-02.14: Query Result Filtering
  As a data analyst
  I want filtered query results
  So that I can focus on relevant data

  Background:
    Given the system timezone is "America/New_York"
    And the current time is "09:30:00" in "America/New_York"

  @primary @functional
  Scenario: Successful filter application
    Given valid filter criteria
    When user applies filter
    Then filtered results are returned
    And response time is less than @threshold:PRD.02.perf.api.p95_latency

Tags Placement (CRITICAL - E041)

Tags MUST be Gherkin-native, NOT in comments.

# INVALID (frameworks cannot parse comment-based tags):
# @brd: BRD.01.01.01
# @prd: PRD.01.01.01
Feature: My Feature

# VALID (Gherkin-native tags before Feature):
@brd:BRD.01.01.01
@prd:PRD.01.01.01
@ears:EARS.01.24.01
Feature: My Feature

Times and Timezones (MANDATORY)

• All times include seconds: HH:MM:SS
• Use IANA timezone format: America/New_York, America/Los_Angeles
• Avoid ambiguous abbreviations (EST/EDT/PST/PDT)

Given the current time is "14:30:00" in "America/New_York"
And the system timezone is "America/New_York"

Unified Element ID Format (MANDATORY)

Pattern: BDD.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)

Element Type	Code	Example
Test Scenario	14	BDD.02.14.01
Step	15	BDD.02.15.01

REMOVED PATTERNS - Do NOT use:

• SCENARIO-XXX, TS-XXX → Use BDD.NN.14.SS
• STEP-XXX → Use BDD.NN.15.SS
• TC-XXX → Use BDD.NN.14.SS

ADR-Ready Scoring System

Purpose: Measures BDD maturity and readiness for ADR progression.

Format in Document Control:

| **ADR-Ready Score** | ✅ 95% (Target: ≥90%) |

Status and ADR-Ready Score Mapping

ADR-Ready Score	Required Status
≥90%	Approved
70-89%	In Review
<70%	Draft

Scoring Criteria

Scenario Completeness (35%):

• All EARS statements translated to BDD scenarios: 15%
• Comprehensive coverage (success/error/edge): 15%
• Observable verification methods specified: 5%

Testability (30%):

• Scenarios are automatable: 15%
• Data-driven Examples tables used: 10%
• Performance benchmarks quantifiable: 5%

Architecture Requirements Clarity (25%):

• Performance, security, scalability quality attributes specified: 15%
• Integration points and external dependencies defined: 10%

Business Validation (10%):

• Business acceptance criteria traceable: 5%
• Measurable success outcomes defined: 5%

Quality Gate: Score <90% blocks ADR artifact creation.

Threshold Registry Integration (MANDATORY)

All quantitative values MUST use @threshold: keys. No hardcoded magic numbers.

Inline Step Format

# INVALID (hardcoded):
Then response time is less than 200ms

# VALID (threshold reference):
Then response time is less than @threshold:PRD.035.perf.api.p95_latency

Scenario Tag Format

@threshold:PRD.NN.perf.api.p95_latency
Scenario: API responds within performance threshold

Common Threshold Categories

Category	BDD Usage	Example Key
perf.*	Performance validation	perf.api.p95_latency
sla.*	SLA validation	sla.uptime.target
limit.*	Rate limit testing	limit.api.requests_per_second
timeout.*	Timeout validation	timeout.request.sync

Cumulative Tagging Requirements

Layer 4 (BDD): Must include tags from Layers 1-3 (BRD, PRD, EARS)

Tag Count: 3+ tags (@brd, @prd, @ears)

Format (Gherkin-native tags before Feature):

@brd:BRD.01.01.03
@prd:PRD.01.07.02
@ears:EARS.01.24.01
Feature: Feature Name

Tag Format Convention

Notation	Format	Artifacts	Purpose
Dash	TYPE-NN	ADR, SPEC, CTR, IPLAN	Technical artifacts - document references
Dot	TYPE.NN.TT.SS	BRD, PRD, EARS, BDD, SYS, REQ	Hierarchical artifacts - element references

Scenario Types

All 8 categories should be represented:

Category	Tag	Description
Success Path	@primary	Happy path scenarios
Alternative Path	@alternative	Optional parameters, different workflows
Error Conditions	@negative	Invalid inputs, error handling
Edge Cases	@edge_case, @boundary	Boundary conditions, limits
Data-Driven	@data_driven	Parameterized with Examples tables
Integration	@integration	External system interactions
Quality Attributes	@quality_attribute	Performance, security, reliability
Failure Recovery	@failure_recovery	Error recovery, circuit breakers

Success Path Example

@primary @functional
Scenario: User logs in successfully
  Given valid credentials
  When user submits login
  Then user is authenticated

Error Conditions Example

@negative @error_handling
Scenario: Trade rejected due to insufficient funds
  Given account balance is $1000
  When trade requires $5000
  Then trade is rejected
  And error code "INSUFFICIENT_FUNDS" is returned

Edge Cases Example

@edge_case @boundary
Scenario: Trade at exact position limit
  Given current delta is 0.499
  And position limit is 0.50
  When trade increases delta to 0.50
  Then trade is accepted

Data-Driven Example

@data_driven
Scenario Outline: Validate price precision
  Given instrument <symbol>
  When price is <price>
  Then precision should be <decimals> decimal places
  Examples:
    | symbol | price  | decimals |
    | SPY    | 450.25 | 2        |
    | AMZN   | 3250.5 | 1        |

Section Metadata Requirements

All .feature files MUST include section metadata tags:

@section: NN.SS              # Section number (e.g., 2.1, 2.14)
@parent_doc: BDD-NN          # Parent BDD suite (e.g., BDD-02)
@index: BDD-NN.0_index.md    # Index file reference
@brd:BRD.NN.EE.SS            # Upstream BRD element
@prd:PRD.NN.EE.SS            # Upstream PRD element
@ears:EARS.NN.SS.RR          # Upstream EARS requirement

For subsections, add:

@parent_section: NN.SS       # Parent section number

Feature Title Format:

Feature: BDD-NN.SS: Domain Description

Aggregator Files

Use when: Section has 5+ subsections

Requirements:

• @redirect tag MUST be present
• 0 scenarios (redirect stub only)
• List subsections in Feature description

@redirect
@section: 2.12.00
@parent_doc: BDD-02
@index: BDD-02.0_index.md

Feature: BDD-02.12: Query Graph Traversal (Aggregator)

  This is a redirect stub. Test scenarios are in subsections:
  - BDD-02.12.01_depth_first.feature - Depth-first traversal tests
  - BDD-02.12.02_breadth_first.feature - Breadth-first traversal tests

Background:
  Given the system timezone is "America/New_York"
  # No scenarios in aggregator - redirect only

Index File Template

Mandatory: BDD-NN.0_index.md for each suite

# BDD-02.0: Knowledge Engine Test Suite Index

## Suite Overview
**Purpose**: Test scenarios for Knowledge Engine functionality
**Scope**: Ingest, Query, Learning, Performance Monitoring

## Section File Map
| Section | File | Scenarios | Lines | Status | Description |
|---------|------|-----------|-------|--------|-------------|
| 02.1 | BDD-02.1_ingest.feature | 8 | 350 | Active | Ingest tests |
| 02.2 | BDD-02.2_query.feature | 10 | 420 | Active | Query tests |

## Traceability Matrix
| BDD Section | Upstream Source | Description |
|-------------|----------------|-------------|
| BDD-02.1 | EARS.02.01-05 | Ingest requirements |
| BDD-02.2 | EARS.02.06-12 | Query requirements |

Creation Process

Step 1: Read Upstream Artifacts

Read BRD, PRD, and EARS to understand requirements to test.

Step 2: Reserve Suite ID

Check docs/BDD/ for next available ID (e.g., BDD-01, BDD-02).

Step 3: Create Suite Folder

mkdir -p docs/BDD/BDD-02_knowledge_engine/

Step 4: Create Index File

cp ai_dev_flow/BDD/BDD-SECTION-0-TEMPLATE.md docs/BDD/BDD-02_knowledge_engine/BDD-02.0_index.md

Step 5: Design Section Split

• Identify logical domains or EARS groupings
• Estimate scenarios per section (target: 6-10)
• Plan for subsections if needed (>500 lines)

Step 6: Create Section Files

cp ai_dev_flow/BDD/BDD-SECTION-TEMPLATE.feature docs/BDD/BDD-02_knowledge_engine/BDD-02.1_ingest.feature

Step 7: Add Section Metadata Tags

• @section, @parent_doc, @index
• Upstream traceability: @brd, @prd, @ears

Step 8: Write Scenarios

For each requirement from EARS/PRD:

1. Success path scenario
2. Error condition scenarios (2-3)
3. Edge case scenarios (1-2)
4. Scenario outlines for parameterized tests

Step 9: Replace Magic Numbers with Thresholds

• Add to PRD threshold registry first if key missing
• Use @threshold:PRD.NN.category.key format

Step 10: Create Redirect Stub

# Create redirect stub at docs/BDD/ root
touch docs/BDD/BDD-02_knowledge_engine.feature

Add minimal content with @redirect tag and 0 scenarios.

Step 11: Update Index File

• List all section files with scenario counts
• Add traceability matrix

Step 12: Validate BDD Suite

python3 scripts/validate_bdd_suite.py --root BDD

Step 13: Commit Changes

Commit suite folder and redirect stub together.

Validation

Validation Error Codes Reference

Code	Description	Severity
E001	Document Control fields missing	ERROR
E002	Gherkin syntax invalid	ERROR
E003	ADR-Ready Score format invalid	ERROR
E004	Upstream traceability tags missing	ERROR
E041	Tags in comments (not Gherkin-native)	ERROR
E008	Element ID format invalid	ERROR
CHECK 9.1	File naming pattern invalid	ERROR
CHECK 9.2	Prohibited pattern detected	ERROR
CHECK 9.3	Aggregator requirements not met	ERROR
CHECK 9.4	File size exceeds limits	ERROR
CHECK 9.5	Section metadata tags missing	ERROR
CHECK 9.6	Index file missing	ERROR
CHECK 9.7	Non-Gherkin content in .feature file	ERROR

Manual Checklist

File Structure:

• All .feature files in suite folder (no features/ subdirectory)
• Index file exists: BDD-NN.0_index.md
• Redirect stub at docs/BDD/BDD-NN_slug.feature (0 scenarios)
• No file exceeds 500 lines
• No Feature block exceeds 12 scenarios

File Naming:

• All files match one of 3 valid patterns
• No prohibited patterns (_partN, single-file)

Tags and Metadata:

• Tags are Gherkin-native (NOT in comments)
• Section metadata: @section, @parent_doc, @index
• Cumulative tags: @brd, @prd, @ears
• All quantitative values use @threshold: keys
• Times include seconds (HH:MM:SS) with IANA timezone

Scenarios:

• All 8 scenario categories represented
• Given-When-Then structure
• No subjective language ("fast", "reliable")
• Observable outcomes in Then steps

Aggregators (if applicable):

• Has @redirect tag
• Has 0 scenarios
• Lists subsections in Feature description

Common Pitfalls

Mistake	Correction
Tags in comments # @brd:	Use Gherkin-native @brd: before Feature
ADR-Ready Score: 95%	Use ✅ 95% (Target: ≥90%)
response time < 200ms (hardcoded)	Use @threshold:PRD.NN.perf.api.p95_latency
.feature in features/ subdir	Put at suite folder root
BDD-02_query_part1.feature	Use BDD-02.2.01_query.feature
Missing @ears tag	All 3 upstream tags are MANDATORY
Only success scenarios	Include all 8 scenario categories
Status: Approved (with <90% score)	Use Status: In Review or Draft
File >500 lines	Split into subsections
09:30 (no seconds)	Use 09:30:00
EST timezone	Use America/New_York

Post-Creation Validation (MANDATORY)

CRITICAL: Execute validation loop IMMEDIATELY after document creation.

Automatic Validation Loop

LOOP:
  1. Run: python scripts/validate_bdd_suite.py --root BDD
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review
  5. IF clean: Mark VALIDATED, proceed

Quality Gate

Blocking: YES - Cannot proceed to ADR creation until validation passes with 0 errors.

---

Reserved ID Exemption

Pattern: BDD-000_*.md or BDD-000_*.feature

Scope: Documents with reserved ID 000 are FULLY EXEMPT from validation.

Document Types:

• Index documents (BDD-000_index.md)
• Traceability matrix templates
• Glossaries, registries, checklists

---

Next Skill

After creating BDD, use:

doc-adr - Create Architecture Decision Records (Layer 5)

The ADR will:

• Document architectural decisions for topics identified in BRD/PRD
• Include @brd, @prd, @ears, @bdd tags (cumulative)
• Use Context-Decision-Consequences format
• Reference BDD scenarios that validate the architecture

Related Resources

• Template: ai_dev_flow/BDD/BDD-SECTION-TEMPLATE.feature
• Index Template: ai_dev_flow/BDD/BDD-SECTION-0-TEMPLATE.md
• Subsection Template: ai_dev_flow/BDD/BDD-SUBSECTION-TEMPLATE.feature
• Aggregator Template: ai_dev_flow/BDD/BDD-AGGREGATOR-TEMPLATE.feature
• Creation Rules: ai_dev_flow/BDD/BDD_CREATION_RULES.md
• Validation Rules: ai_dev_flow/BDD/BDD_VALIDATION_RULES.md
• Splitting Rules: ai_dev_flow/BDD/BDD_SPLITTING_RULES.md
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
• ID Standards: ai_dev_flow/ID_NAMING_STANDARDS.md

Quick Reference

Item	Value
Purpose	Define executable test scenarios
Layer	4
Tags Required	@brd, @prd, @ears (3 tags)
ADR-Ready Score	≥90% required for "Approved" status
Element ID Format	BDD.NN.14.SS (scenarios), BDD.NN.15.SS (steps)
File Structure	Nested suite folder: docs/BDD/BDD-NN_{slug}/
Max File Size	500 lines (soft: 400)
Max Scenarios	12 per Feature block
Time Format	HH:MM:SS with IANA timezone
Quantitative Values	Use @threshold:PRD.NN.category.key
Next Skill	doc-adr