doc-ears-autopilot（博士耳朵自动驾驶仪）

doc-ears-autopilot

Purpose

Automated EARS (Easy Approach to Requirements Syntax) generation pipeline that processes PRD documents and generates formal EARS statements with readiness validation, statement categorization, and BDD-Ready score compliance.

Layer: 3 (EARS Generation)

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

Downstream Artifacts: BDD (Layer 4), ADR (Layer 5), SYS (Layer 6)

Input Contract (IPLAN-004 Standard)

• Supported modes:

- --ref <path> - --prompt "<text>" - --iplan <path|IPLAN-NNN>

• Precedence: --iplan > --ref > --prompt
• IPLAN resolution order:

1. Use explicit file path when it exists 2. Resolve work_plans/IPLAN-NNN*.md 3. Resolve governance/plans/IPLAN-NNN*.md 4. If multiple matches exist, fail with disambiguation request

• Merge conflict rule:

- Objective/scope conflicts between primary and supplemental sources are blocking and require user clarification.

Input Contract (IPLAN-004 Standard)

• Supported modes:

- --ref <path> - --prompt "<text>" - --iplan <path|IPLAN-NNN>

• Precedence: --iplan > --ref > --prompt
• IPLAN resolution order:

1. Use explicit file path when it exists 2. Resolve work_plans/IPLAN-NNN*.md 3. Resolve governance/plans/IPLAN-NNN*.md 4. If multiple matches exist, fail with disambiguation request

• Merge conflict rule:

- Objective/scope conflicts between primary and supplemental sources are blocking and require user clarification.

Skill Dependencies

This autopilot orchestrates the following skills:

Delegation Principle: The autopilot orchestrates workflow but delegates:

• EARS structure/content rules -> doc-ears skill
• Real-time quality feedback -> quality-advisor skill
• EARS validation logic -> doc-ears-validator skill
• Content review and scoring -> doc-ears-reviewer skill
• Issue resolution and fixes -> doc-ears-fixer skill
• PRD validation logic -> doc-prd-validator skill
• Element ID standards -> doc-naming skill

Document Type Contract (MANDATORY)

When generating EARS document instances, the autopilot MUST:

1. Read instance_document_type from template:

- Source: ai_dev_ssd_flow/03_EARS/EARS-MVP-TEMPLATE.yaml - Field: metadata.instance_document_type: "ears-document"

1. Set document_type in generated document frontmatter: custom_fields: document_type: ears-document # NOT "template" artifact_type: EARS layer: 3
2. Validation: Generated documents MUST have document_type: ears-document

- Templates have document_type: template - Instances have document_type: ears-document - Schema validates both values

Error Handling: If instance_document_type is missing from template, default to ears-document.

Smart Document Detection

The autopilot automatically determines the action based on the input document type.

Input Type Recognition

Detection Algorithm

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

File Existence Check

# Check for nested folder structure (mandatory)
ls docs/03_EARS/EARS-{NN}_*/

Examples

# Review mode (same type - EARS input)
/doc-ears-autopilot EARS-01          # Reviews existing EARS-01

# Generate/Find mode (upstream type - PRD input)
/doc-ears-autopilot PRD-01           # Generates EARS-01 if missing, or reviews existing EARS-01

# Multiple inputs
/doc-ears-autopilot PRD-01,PRD-02    # Generates/reviews EARS-01 and EARS-02
/doc-ears-autopilot EARS-01,EARS-02  # Reviews EARS-01 and EARS-02

Action Determination Output

Input: PRD-01
├── Detected Type: PRD (upstream)
├── Expected EARS: EARS-01
├── EARS Exists: Yes → docs/03_EARS/EARS-01_f1_iam/
└── Action: REVIEW MODE - Running doc-ears-reviewer on EARS-01

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

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

When to Use This Skill

Use doc-ears-autopilot when:

• You have one or more completed PRD documents ready for EARS generation
• You want automated requirement categorization (Event, State, Unwanted, Ubiquitous)
• You need EARS-Ready score validation before generation
• You want automatic BDD-Ready score validation after EARS creation
• You need to generate formal WHEN-THE-SHALL-WITHIN statements from PRD features

Do NOT use when:

• Creating a single EARS with extensive manual customization (use doc-ears directly)
• PRDs are incomplete or in Draft status
• You need fine-grained control over each EARS statement
• PRD EARS-Ready score is below 90%

Workflow Overview

