1. Parse input: Extract TYPE and NN from "{TYPE}-{NN}"
2. Determine action:
   - IF TYPE == "BDD": Review Mode
   - ELSE IF TYPE == "EARS": Generate/Find Mode
   - ELSE: Error (invalid type for this autopilot)
3. For Generate/Find Mode:
   - Check: Does BDD-{NN} exist in docs/04_BDD/?
   - IF exists: Switch to Review Mode for BDD-{NN}
   - ELSE: Proceed with Generation from EARS-{NN}

undefined

undefined

undefined

undefined

Input: EARS-01
├── Detected Type: EARS (upstream)
├── Expected BDD: BDD-01
├── BDD Exists: Yes → docs/04_BDD/BDD-01_f1_iam/
└── Action: REVIEW MODE - Running doc-bdd-reviewer on BDD-01

Input: EARS-05
├── Detected Type: EARS (upstream)
├── Expected BDD: BDD-05
├── BDD Exists: No
└── Action: GENERATE MODE - Creating BDD-05 from EARS-05

Input: BDD-03
├── Detected Type: BDD (self)
└── Action: REVIEW MODE - Running doc-bdd-reviewer on BDD-03

flowchart TD
    subgraph Phase1["Phase 1: EARS Analysis"]
        A[Input: EARS List] --> B[Read EARS Documents]
        B --> C[Extract EARS Statements]
        C --> D[Categorize by Statement Type]
        D --> E[Identify Quality Attributes]
        E --> F[Extract Threshold References]
    end

    subgraph Phase2["Phase 2: BDD Readiness Check"]
        F --> G{Next EARS}
        G --> H[Check BDD-Ready Score]
        H --> I{Score >= 90?}
        I -->|No| J[Auto-Fix EARS Issues]
        J --> K[Re-validate EARS]
        K --> I
        I -->|Yes| L[Mark EARS Ready]
    end

    subgraph Phase3["Phase 3: BDD Generation"]
        L --> M[Plan Section Structure]
        M --> N[Generate Feature Files]
        N --> O[Generate Success Path Scenarios]
        O --> P[Generate Error Condition Scenarios]
        P --> Q[Generate Edge Case Scenarios]
        Q --> R[Generate Data-Driven Scenarios]
        R --> S[quality-advisor: Real-time Feedback]
        S --> T[Add Quality Attribute Scenarios]
        T --> U[Add Cumulative Tags]
        U --> V[Write BDD Files]
    end

    subgraph Phase4["Phase 4: BDD Validation"]
        V --> W[Run doc-bdd-validator]
        W --> X{ADR-Ready >= 90?}
        X -->|No| Y[Auto-Fix BDD Issues]
        Y --> Z[Re-validate BDD]
        Z --> X
        X -->|Yes| AA[Validation Passed]
    end

    subgraph Phase5["Phase 5: Final Review"]
        AA --> AB[Check Gherkin Syntax Compliance]
        AB --> AC[Verify Threshold References]
        AC --> AD[Validate Cumulative Tags]
        AD --> AE[Check Scenario Coverage]
        AE --> AF{Review Passed?}
        AF -->|No| AG[Flag Issues]
        AG --> AH[Auto-Fix or Manual]
        AH --> AF
        AF -->|Yes| AI[Mark BDD Complete]
    end

    AI --> AJ{More EARS?}
    AJ -->|Yes| G
    AJ -->|No| AK[Generate Summary Report]
    AK --> AL[Complete]

undefined

**Output**: Scenario catalog with categorization hints, threshold references, and traceability links.

python ai_dev_flow/scripts/validate_bdd_ready.py \
  --ears docs/03_EARS/EARS-01_{slug}/ \
  --min-score 90 \
  --auto-fix

python ai_dev_flow/scripts/validate_bdd.py docs/04_BDD/BDD-NN_{slug}/ --verbose

LOOP (max 3 iterations):
  1. Run doc-bdd-validator
  2. IF errors found: Apply auto-fixes
  3. IF warnings found: Review and address if critical
  4. IF ADR-Ready Score < 90%: Enhance scenarios
  5. IF clean: Mark VALIDATED, proceed
  6. IF max iterations: Log issues, flag for manual review

flowchart TD
    A[Phase 5 Start] --> B[Run doc-bdd-reviewer]
    B --> C[Generate Review Report]
    C --> D{Review Score >= 90?}

    D -->|Yes| E[PASS - Proceed to Phase 6]
    D -->|No| F{Iteration < Max?}

    F -->|Yes| G[Run doc-bdd-fixer]
    G --> H[Apply Fixes]
    H --> I[Generate Fix Report]
    I --> J[Increment Iteration]
    J --> B

    F -->|No| K[Flag for Manual Review]
    K --> L[Generate Final Report with Remaining Issues]
    L --> E

