doc-bdd-reviewer

Purpose

Comprehensive content review and quality assurance for Behavior-Driven Development (BDD) documents. This skill performs deep content analysis beyond structural validation, checking Gherkin syntax correctness, scenario completeness, EARS alignment, step definition reusability, and identifying issues that require manual review.

Layer: 4 (BDD Quality Assurance)

Upstream: BDD (from doc-bdd-autopilot or doc-bdd)

Downstream: None (final QA gate before ADR generation)

When to Use This Skill

Use doc-bdd-reviewer when:

• After BDD Generation: Run immediately after doc-bdd-autopilot completes
• Manual BDD Edits: After making manual changes to BDD scenarios
• Pre-ADR Check: Before running doc-adr-autopilot
• Periodic Review: Regular quality checks on existing BDD
• CI/CD Integration: Automated review gate in documentation pipelines

Do NOT use when:

• BDD does not exist yet (use doc-bdd or doc-bdd-autopilot first)
• Need structural/schema validation only (use doc-bdd-validator)
• Generating new BDD content (use doc-bdd)

Skill vs Validator: Key Differences

Review Workflow

flowchart TD
    A[Input: BDD Path] --> B[Load BDD Files]
    B --> B2[0. Structure Compliance]
    B2 --> B3{Structure Valid?}
    B3 -->|No| B4[BLOCKING - Stop Review]
    B3 -->|Yes| C{Single or Multiple Features?}

    C -->|Multiple| D[Load All Feature Files]
    C -->|Single| E[Load Single File]

    D --> F[Run Review Checks]
    E --> F

    subgraph Review["Review Checks"]
        F --> G[1. Gherkin Syntax Compliance]
        G --> H[2. Scenario Completeness]
        H --> I[3. EARS Alignment]
        I --> J[4. Step Definition Reusability]
        J --> K[5. Data Table Validation]
        K --> L[6. Placeholder Detection]
        L --> M[7. Naming Compliance]
        M --> M2[8. Upstream Drift Detection]
    end

    M2 --> N{Issues Found?}
    N -->|Yes| O[Categorize Issues]
    O --> P{Auto-Fixable?}
    P -->|Yes| Q[Apply Auto-Fixes]
    Q --> R[Re-run Affected Checks]
    P -->|No| S[Flag for Manual Review]
    R --> N
    S --> T[Generate Report]
    N -->|No| T
    T --> U[Calculate Review Score]
    U --> V{Score >= Threshold?}
    V -->|Yes| W[PASS]
    V -->|No| X[FAIL with Details]

Review Checks

0. Structure Compliance (12/12) – BLOCKING

Validates BDD follows the mandatory nested folder rule.

Nested Folder Rule: ALL BDD documents MUST be in nested folders.

Required Structure:

Error Codes:

This check is BLOCKING – BDD must pass structure validation before other checks proceed.

1. Gherkin Syntax Compliance

Validates all scenarios follow correct Gherkin syntax.

Scope:

• Feature files have proper structure
• Given-When-Then order correct
• Background used appropriately
• Scenario Outline with Examples
• Tags properly formatted

Error Codes:

2. Scenario Completeness

Validates scenarios cover all requirement aspects.

Scope:

• Happy path covered
• Error conditions tested
• Edge cases identified
• Boundary values checked
• Negative scenarios present

Error Codes:

3. EARS Alignment

Validates BDD scenarios trace to EARS requirements.

Scope:

• Every scenario maps to EARS requirement
• No orphaned scenarios
• Coverage complete for all EARS
• Feature IDs consistent

Error Codes:

4. Step Definition Reusability

Analyzes step definitions for reuse potential.

Scope:

• Similar steps identified
• Parameterized steps suggested
• Duplicate steps flagged
• Step library consistency

Error Codes:

5. Data Table Validation

Validates Examples and data tables are complete.

Scope:

• Examples table has headers
• Data rows present
• Column values appropriate
• Boundary values included

Error Codes:

6. Placeholder Detection

Identifies incomplete content requiring replacement.

Error Codes:

7. Naming Compliance

Validates element IDs follow doc-naming standards.

Scope:

• Element IDs use BDD.NN.TT.SS format
• Element type codes valid for BDD (35, 36, 37)
• No legacy patterns (SC-NNN, TC-NNN)

Error Codes:

8. Upstream Drift Detection (Mandatory Cache)

Detects when upstream source documents have been modified after the BDD was created or last updated.

Purpose: Identifies stale BDD content that may not reflect current EARS documentation.