flowchart TD
    subgraph Phase1["Phase 1: PRD Analysis"]
        A[Input: PRD List] --> B[Read PRD Documents]
        B --> C[Extract Features and Requirements]
        C --> D[Identify Functional Requirements]
        D --> E[Catalog Quality Attributes]
        E --> F[Extract Threshold References]
    end

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

    subgraph Phase3["Phase 3: EARS Generation"]
        L --> M[Categorize Requirements]
        M --> N[Generate Event-Driven Statements]
        N --> O[Generate State-Driven Statements]
        O --> P[Generate Unwanted Behavior Statements]
        P --> Q[Generate Ubiquitous Statements]
        Q --> R[quality-advisor: Real-time Feedback]
        R --> S[Add Quality Attributes Section]
        S --> T[Add Traceability Tags]
        T --> U[Write EARS Files]
    end

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

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

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

Detailed Workflow

Phase 1: PRD Analysis

Analyze PRD documents to extract requirements for EARS formalization.

Input Sources (from PRD):

Analysis Process:

# Check for PRD documents
ls -la docs/02_PRD/

# Expected structure:
# - PRD-NN_{slug}.md (monolithic)
# - PRD-NN_{slug}/ (sectioned with PRD-NN.S_{section}.md files)

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

Phase 2: EARS Readiness Check

Validate that source PRDs meet EARS-Ready requirements before generation.

Skill Delegation: This phase uses validation rules from doc-prd-validator skill. See: .claude/skills/doc-prd-validator/SKILL.md for complete PRD validation rules.

EARS-Ready Scoring Criteria (100%):

Minimum Score: 90% (configurable)

Auto-Fix Actions:

Validation Command (internal):

/doc-prd-validator PRD-NN

Phase 3: EARS Generation

Generate EARS statements from validated PRD with real-time quality feedback.

Skill Delegation: This phase follows rules defined in doc-ears skill. See: .claude/skills/doc-ears/SKILL.md for complete EARS creation guidance. Quality Guidance: Uses quality-advisor skill for real-time feedback during generation. See: .claude/skills/quality-advisor/SKILL.md for quality monitoring.

Generation Process:

1. Reserve EARS ID: # Check for next available ID ls docs/03_EARS/EARS-*.md docs/03_EARS/EARS-*/EARS-*.0_*.md 2>/dev/null | \ grep -oP 'EARS-\K\d+' | sort -n | tail -1 # Increment for new EARS
2. Load EARS Template:

- Primary: ai_dev_ssd_flow/03_EARS/EARS-MVP-TEMPLATE.md - Section templates: For sectioned EARS (>800 lines)

1. Generate Document Control Section: Field Value EARS ID EARS-NN Version 0.1.0 Date Created Current date (YYYY-MM-DD) Last Updated Current date (YYYY-MM-DD) Status Draft Priority From PRD priority Source Document @prd: PRD.NN.EE.SS (single value) BDD-Ready Score Calculated after generation
2. Categorize Requirements: Requirement Category Detection: PRD Pattern EARS Category ID Range "when user...", "upon receiving...", "triggered by..." Event-Driven 001-099 "while connected...", "during session...", "maintaining..." State-Driven 101-199 "if error...", "prevent...", "handle failure..." Unwanted Behavior 201-299 "always...", "system-wide...", "all requests..." Ubiquitous 401-499
3. Generate EARS Statements by Category: Event-Driven Requirements (ID Range: 001-099): #### EARS.NN.25.001: [Requirement Name] WHEN [trigger condition], THE [system component] SHALL [action 1], [action 2], and [action 3] WITHIN [timing constraint] (@threshold: PRD.NN.category.key). **Traceability**: @brd: BRD.NN.01.SS | @prd: PRD.NN.07.SS State-Driven Requirements (ID Range: 101-199): #### EARS.NN.25.101: [Requirement Name] WHILE [state condition], THE [system component] SHALL [continuous behavior] WITHIN [operational context]. **Traceability**: @brd: BRD.NN.01.SS | @prd: PRD.NN.07.SS Unwanted Behavior Requirements (ID Range: 201-299): #### EARS.NN.25.201: [Requirement Name] IF [error condition], THE [system component] SHALL [prevention/recovery action] WITHIN [timing constraint]. **Traceability**: @brd: BRD.NN.01.SS | @prd: PRD.NN.07.SS Ubiquitous Requirements (ID Range: 401-499): #### EARS.NN.25.401: [Requirement Name] THE [system component] SHALL [universal behavior] for [scope/context]. **Traceability**: @brd: BRD.NN.01.SS | @prd: PRD.NN.07.SS
4. Real-Time Quality Feedback (via quality-advisor skill):

