| name | doc-bdd |
| description | Create Behavior-Driven Development (BDD) scenarios - Layer 4 of the SDD flow, translating EARS requirements into executable Given-When-Then acceptance scenarios with req-to-SPEC trace links. Use after EARS, before ADR. Single-document authoring primitive; for end-to-end or batch generation the autopilot (`doc-bdd-autopilot`) drives this skill. |
| metadata | {"tags":["sdd-workflow","layer-4-artifact"],"custom_fields":{"layer":4,"artifact_type":"BDD","skill_category":"core-workflow","upstream_artifacts":["EARS"],"downstream_artifacts":["ADR","SPEC","TDD","IPLAN"],"version":"0.24.0","framework_spec_version":"0.40.0","last_updated":"2026-05-23","adapts":["section_toggles","glossary"]}} |
doc-bdd
Purpose
Create Behavior-Driven Development (BDD) scenarios — Layer 4 of the SDD
flow. A BDD suite translates EARS formal requirements into structured YAML
scenarios (Given/When/Then phase lists carried in a ```yaml block, NOT
Gherkin @-tags), each carrying an element-level ears: trace list and a
spec_trace link forward to the SPEC sections it exercises. (If a runner ever
needs .feature files, the YAML is the source of record and a .feature
emitter can be authored on demand — no such emitter ships today; the only
shipped transcoder is the one-off reverse-direction tools/gherkin_to_bdd_yaml.py
used to migrate legacy Gherkin into the YAML form.)
Layer: 4. Upstream: EARS (per the necessary-upstream contract;
upstream PRD/BRD lineage is reachable transitively via the @-tag chain).
Downstream: ADR → SPEC → TDD → IPLAN → Code.
BDD scenarios are the acceptance source of truth that TDD (Layer 7) maps to
concrete test cases. Execution is QA-staging only — never run BDD in CI
(use TDD unit/integration tests for CI).
When to Use
Use doc-bdd when:
- EARS (Layer 3) exists and you need executable acceptance scenarios.
- Validating EARS requirements with concrete Given-When-Then behaviors.
- Defining the req-to-SPEC trace bridge (
spec_trace) before ADR/SPEC.
For end-to-end generation from EARS, a prompt, or an IPLAN, use
../doc-bdd-autopilot/SKILL.md. Create upstream artifacts first; never invent
placeholders like EARS-XXX or reference documents that do not yet exist.
Prerequisites
BDD is Layer 4, so the required upstream EARS must already exist. Confirm it
and read the spec before writing:
- Template (source of truth):
${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml
- Layer README:
${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/README.md
- ID & tag standards:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
- Authoring style:
${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
Verify upstream and check for ID collision:
ls docs/03_EARS/ docs/04_BDD/ 2>/dev/null. Reference only existing EARS
elements in trace tags; upstream PRD/BRD lineage is reachable transitively
via the EARS document's own @-tag chain.
Layer Guidance
Required structure (5 sections)
Per BDD-TEMPLATE.yaml, every BDD document carries:
- Document Control — version, status, dates, author, priority, plus the
ADR-Ready score. (No
@ears/@prd/@brd reference rows — upstream trace
lives on each scenario's ears: list.)
- Feature Definition — a
```yaml feature: block: name matching the
EARS requirement, an As a / I want / So that description, and a background
(bare step text + IANA timezone, default America/New_York). The feature
carries no ears — its EARS coverage is the union of its scenarios.
- Scenario Structure — a
```yaml scenarios: flat list (Given/When/Then
phase lists), each with a type: across the five categories (below).
- Traceability — the derived coverage summary + downstream expectations and
the health/coverage score.
- Glossary — flat list of project-specific terms.
See BDD-TEMPLATE.yaml for per-section content and the normative scenario schema.
Scenario categories (Section 3)
Every scenario is a YAML mapping with id: BDD.NN.03.xxxx, name, type,
priority (p0-critical … p3-low), an element-level ears: list, given /
when / then phase lists, and a spec_trace list (notes optional).
| Category | type: value | Min | Priority |
|---|
| success | success | 1 / EARS | p0–p1 |
| error | error | 1 / error | p1–p2 |
| recovery | recovery | 1 / circuit-breaker | p1 |
| parameterized | parameterized | 1 / multi-value | p1–p2 |
| optional | optional | 1 / optional param | p2–p3 |
A parameterized scenario adds outline: true + examples: {headers, rows}.
Scenario YAML rules
- Scenarios are structured YAML, not Gherkin
@-tags. Trace is the
ears: list (element-level only — REFGRAN01 rejects doc-form EARS-NN);
id/type/priority are fields, not tags.
- Times include seconds (
HH:MM:SS) with IANA timezones (America/New_York),
never abbreviations like EST.
- Quantitative values use
@threshold: keys written inline in the step
prose (e.g. … WITHIN @threshold:PRD.NN.perf.api.p95) — no magic numbers.
- Keep scenarios atomic (one behavior each). One BDD document per module up to
~50,000 tokens; beyond that, start a new self-contained BDD document.
Element IDs and upstream trace
- Hierarchical element IDs:
BDD.{doc_id}.{section_id}.{hash} (e.g.
BDD.01.03.d7a2). Emit a stable 4-hex-char identifier per element, distinct within its section (HASH01); extend to 8 on collision. Do not compute SHA-256 in this prompt — the hash form is the canonicalization TARGET produced by a deterministic tool pass, and byte-exact field extraction is defined for BRD §7 only (Phase 2+ for BDD). Authority: framework/governance/ID_NAMING_STANDARDS.md.
Scenarios live in section 03, in each scenario's id: field.
- BDD's required upstream trace is each scenario's element-level
ears: list
(per the necessary-upstream contract — satisfies required_tags: [ears]).
Downstream artifacts cite BDD scenarios with @bdd: BDD.01.03.8f4c tags
(unchanged). Upstream PRD/BRD lineage is reachable transitively via the EARS
document's own @-tag chain — do not emit @brd:/@prd:/@ears tags on BDD.
- Removed patterns (do not use):
SCENARIO-XXX, SCEN-XXX, TS-XXX,
STEP-XXX, numeric type-codes, the legacy 3-segment BDD.NN.xxxx, and
Gherkin @ears/@scenario-type/@scenario-id tags (now YAML fields).
Downstream trace (spec_trace)
Each scenario records the SPEC sections it maps to, e.g.
spec_trace: ["SPEC Section 3 (Interfaces)", "SPEC Section 5 (Behavior)"].
This is the req-to-SPEC bridge that downstream layers consume.
Creation Process
- Read upstream — the EARS that drives this BDD (and, via its @-tag
chain, the PRD/BRD it derives from) to understand the behaviors to test.
- Reserve ID — next free
BDD-NN (two digits, no extra leading zero:
BDD-01, BDD-99, BDD-102).
Per-layer independence (CLEANUP-PR-F item 18): pick the next-free
number in YOUR layer's index — the upstream's number is NOT your number
(doc numbers are per-layer sequential and independent; see
framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality).
- Create the document from
${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml;
complete all 5 sections, Document Control first.
- Write the
feature: block + the scenarios: list (YAML) per EARS
requirement across the five categories; each scenario carries id, type,
priority, an element-level ears: list, given/when/then phase lists,
inline @threshold:, and spec_trace. Add the feature background.
- Set each scenario's element-level
ears: list (this is the required
upstream trace) and a unique id: — no Gherkin @-tags.
- Update the BDD index
docs/04_BDD/BDD-00_index.md in the same change.
- Validate (below) and commit the BDD and index together.
Validation
This skill is the validator (no runtime code). Apply against ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/README.md and ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md.
Error codes (all severity error): XDOC-006 tag format invalid · XDOC-008 broken internal link · XDOC-009 missing traceability section.
Quality gate (blocking): ADR-Ready score ≥ 90/100 before moving on. If
issues are found, fix and re-check; if unfixable, log for manual review.
Next Skill
../doc-adr/SKILL.md — the ADR references this BDD (@bdd: BDD.NN.SS.xxxx)
along with its required @ears, records architecture decisions in
Context-Decision-Consequences form, and cites the BDD scenarios that validate
each decision.
Adaptation
Read .aidoc/profile.yaml; honor only this skill's knobs
(section_toggles, glossary). Ignore unknown keys; absent a profile, use
framework defaults. Authority:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md.
Related Resources
- Template / authoring rules:
${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml
- Layer README:
${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/README.md
- Index template:
${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-00_index.TEMPLATE.md
- ID & tag standards:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
- Quality gate:
../doc-bdd-audit/SKILL.md · Fixes: ../doc-bdd-fixer/SKILL.md
- Generation pipeline:
../doc-bdd-autopilot/SKILL.md
Quick Reference
| |
|---|
| Purpose | Structured YAML Given/When/Then acceptance scenarios |
| Layer | 4 |
| Upstream trace | scenario ears: lists (per necessary-upstream contract) |
| Key idea | EARS → YAML scenarios with spec_trace to SPEC |
| Must include | Document Control (first), 5 scenario categories, thresholds |
| Execution | QA staging only — never CI |
| Next | doc-adr |