/doc-bdd-reviewer BDD-NN

/doc-bdd-fixer BDD-NN --revalidate

/doc-bdd-reviewer BDD-NN

Iteration 1:
  Review v001: Score 84 (3 errors, 6 warnings)
  Fix v001: Fixed 7 issues, added 5 threshold references

Iteration 2:
  Review v002: Score 92 (0 errors, 4 warnings)
  Status: PASS (score >= 90)

@primary @functional
Scenario: User successfully authenticates with valid credentials
  Given user has valid credentials
  And authentication service is available
  When user submits authentication request
  Then user session is created
  And session token is returned
  And response time is less than @threshold:PRD.01.auth.response.p95

@alternative @optional_params
Scenario: User authenticates with remember-me option
  Given user has valid credentials
  When user submits authentication with remember-me enabled
  Then extended session token is returned
  And session expiry is set to @threshold:PRD.01.session.extended_ttl

@negative @error_handling
Scenario: Authentication fails with invalid credentials
  Given user has invalid credentials
  When user submits authentication request
  Then authentication is rejected
  And error code "AUTH_INVALID_CREDENTIALS" is returned
  And failed attempt is logged

@edge_case @boundary
Scenario: Session expires at exact timeout boundary
  Given session was created at "09:00:00" in "America/New_York"
  And session timeout is @threshold:PRD.01.session.idle_timeout
  When current time reaches session expiry
  Then session is invalidated
  And user is prompted to re-authenticate

@data_driven
Scenario Outline: Validate user role authorization
  Given user has role <role>
  When user attempts to access <resource>
  Then access is <result>

  Examples:
    | role    | resource    | result  |
    | admin   | /admin      | granted |
    | user    | /admin      | denied  |
    | user    | /dashboard  | granted |
    | guest   | /dashboard  | denied  |

@integration @external_api
Scenario: System integrates with external identity provider
  Given external identity provider is configured
  When user initiates SSO authentication
  Then system redirects to identity provider
  And callback is processed within @threshold:PRD.01.sso.callback_timeout

@quality_attribute @performance
Scenario: Authentication endpoint meets performance SLA
  Given system is under normal load
  When 100 concurrent authentication requests are submitted
  Then p95 response time is less than @threshold:PRD.01.perf.auth.p95_latency
  And no requests fail due to timeout

@failure_recovery @circuit_breaker
Scenario: Authentication service recovers from database failure
  Given database connection fails
  When authentication request is received
  Then circuit breaker activates
  And fallback authentication is attempted
  And service recovers within @threshold:PRD.01.recovery.max_time

@scenario-type:success @p0-critical
Scenario: Authentication completes within performance threshold
  Given user has valid credentials
  When user submits authentication request
  Then the system SHALL authenticate the user
  And the response SHALL be returned WITHIN @threshold:PRD.01.perf.auth.p95_latency

@section: NN.SS
@parent_doc: BDD-NN
@index: BDD-NN.0_index.md
@brd:BRD.NN.01.SS
@prd:PRD.NN.07.SS
@ears:EARS.NN.25.SS

Feature: BDD-NN.SS: [Feature Name]
  As a [role]
  I want [feature]
  So that [benefit]

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

  @scenario-type:success @p0-critical @scenario-id:BDD.NN.14.01
  Scenario: [Primary success path description]
    Given [precondition from EARS WHEN clause]
    When [action from EARS trigger]
    Then the system SHALL [outcome from EARS SHALL clause]
    And the response SHALL be returned WITHIN @threshold:PRD.NN.perf.api.p95_latency

  @scenario-type:error @p1-high @scenario-id:BDD.NN.14.10
  Scenario: [Error condition] results in [expected behavior]
    Given [error precondition from EARS IF clause]
    When [action that triggers error]
    Then the system SHALL NOT [prevented behavior]
    And error code "[ERROR_CODE]" SHALL be returned WITHIN @threshold:PRD.NN.timeout.error.response

  @scenario-type:recovery @p1-high @scenario-id:BDD.NN.14.20
  Scenario: System recovers from [failure type]
    Given [failure condition]
    When [recovery trigger]
    Then the system SHALL recover WITHIN @threshold:PRD.NN.recovery.max_time
    And circuit breaker state SHALL transition to "half-open"

  @scenario-type:parameterized @p2-medium @scenario-id:BDD.NN.14.30
  Scenario Outline: [Parameterized test description]
    Given [context with <variable>]
    When [action with <variable>]
    Then the system SHALL [outcome with <expected>]

    Examples:
      | variable | expected |
      | value1   | result1  |
      | value2   | result2  |

  @scenario-type:optional @p2-medium @scenario-id:BDD.NN.14.40
  Scenario: [Alternative path with optional parameter]
    Given [optional context]
    When [alternative action]
    Then the system SHALL [alternative outcome]