- Monitor EARS syntax compliance as statements are generated - Detect anti-patterns (missing SHALL, ambiguous terms, non-atomic statements) - Validate @threshold tag format and references - Check element ID format compliance (EARS.NN.25.SS) - Flag issues early to reduce post-generation rework

1. Generate Quality Attributes Section: Performance Requirements Table: QA ID Requirement Statement Metric Target Priority Measurement Method EARS.NN.02.01 THE [component] SHALL complete [operation] Latency p95 < NNms High [method] EARS.NN.02.02 THE [component] SHALL process [workload] Throughput NN/s Medium [method] Security Requirements Table: QA ID Requirement Statement Control Compliance Priority EARS.NN.03.01 THE [component] SHALL authenticate using [method] Authentication [standard] High Reliability Requirements Table: QA ID Requirement Statement Metric Target Priority EARS.NN.04.01 THE [component] SHALL maintain availability Uptime 99.9% High
2. Add Cumulative Traceability Tags: ## Traceability **Required Tags** (Cumulative Tagging Hierarchy - Layer 3): @brd: BRD.01.0103, BRD.01.0110 @prd: PRD.01.0702, PRD.01.0715
3. Add Threshold References Section: ### Thresholds Referenced | Threshold ID | Category | Value | Source | |--------------|----------|-------|--------| | @threshold: PRD.01.timeout.auth.sso | Timing | 500ms | PRD Section 20.1 | | @threshold: PRD.01.perf.api.p95 | Performance | 100ms | PRD Section 14 |
4. File Output (ALWAYS use nested folder): Nested Folder Rule: ALL EARS use nested folders (EARS-NN_{slug}/) regardless of size. This keeps companion files (review reports, fix reports, drift cache) organized with their parent document.

- Monolithic (<20k tokens): docs/03_EARS/EARS-NN_{slug}/EARS-NN_{slug}.md - Sectioned (≥20k tokens): docs/03_EARS/EARS-NN_{slug}/EARS-NN.0_index.md, EARS-NN.1_core.md, etc. - Master Index (always): docs/03_EARS/EARS-00_index.md (create or update)

Phase 4: EARS Validation

After EARS generation, validate structure and BDD-Ready score.

Skill Delegation: This phase uses validation rules from doc-ears-validator skill. See: .claude/skills/doc-ears-validator/SKILL.md for complete validation rules.

Validation Command:

python ai_dev_ssd_flow/03_EARS/scripts/validate_ears.py docs/03_EARS/EARS-NN_{slug}/EARS-NN_{slug}.md --verbose

Validation Checks:

Auto-Fix Actions:

Validation Loop:

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

Phase 5: Review & Fix Cycle (v2.2)

Iterative review and fix cycle to ensure EARS quality before completion.