The drift cache is mandatory – the reviewer MUST create/update it after every review.

Scope:

• @ref: tag targets
• @ears: tag references
• Traceability section upstream artifact links

Drift Cache File (MANDATORY)

Location: docs/04_BDD/.drift_cache.json

Cache Schema:

{
  "cache_version": "1.0",
  "last_updated": "2026-02-10T17:00:00Z",
  "upstream_type": "EARS",
  "documents": {
    "BDD-01_f1_iam.feature": {
      "bdd_hash": "sha256:abc123...",
      "bdd_mtime": "2026-02-10T15:00:00Z",
      "upstream_refs": {
        "docs/03_EARS/EARS-01_f1_iam.md": {
          "content_hash": "sha256:def456...",
          "version": "1.2",
          "mtime": "2026-02-09T12:00:00Z",
          "sections_referenced": ["REQ-F1-001", "REQ-F1-002"]
        }
      },
      "last_review": "2026-02-10T16:30:00Z",
      "drift_status": "fresh"
    }
  }
}

Three-Phase Detection Algorithm

Phase 1: Load Cache

1. Check if .drift_cache.json exists
2. If exists, load and validate schema
3. If not exists, initialize empty cache structure

Phase 2: Detect Drift

1. For each BDD document being reviewed:
   • Extract all @ears: and @ref: references
   • For each upstream reference:
     • Calculate current content hash
     • Compare with cached hash
     • Check mtime and version fields
   • Flag drift if any mismatch detected

Phase 3: Update Cache (MANDATORY)

1. Update document entry with current hashes
2. Update last_review timestamp
3. Set drift_status based on detection results
4. Write cache file atomically
5. Log cache update in review report

Hash Calculation

import hashlib

def calculate_content_hash(file_path: str) -> str:
    """Calculate SHA-256 hash of file content."""
    with open(file_path, 'rb') as f:
        content = f.read()
    return f"sha256:{hashlib.sha256(content).hexdigest()}"

Detection Methods:

Error Codes:

Report Output:

### Drift Detection Results

**Cache Status**: Updated (docs/04_BDD/.drift_cache.json)
**Documents Checked**: 5
**Fresh**: 4
**Drifted**: 1 (BDD-03_f3_observability.feature)

| Document | Upstream | Status | Hash Match | Details |
|----------|----------|--------|------------|---------|
| BDD-01 | EARS-01 | Fresh | Yes | - |
| BDD-03 | EARS-03 | Drifted | No | Section 4.2 modified |

Configuration:

Review Score Calculation

Scoring Formula:

Total: Sum of all categories (max 100)

Thresholds:

• PASS: ≥ 90
• WARNING: 80-89
• FAIL: < 80

Command Usage

# Review specific BDD
/doc-bdd-reviewer BDD-01

# Review BDD by path
/doc-bdd-reviewer docs/04_BDD/BDD-01_f1_iam.feature

# Review all BDD
/doc-bdd-reviewer all

Output Report

Review reports are stored alongside the reviewed document per project standards.

Nested Folder Rule: ALL BDD suites use nested folders (BDD-NN_{slug}/). This ensures review reports, fix reports, and drift cache files are organized with their parent document.

File Naming: BDD-NN.R_review_report_vNNN.md

Location: Inside the BDD nested folder: docs/04_BDD/BDD-NN_{slug}/

Versioning Rules

1. First Review: Creates BDD-NN.R_review_report_v001.md
2. Subsequent Reviews: Auto-increments version (v002, v003, etc.)
3. Same-Day Reviews: Each review gets unique version number

Version Detection: Scans folder for existing BDD-NN.R_review_report_v*.md files and increments.

Example:

docs/04_BDD/BDD-01_f1_iam/
├── BDD-01.0_index.md
├── BDD-01.1_authentication.feature
├── BDD-01.2_authorization.feature
├── BDD-01.R_review_report_v001.md    # First review
├── BDD-01.R_review_report_v002.md    # After fixes
└── .drift_cache.json

Delta Reporting

When previous reviews exist, include score comparison in the report.

See REVIEW_DOCUMENT_STANDARDS.md for complete versioning requirements.

Integration with doc-bdd-autopilot

This skill is invoked during Phase 5 of doc-bdd-autopilot:

flowchart LR
    A[Phase 4: Validation] --> B[Phase 5: Final Review]
    B --> C{doc-bdd-reviewer}
    C --> D[Phase 6: Continue]

Related Skills

Version History