undefined

undefined

undefined

**Batch Configuration** (`config/bdd_batch.yaml`):

```yaml
bdd_generation:
  - id: "01"
    slug: "f1_iam_scenarios"
    ears: "EARS-01"
    priority: 1

  - id: "02"
    slug: "f2_data_scenarios"
    ears: "EARS-02"
    priority: 2

  - id: "03"
    slug: "f3_api_scenarios"
    ears: "EARS-03"
    priority: 2

execution:
  parallel: false
  fail_fast: true

python ai_dev_flow/scripts/bdd_autopilot.py \
  --ears docs/03_EARS/EARS-01_f1_iam/ \
  --dry-run

undefined

**Review Process**:

```mermaid
flowchart TD
    A[Input: Existing BDD] --> B[Load BDD Documents]
    B --> C[Run Validation Checks]
    C --> D[Calculate ADR-Ready Score]
    D --> E[Identify Issues]
    E --> F[Categorize Issues]
    F --> G{Generate Report}
    G --> H[Fixable Issues List]
    G --> I[Manual Review Items]
    G --> J[Score Breakdown]
    H --> K[Output: Review Report]
    I --> K
    J --> K

undefined

**Review Configuration**:

```yaml
review_mode:
  enabled: true
  checks:
    - structure_validation      # Index, sections, redirects
    - gherkin_syntax           # Given-When-Then compliance
    - tag_validation           # Cumulative tags, scenario tags
    - threshold_references     # @threshold format and validity
    - v2_compliance            # Scenario types, priorities, WITHIN
    - coverage_analysis        # 5-category coverage
    - score_calculation        # ADR-Ready score
  output:
    format: markdown           # markdown, json, html
    include_line_numbers: true
    include_fix_suggestions: true
  thresholds:
    pass: 90
    warning: 85
    fail: 0

undefined

**Fix Process**:

```mermaid
flowchart TD
    A[Input: Existing BDD] --> B[Run Review Mode]
    B --> C[Identify Fixable Issues]
    C --> D{Backup Enabled?}
    D -->|Yes| E[Create Backup]
    D -->|No| F[Skip Backup]
    E --> G[Apply Fixes by Category]
    F --> G

    subgraph FixCategories["Fix Categories"]
        G --> H[Structure Fixes]
        G --> I[Tag Fixes]
        G --> J[Threshold Fixes]
        G --> K[Syntax Fixes]
        G --> L[v2.0 Compliance Fixes]
    end

    H --> M[Preserve Manual Content]
    I --> M
    J --> M
    K --> M
    L --> M

    M --> N[Re-validate]
    N --> O{Score Improved?}
    O -->|Yes| P[Generate Fix Report]
    O -->|No| Q[Log Warnings]
    Q --> P
    P --> R[Output: Fixed BDD + Report]

undefined

**Fix Configuration**:

```yaml
fix_mode:
  enabled: true
  backup:
    enabled: true
    location: "tmp/backup/"
    retention_days: 7

  fix_categories:
    structure: true          # Index, redirects
    tags: true               # Scenario tags, cumulative tags
    thresholds: true         # @threshold references
    syntax: false            # Gherkin syntax (risky, disabled by default)
    v2_compliance: true      # Scenario types, priorities, WITHIN

  preservation:
    step_definitions: true   # Never modify step text
    examples_data: true      # Never modify Examples tables
    comments: true           # Preserve user comments
    custom_tags: true        # Preserve non-standard tags

  validation:
    re_validate_after_fix: true
    require_score_improvement: false
    max_fix_iterations: 3

undefined

undefined

EARS: EARS-01, EARS-02, EARS-03, EARS-04, EARS-05, EARS-06, EARS-07

Chunk 1: [EARS-01, EARS-02, EARS-03] → Process → Summary → Pause
Chunk 2: [EARS-04, EARS-05, EARS-06] → Process → Summary → Pause
Chunk 3: [EARS-07]                    → Process → Summary → Complete

Chunk N/M Complete:
├── Generated: BDD-01, BDD-02, BDD-03
├── ADR-Ready Scores: 94%, 92%, 91%
├── Status: All validated
└── Next: Continue with Chunk N+1? [Y/n]

def handle_error(error_type: str, context: dict) -> Action:
    match error_type:
        case "EARS_MISSING":
            return Action.ABORT_WITH_MESSAGE
        case "BDD_READY_LOW":
            return Action.AUTO_FIX_EARS
        case "VALIDATION_FAILURE":
            if context["retry_count"] < 3:
                return Action.AUTO_FIX_RETRY
            return Action.FLAG_MANUAL_REVIEW
        case "ADR_READY_LOW":
            return Action.ENHANCE_SCENARIOS
        case _:
            return Action.FLAG_MANUAL_REVIEW

undefined

undefined

undefined