flowchart TD
    A[Phase 5 Start] --> B[Run doc-ears-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-ears-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

5.1 Initial Review

Run doc-ears-audit to execute validator + reviewer and generate a combined report.

/doc-ears-audit EARS-NN

Output: EARS-NN.A_audit_report_v001.md (legacy-compatible reviewer report may still exist)

Review Checks:

1. EARS Syntax Compliance:

- All statements use WHEN-THE-SHALL-WITHIN format - SHALL/SHOULD/MAY keywords used correctly - No ambiguous terms ("fast", "efficient", "user-friendly") - All constraints quantifiable

1. Threshold Consistency:

- All @threshold tags reference valid PRD thresholds - Threshold values match PRD source - No orphan threshold references

1. Cumulative Tag Validation:

- @brd tags reference valid BRD elements - @prd tags reference valid PRD elements - Tag format uses pipe separators for inline

1. Statement Atomicity:

- Each EARS statement defines one testable concept - No compound requirements in single statements - Clear trigger-action-constraint structure

5.2 Fix Cycle

If review score < 90%, invoke doc-ears-fixer.

/doc-ears-fixer EARS-NN --revalidate

Fix Categories:

Output: EARS-NN.F_fix_report_v001.md

5.3 Re-Review

After fixes, automatically re-run reviewer.

/doc-ears-audit EARS-NN

Output: EARS-NN.A_audit_report_v002.md

5.4 Iteration Control

Iteration Example:

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

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

5.5 Quality Checks (Post-Fix)

After passing the fix cycle:

1. BDD-Ready Report: BDD-Ready Score Breakdown ========================= Requirements Clarity: 40/40 EARS Syntax Compliance: 20/20 Statement Atomicity: 15/15 Quantifiable Constraints: 5/5 Testability: 35/35 BDD Translation Ready: 15/15 Observable Verification: 10/10 Edge Cases Specified: 10/10 Quality Attributes: 15/15 Performance Targets: 5/5 Security Requirements: 5/5 Reliability Targets: 5/5 Strategic Alignment: 10/10 Business Objective Links: 5/5 Implementation Paths: 5/5 ---------------------------- Total BDD-Ready Score: 100/100 (Target: >= 90) Status: READY FOR BDD GENERATION
2. Traceability Matrix Update: # Update EARS-00_TRACEABILITY_MATRIX.md python ai_dev_ssd_flow/scripts/update_traceability_matrix.py \ --ears docs/03_EARS/EARS-NN_{slug}.md \ --matrix docs/03_EARS/EARS-00_TRACEABILITY_MATRIX.md

EARS Statement Types Reference

1. Event-Driven Requirements

Pattern: WHEN [trigger] THE [system] SHALL [action] WITHIN [constraint]

Keywords: "when", "upon", "triggered by", "on receipt of", "after"

Example:

WHEN user submits authentication request,
THE identity service SHALL validate credentials,
generate session token,
and return authentication response
WITHIN 100ms (@threshold: PRD.01.auth.response.p95).

Use Cases:

• User-initiated actions
• External system events
• Timer-triggered operations
• Message receipt handling

2. State-Driven Requirements

Pattern: WHILE [state] THE [system] SHALL [behavior] WITHIN [context]

Keywords: "while", "during", "as long as", "when in state"

Example:

WHILE user session is active,
THE session manager SHALL maintain heartbeat connection
and refresh token before expiration.

Use Cases:

• Continuous monitoring
• Persistent connections
• Background processes
• State maintenance

3. Unwanted Behavior Requirements

Pattern: IF [condition] THEN THE [system] SHALL [prevention/recovery]

Keywords: "if error", "when failure", "prevent", "handle", "recover from"

Example:

IF authentication timeout occurs,
THEN THE identity service SHALL retry authentication once
and log failure event
WITHIN 50ms (@threshold: PRD.01.auth.retry.timeout).

Use Cases:

• Error handling
• Failure recovery
• Prevention mechanisms
• Fallback behaviors

4. Ubiquitous Requirements

Pattern: THE [system] SHALL [behavior] for [scope]

Keywords: "always", "all", "every", "system-wide", "unconditionally"

Example:

THE logging service SHALL record all authentication events
with timestamp, user ID, and outcome status.

Use Cases:

• System-wide policies
• Compliance requirements
• Universal behaviors
• Cross-cutting concerns

Execution Modes

Single PRD Mode

Generate EARS from one PRD document.

# Example: Generate EARS from PRD-01
/doc-ears-autopilot PRD-01

Batch Mode

Generate EARS from multiple PRDs in sequence.

# Example: Generate EARS from all PRDs
/doc-ears-autopilot all --auto

Batch Configuration (config/ears_batch.yaml):

ears_generation:
  - id: "01"
    slug: "f1_iam_requirements"
    prd: "PRD-01"
    priority: 1

  - id: "02"
    slug: "f2_data_requirements"
    prd: "PRD-02"
    priority: 2

  - id: "03"
    slug: "f3_api_requirements"
    prd: "PRD-03"
    priority: 2

execution:
  parallel: false
  fail_fast: true

Dry Run Mode

Preview execution plan without generating files.

/doc-ears-autopilot PRD-01 --dry-run

Mode 4: Review Mode (v2.1)

Validate existing EARS documents without modification. Generates quality report with actionable recommendations.

Command:

# Review single EARS
/doc-ears-autopilot EARS-01 --review

# Review all EARS in directory
/doc-ears-autopilot docs/03_EARS/ --review --all

# Review with detailed report
/doc-ears-autopilot EARS-01 --review --verbose

Review Process:

flowchart TD
    A[Input: EARS Document] --> B[Load EARS Content]
    B --> C[Validate EARS Syntax]
    C --> D[Check BDD-Ready Score]
    D --> E[Verify Cumulative Tags]
    E --> F[Validate Element IDs]
    F --> G[Check Threshold References]
    G --> H[Validate Statement Atomicity]
    H --> I[Generate Review Report]
    I --> J{Issues Found?}
    J -->|Yes| K[Categorize Issues]
    K --> L[Generate Fix Recommendations]
    L --> M[Output Review Report]
    J -->|No| M

Review Report Template:

# EARS Review Report: EARS-NN_{slug}

## Summary
- **BDD-Ready Score**: NN% (✅/🟡/❌)
- **Total Issues**: N (E errors, W warnings)
- **Auto-Fixable**: N issues
- **Manual Review**: N issues

## Score Breakdown
| Category | Score | Max | Status |
|----------|-------|-----|--------|
| EARS Syntax Compliance | NN | 25 | ✅/🟡/❌ |
| Statement Atomicity | NN | 20 | ✅/🟡/❌ |
| Quantifiable Constraints | NN | 15 | ✅/🟡/❌ |
| BDD Translation Ready | NN | 15 | ✅/🟡/❌ |
| Traceability Tags | NN | 15 | ✅/🟡/❌ |
| Threshold References | NN | 10 | ✅/🟡/❌ |

## Issues by Category

### Auto-Fixable Issues
| Issue | Location | Fix Action |
|-------|----------|------------|
| Legacy ID pattern | EARS.01.25001 | Convert ER-001 → EARS.01.25001 |
| Missing @threshold | Line 45 | Add @threshold: PRD.01.xx.yy |

### Manual Review Required
| Issue | Location | Recommendation |
|-------|----------|----------------|
| Ambiguous term | Line 23 | Replace "fast" with quantified value |
| Compound requirement | Line 67 | Split into atomic statements |

Score Indicators:

• ✅ Green (>=90%): BDD-Ready
• 🟡 Yellow (70-89%): Needs improvement
• ❌ Red (<70%): Significant issues

Review Configuration:

review_mode:
  enabled: true
  checks:
    - ears_syntax          # WHEN-THE-SHALL-WITHIN patterns
    - statement_atomicity  # One testable concept per statement
    - threshold_refs       # @threshold tag validation
    - cumulative_tags      # @brd, @prd presence
    - element_ids          # EARS.NN.25.SS format
    - quantifiable         # No ambiguous terms
  output:
    format: markdown       # markdown, json, html
    include_recommendations: true
    include_fix_commands: true

Mode 5: Fix Mode (v2.1)

Auto-repair existing EARS documents with backup and content preservation.

Command:

# Fix single EARS
/doc-ears-autopilot EARS-01 --fix

# Fix with backup
/doc-ears-autopilot EARS-01 --fix --backup

# Fix all EARS
/doc-ears-autopilot docs/03_EARS/ --fix --all

# Fix specific categories only
/doc-ears-autopilot EARS-01 --fix --only element_ids,thresholds

# Dry-run fix (preview changes)
/doc-ears-autopilot EARS-01 --fix --dry-run

Fix Process:

flowchart TD
    A[Input: EARS Document] --> B[Create Backup]
    B --> C[Load EARS Content]
    C --> D[Run Review Analysis]
    D --> E{Auto-Fixable Issues?}
    E -->|No| F[Report: No Fixes Needed]
    E -->|Yes| G[Apply Fixes by Category]

    subgraph FixCategories["Fix Categories"]
        G --> H[Fix Element IDs]
        H --> I[Fix EARS Syntax]
        I --> J[Fix Threshold References]
        J --> K[Add Missing Tags]
        K --> L[Fix Section Structure]
    end

    L --> M[Validate Fixed Document]
    M --> N{Validation Passed?}
    N -->|No| O[Rollback to Backup]
    O --> P[Report: Fix Failed]
    N -->|Yes| Q[Save Fixed Document]
    Q --> R[Generate Fix Report]

EARS-Specific Fix Categories:

Element ID Migration (Layer 3):

Content Preservation Rules:

Fix Configuration:

fix_mode:
  enabled: true
  backup:
    enabled: true
    location: "tmp/backups/"
    timestamp: true
  fix_categories:
    element_ids: true      # Convert legacy ID patterns
    ears_syntax: true      # Fix WHEN-THE-SHALL structure
    thresholds: true       # Add @threshold references
    cumulative_tags: true  # Add @brd, @prd tags
    sections: true         # Add missing sections
    atomicity: false       # Manual only (flag but don't auto-fix)
    ambiguous_terms: false # Manual only (flag but don't auto-fix)
  validation:
    post_fix: true         # Validate after fixes
    rollback_on_fail: true # Restore backup if validation fails
  preserve:
    custom_statements: true
    domain_content: true
    threshold_values: true

Fix Report Template:

# EARS Fix Report: EARS-NN_{slug}

## Summary
- **Backup Created**: tmp/backups/EARS-NN_{slug}_20260209_143022.md
- **Issues Fixed**: N of M auto-fixable issues
- **Manual Review**: N issues flagged

## Fixes Applied

### Element ID Migration
| Original | Fixed | Location |
|----------|-------|----------|
| ER-001 | EARS.01.25001 | Line 45 |
| SR-101 | EARS.01.25101 | Line 78 |

### Threshold References Added
| Statement | Threshold Added |
|-----------|-----------------|
| EARS.01.25001 | @threshold: PRD.01.auth.p95 |

### Cumulative Tags Added
- @brd: BRD.01.0103 (added)
- @prd: PRD.01.0702 (verified)

## Manual Review Required

### Compound Statements (Split Required)
| Statement ID | Issue | Recommendation |
|--------------|-------|----------------|
| EARS.01.25015 | Multiple actions | Split into EARS.01.25015, .016 |

### Ambiguous Terms
| Location | Term | Suggested Replacement |
|----------|------|----------------------|
| Line 89 | "quickly" | "WITHIN 100ms" |
| Line 156 | "efficiently" | Remove or quantify |

## Validation Results
- **BDD-Ready Score**: Before: 78% → After: 94%
- **Syntax Errors**: Before: 5 → After: 0
- **Status**: ✅ All auto-fixes validated

Command Line Options (Review/Fix Modes):

Configuration

Default Configuration

# config/ears_autopilot.yaml
ears_autopilot:
  version: "1.0"

  scoring:
    ears_ready_min: 90
    bdd_ready_min: 90
    strict_mode: false

  execution:
    max_parallel: 3        # HARD LIMIT - do not exceed
    chunk_size: 3          # Documents per chunk
    pause_between_chunks: true
    auto_fix: true
    continue_on_error: false
    timeout_per_prd: 300  # seconds

  output:
    structure: auto  # auto, monolithic, sectioned
    size_threshold_lines: 800
    report_format: markdown

  validation:
    skip_validation: false
    fix_iterations_max: 3

  review:
    enabled: true
    check_syntax: true
    check_thresholds: true
    check_atomicity: true
    check_tags: true
    auto_fix_syntax: true

Command Line Options

Context Management

Chunked Parallel Execution (MANDATORY)

CRITICAL: To prevent conversation context overflow errors ("Prompt is too long", "Conversation too long"), all autopilot operations MUST follow chunked execution rules:

Chunk Size Limit: Maximum 3 documents per chunk

Chunking Rules:

1. Chunk Formation: Group PRD documents into chunks of maximum 3 at a time
2. Sequential Chunk Processing: Process one chunk at a time, completing all EARS in a chunk before starting the next
3. Context Pause: After completing each chunk, provide a summary and pause for user acknowledgment
4. Progress Tracking: Display chunk progress (e.g., "Chunk 2/5: Processing PRD-04, PRD-05, PRD-06")

Execution Pattern:

PRDs: PRD-01, PRD-02, PRD-03, PRD-04, PRD-05, PRD-06, PRD-07

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

Chunk Completion Summary Template:

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

Why Chunking is Required:

• Prevents "Conversation too long" errors during batch processing
• Allows context compaction between chunks
• Enables recovery from failures without losing all progress
• Provides natural checkpoints for user review

Output Artifacts

Generated Files

All EARS use nested folders (EARS-NN_{slug}/) regardless of size. Document sectioning (monolithic vs sectioned) depends only on document size (>20k tokens = sectioned).

Validation Reports

Error Handling

Error Categories

Recovery Actions

def handle_error(error_type: str, context: dict) -> Action:
    match error_type:
        case "PRD_MISSING":
            return Action.ABORT_WITH_MESSAGE
        case "EARS_READY_LOW":
            return Action.AUTO_FIX_PRD
        case "VALIDATION_FAILURE":
            if context["retry_count"] < 3:
                return Action.AUTO_FIX_RETRY
            return Action.FLAG_MANUAL_REVIEW
        case "BDD_READY_LOW":
            return Action.ENHANCE_STATEMENTS
        case _:
            return Action.FLAG_MANUAL_REVIEW

Integration Points

Pre-Execution Hooks

# Hook: pre_ears_generation
# Runs before EARS generation starts
./hooks/pre_ears_generation.sh

# Example: Validate PRD exists and is ready
if [ ! -d "docs/02_PRD/PRD-01_*" ]; then
  echo "ERROR: PRD-01 required"
  exit 1
fi

Post-Execution Hooks

# Hook: post_ears_generation
# Runs after EARS generation completes
./hooks/post_ears_generation.sh

# Example: Trigger BDD autopilot for validated EARS
if [ "$EARS_VALIDATED" = "true" ]; then
  /doc-bdd-autopilot "$EARS_ID"
fi

CI/CD Integration

# .github/workflows/ears_autopilot.yml
name: EARS Autopilot

on:
  push:
    paths:
      - 'docs/02_PRD/**'

jobs:
  generate-ears:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run EARS Autopilot
        run: |
          /doc-ears-autopilot all --auto

      - name: Upload Validation Report
        uses: actions/upload-artifact@v4
        with:
          name: ears-validation
          path: tmp/ears_validation_report.json

Quality Gates

Phase Gates

Blocking vs Non-Blocking

Validation Checklist

After autopilot completion:

• All target EARS documents generated
• Each EARS has BDD-Ready score >= 90%
• Traceability matrix updated (EARS-00_TRACEABILITY_MATRIX.md)
• Each EARS references upstream PRD with @prd tags
• Each EARS references upstream BRD with @brd tags
• All statements use WHEN-THE-SHALL-WITHIN syntax
• All constraints have @threshold references
• No ambiguous terms in statements
• Each statement is atomic (one testable concept)
• Quality Attributes section uses tabular format
• Element IDs use EARS.NN.25.SS format
• Source Document has single @prd value

Quick Reference

Usage:

/doc-ears-autopilot <PRD-LIST> [OPTIONS]

Common Commands:

# Single PRD
/doc-ears-autopilot PRD-01

# All PRDs (automatic)
/doc-ears-autopilot all --auto

# Preview only
/doc-ears-autopilot all --dry-run

# Resume after failure
/doc-ears-autopilot resume

Related Resources

Skills (Delegated)

• EARS Skill: .claude/skills/doc-ears/SKILL.md - EARS creation rules and WHEN-THE-SHALL syntax
• EARS Validator Skill: .claude/skills/doc-ears-validator/SKILL.md - Validation rules and error codes
• PRD Validator Skill: .claude/skills/doc-prd-validator/SKILL.md - PRD readiness validation
• Quality Advisor Skill: .claude/skills/quality-advisor/SKILL.md - Real-time quality feedback
• Naming Standards Skill: .claude/skills/doc-naming/SKILL.md - Element ID format

Templates and Rules

• EARS Template: ai_dev_ssd_flow/03_EARS/EARS-MVP-TEMPLATE.md
• EARS Schema: ai_dev_ssd_flow/03_EARS/EARS_MVP_SCHEMA.yaml
• EARS Creation Rules: ai_dev_ssd_flow/03_EARS/EARS-MVP-TEMPLATE.md
• EARS Validation Rules: ai_dev_ssd_flow/03_EARS/EARS_MVP_SCHEMA.yaml

Section Templates (for documents >800 lines)

• Index template: ai_dev_ssd_flow/03_EARS/EARS-SECTION-0-TEMPLATE.md
• Content template: ai_dev_ssd_flow/03_EARS/EARS-SECTION-TEMPLATE.md

Framework References

• SDD Workflow: ai_dev_ssd_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
• MVP Autopilot: ai_dev_ssd_flow/AUTOPILOT/MVP_AUTOPILOT.md
• PRD Autopilot Skill: .claude/skills/doc-prd-autopilot/SKILL.md
• BRD Autopilot Skill: .claude/skills/doc-brd-autopilot/SKILL.md

Review Document Standards (v2.2)

IMPORTANT: Audit/review reports generated by this autopilot are formal project documents.

See: .claude/skills/REVIEW_DOCUMENT_STANDARDS.md for complete standards.

Quick Reference

Example Location:

docs/03_EARS/
├── EARS-03_f3_observability.md
├── EARS-03.A_audit_report_v001.md    # ← Preferred report stored here
└── EARS-03.R_review_report_v001.md    # ← Legacy-compatible reviewer report

Version History