doc-ears-fixer

name	doc-ears-fixer
description	Automated fix skill that reads review reports and applies fixes to EARS documents - handles broken links, element IDs, missing files, and iterative improvement
metadata	{"tags":["sdd-workflow","quality-assurance","ears-fix","layer-3-artifact","shared-architecture"],"custom_fields":{"layer":3,"artifact_type":"EARS","architecture_approaches":["ai-agent-based"],"priority":"primary","development_status":"active","skill_category":"quality-assurance","upstream_artifacts":["EARS","Audit Report","Review Report","PRD"],"downstream_artifacts":["Fixed EARS","Fix Report"],"version":"2.2","last_updated":"2026-02-26"}}

doc-ears-fixer

Purpose

Automated fix skill that reads the latest audit/review report and applies fixes to EARS (Easy Approach to Requirements Syntax) documents. This skill bridges the gap between doc-ears-reviewer/doc-ears-audit (which identify issues) and the corrected EARS, enabling iterative improvement cycles.

Layer: 3 (EARS Quality Improvement)

Upstream: EARS document, Audit/Review Report (EARS-NN.A_audit_report_vNNN.md preferred, EARS-NN.R_review_report_vNNN.md legacy), PRD (source requirements)

Downstream: Fixed EARS, Fix Report (EARS-NN.F_fix_report_vNNN.md)

---

When to Use This Skill

Use doc-ears-fixer when:

• After Review: Run after doc-ears-reviewer identifies issues
• Iterative Improvement: Part of Review -> Fix -> Review cycle
• Automated Pipeline: CI/CD integration for quality gates
• Batch Fixes: Apply fixes to multiple EARS based on review reports

Do NOT use when:

• No audit/review report exists (run doc-ears-audit or doc-ears-reviewer first)
• Creating new EARS (use doc-ears or doc-ears-autopilot)
• Only need validation (use doc-ears-validator)

---

Skill Dependencies

Skill	Purpose	When Used
doc-ears-audit	Preferred source of normalized findings	Input (reads audit report)
doc-ears-reviewer	Legacy/alternate source of issues to fix	Input (reads review report)
doc-naming	Element ID standards	Fix element IDs
doc-ears	EARS creation rules	Create missing sections
doc-prd-reviewer	Upstream PRD validation	Check upstream alignment

---

Workflow Overview

flowchart TD
  A[Input: EARS Path] --> B[Find Latest Audit/Review Report]
  B --> C{Report Found?}
  C -->|No| D[Run doc-ears-audit or doc-ears-reviewer First]
  C -->|Yes| E[Parse Report]

    E --> F[Categorize Issues]

    subgraph FixPhases["Fix Phases"]
        F --> F0[Phase 0: Fix Structure Violations]
        F0 --> G[Phase 1: Create Missing Files]
        G --> H[Phase 2: Fix Broken Links]
        H --> I[Phase 3: Fix Element IDs]
        I --> J[Phase 4: Fix Content Issues]
        J --> K[Phase 5: Update References]
        K --> K2[Phase 6: Handle Upstream Drift]
    end

    K2 --> L[Write Fixed EARS]
    L --> M[Generate Fix Report]
    M --> N{Re-run Review?}
    N -->|Yes| O[Invoke doc-ears-reviewer]
    O --> P{Score >= Threshold?}
    P -->|No, iterations < max| F
    P -->|Yes| Q[COMPLETE]
    N -->|No| Q

---

Fix Phases

Phase 0: Fix Structure Violations (CRITICAL)

Fixes EARS documents that are not in nested folders. This phase runs FIRST because all subsequent phases depend on correct folder structure.

Nested Folder Rule: ALL EARS MUST be in nested folders regardless of document size.

Required Structure:

EARS Type	Required Location
Monolithic	docs/03_EARS/EARS-NN_{slug}/EARS-NN_{slug}.md

Fix Actions:

Issue Code	Issue	Fix Action
REV-STR001	EARS not in nested folder	Create folder, move file, update all links
REV-STR002	EARS folder name doesn't match EARS ID	Rename folder to match
REV-STR003	Monolithic EARS >25KB should be sectioned	Flag for manual review

Structure Fix Workflow:

def fix_ears_structure(ears_path: str) -> list[Fix]:
    """Fix EARS structure violations."""
    fixes = []

    filename = os.path.basename(ears_path)
    parent_folder = os.path.dirname(ears_path)

    # Extract EARS ID and slug from filename
    match = re.match(r'EARS-(\d+)_([^/]+)\.md', filename)
    if not match:
        return []  # Cannot auto-fix invalid filename

    ears_id = match.group(1)
    slug = match.group(2)
    expected_folder = f"EARS-{ears_id}_{slug}"

    # Check if already in nested folder
    if os.path.basename(parent_folder) != expected_folder:
        # Create nested folder
        new_folder = os.path.join(os.path.dirname(parent_folder), expected_folder)
        os.makedirs(new_folder, exist_ok=True)

        # Move file
        new_path = os.path.join(new_folder, filename)
        shutil.move(ears_path, new_path)
        fixes.append(f"Moved {ears_path} to {new_path}")

        # Update upstream links in moved file
        content = Path(new_path).read_text()
        updated_content = content.replace('../02_PRD/', '../../02_PRD/')
        updated_content = updated_content.replace('../01_BRD/', '../../01_BRD/')
        Path(new_path).write_text(updated_content)
        fixes.append(f"Updated relative links for nested folder structure")

    return fixes

Link Path Updates After Move:

Original Path	Updated Path
../02_PRD/PRD-01_slug/PRD-01.md	../../02_PRD/PRD-01_slug/PRD-01.md
../01_BRD/BRD-01_slug/BRD-01.md	../../01_BRD/BRD-01_slug/BRD-01.md

---

Phase 1: Create Missing Files

Creates files that are referenced but don't exist.

Scope:

Missing File	Action	Template Used
EARS-00_GLOSSARY.md	Create EARS glossary	Glossary template
EARS-NN_APPENDIX_*.md	Create appendix placeholder	Appendix template
Pattern library files	Create placeholder with TODO sections	Pattern template
Constraint files	Create placeholder	Constraint template

EARS Glossary Template:

---
title: "EARS-00: Requirements Glossary"
tags:
  - ears
  - glossary
  - reference
custom_fields:
  document_type: glossary
  artifact_type: EARS-REFERENCE
  layer: 3
---

# EARS-00: Requirements Glossary

Common terminology used across all EARS Requirements Documents.

## EARS Pattern Terms

| Term | Definition | Context |
|------|------------|---------|
| Ubiquitous | Always active requirement | Pattern type |
| Event-Driven | Triggered by specific event | Pattern type |
| Unwanted Behavior | Exception handling requirement | Pattern type |
| State-Driven | Active in specific state | Pattern type |
| Optional Feature | Conditionally included requirement | Pattern type |
| Complex | Multi-condition requirement | Pattern type |

## Requirement Keywords

| Term | Definition | Context |
|------|------------|---------|
| SHALL | Mandatory requirement | Normative |
| SHOULD | Recommended requirement | Advisory |
| MAY | Optional requirement | Permissive |
| MUST | Absolute requirement | Critical |

## Domain Terms

<!-- Add project-specific terminology below -->

| Term | Definition | Context |
|------|------------|---------|
| [Term] | [Definition] | [Where used] |

Pattern Placeholder Template:

---
title: "EARS Pattern: [Pattern Name]"
tags:
  - ears
  - pattern-spec
  - reference
custom_fields:
  document_type: pattern-spec
  status: placeholder
  created_by: doc-ears-fixer
---

# EARS Pattern: [Pattern Name]

> **Status**: Placeholder - Requires completion

## 1. Pattern Overview

[TODO: Document pattern overview]

## 2. Pattern Template

```text
[TODO: Define EARS pattern template]

3. Pattern Examples

Example ID	Requirement	Pattern Type
EX-XX-01	[Example requirement]	[Type]

4. Constraints

[TODO: Document pattern constraints]

---

Created by doc-ears-fixer as placeholder. Complete this document to resolve broken link issues.

---

### Phase 2: Fix Broken Links

Updates links to point to correct locations.

**Fix Actions**:

| Issue Code | Issue | Fix Action |
|------------|-------|------------|
| REV-L001 | Broken internal link | Update path or create target file |
| REV-L002 | External link unreachable | Add warning comment, keep link |
| REV-L003 | Absolute path used | Convert to relative path |
| REV-L004 | Broken PRD reference | Update to correct PRD path |

**Path Resolution Logic**:

```python
def fix_link_path(ears_location: str, target_path: str) -> str:
    """Calculate correct relative path based on EARS location."""

    # Monolithic EARS: docs/03_EARS/EARS-01.md
    # Sectioned EARS: docs/03_EARS/EARS-01_slug/EARS-01.3_section.md

    if is_sectioned_ears(ears_location):
        # Need to go up one more level
        return "../" + calculate_relative_path(ears_location, target_path)
    else:
        return calculate_relative_path(ears_location, target_path)

PRD Link Fix:

EARS Type	Original Link	Fixed Link
Monolithic	../02_PRD/PRD-01.md	../02_PRD/PRD-01.md
Sectioned	../02_PRD/PRD-01.md	../../02_PRD/PRD-01.md

---

Phase 3: Fix Element IDs

Converts invalid element IDs to correct format.

Conversion Rules:

Pattern	Issue	Conversion
EARS.NN.01.SS	Code 01 invalid for EARS	EARS.NN.25.SS (EARS Statement)
EARS.NN.22.SS	Code 22 invalid for EARS	EARS.NN.26.SS (Constraint Statement)
REQ-XXX	Legacy pattern	EARS.NN.25.SS
CON-XXX	Legacy pattern	EARS.NN.26.SS
PAT-XXX	Legacy pattern	EARS.NN.25.SS

Type Code Mapping (EARS-specific valid codes: 25, 26):

Invalid Code	Valid Code	Element Type
01	25	EARS Statement
02	25	EARS Statement
03	26	Constraint Statement
05	25	EARS Statement
06	26	Constraint Statement
22	25	EARS Statement
33	26	Constraint Statement

Regex Patterns:

# Find element IDs with invalid type codes for EARS
invalid_ears_type_01 = r'EARS\.(\d{2})\.01\.(\d{2})'
replacement_01 = r'EARS.\1.25.\2'

invalid_ears_type_22 = r'EARS\.(\d{2})\.22\.(\d{2})'
replacement_22 = r'EARS.\1.26.\2'

# Find legacy patterns
legacy_req = r'###\s+REQ-(\d+):'
legacy_con = r'###\s+CON-(\d+):'
legacy_pat = r'###\s+PAT-(\d+):'

---

Phase 4: Fix Content Issues

Addresses placeholders, incomplete content, and EARS-specific syntax issues.

Fix Actions:

Issue Code	Issue	Fix Action
REV-P001	[TODO] placeholder	Flag for manual completion (cannot auto-fix)
REV-P002	[TBD] placeholder	Flag for manual completion (cannot auto-fix)
REV-P003	Template date YYYY-MM-DD	Replace with current date
REV-P004	Template name [Name]	Replace with metadata author or flag
REV-P005	Empty section	Add minimum template content
REV-E001	Missing EARS keyword (shall/should/may)	Flag for manual review
REV-E002	Invalid EARS pattern structure	Flag for manual review
REV-E003	Missing trigger condition	Flag for manual review

Auto-Replacements:

replacements = {
    'YYYY-MM-DDTHH:MM:SS': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
    'YYYY-MM-DD': datetime.now().strftime('%Y-%m-%d'),
    'MM/DD/YYYY': datetime.now().strftime('%m/%d/%Y'),
    '[Current date]': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
    '[System Name]': extract_system_name_from_metadata(),
}

EARS Pattern Validation:

Pattern Type	Required Structure	Auto-Fix
Ubiquitous	"The [system] shall [action]"	No (flag)
Event-Driven	"When [trigger], the [system] shall [action]"	No (flag)
State-Driven	"While [state], the [system] shall [action]"	No (flag)
Unwanted	"If [condition], then the [system] shall [action]"	No (flag)
Optional	"Where [feature], the [system] shall [action]"	No (flag)

---

Phase 5: Update References

Ensures traceability and cross-references are correct.

Fix Actions:

Issue	Fix Action
Missing @ref: for created files	Add reference tag
Incorrect cross-EARS path	Update to correct relative path
Missing PRD traceability	Add PRD reference with @trace: PRD-NN
Missing traceability entry	Add to traceability matrix

Traceability Format:

<!-- Traceability to PRD -->
@trace: PRD-01.22.01 -> EARS-01.25.01

<!-- Reference to upstream -->
@ref: PRD-01 Section 3 (../02_PRD/PRD-01.md#3-feature-requirements)

---

Phase 6: Handle Upstream Drift (Auto-Merge)

Addresses issues where upstream PRD documents have changed since EARS creation. This phase implements a tiered auto-merge system based on drift percentage.

6.0.1 Hash Validation Fixes

FIX-H001: Invalid Hash Placeholder

Trigger: Hash contains placeholder instead of SHA-256

Fix:

sha256sum <upstream_file_path> | cut -d' ' -f1

Update cache with: sha256:<64_hex_output>

FIX-H002: Missing Hash Prefix

Trigger: 64 hex chars but missing sha256: prefix

Fix: Prepend sha256: to value

FIX-H003: Upstream File Not Found

Trigger: Cannot compute hash (file missing)

Fix: Set drift_detected: true, add to manual review

Code	Description	Auto-Fix	Severity
FIX-H001	Replace placeholder hash with actual SHA-256	Yes	Error
FIX-H002	Add missing sha256: prefix	Yes	Warning
FIX-H003	Upstream file not found	Partial	Error

---

Upstream: PRD (Layer 2) Downstream: BDD (Layer 4) ID Pattern: EARS.NN.xxxx (e.g., EARS.01.2513)

Drift Issue Codes (from doc-ears-reviewer Check #9)

Code	Severity	Description	Auto-Fix Tier
REV-D001	Warning	PRD modified after EARS	Tier 1-2
REV-D002	Warning	Referenced PRD section content changed	Tier 1-3
REV-D003	Info	PRD version incremented	Tier 1
REV-D004	Info	New features added to PRD	Tier 1-2
REV-D005	Error	Critical PRD modification (>20% change)	Tier 3

Tiered Auto-Merge System

Tier Classification:

Tier	Change %	Auto-Merge	Version Action	Description
Tier 1	< 5%	Full auto-merge	Patch (+0.0.1)	Additions, threshold updates
Tier 2	5-15%	Auto-merge with changelog	Minor (+0.1.0)	Significant additions, minor modifications
Tier 3	> 15%	Archive + regenerate	Major (+1.0.0)	Structural changes, major content drift

Change Percentage Calculation

def calculate_drift_percentage(
    upstream_current: str,
    upstream_cached: str,
    referenced_sections: list[str]
) -> float:
    """
    Calculate drift percentage between cached and current upstream.

    Args:
        upstream_current: Current PRD content
        upstream_cached: Cached PRD content from last sync
        referenced_sections: List of PRD sections referenced by EARS

    Returns:
        Drift percentage (0.0 - 100.0)
    """
    # Extract referenced sections only
    current_sections = extract_sections(upstream_current, referenced_sections)
    cached_sections = extract_sections(upstream_cached, referenced_sections)

    # Calculate line-based diff
    diff = unified_diff(cached_sections.splitlines(), current_sections.splitlines())

    added_lines = sum(1 for line in diff if line.startswith('+') and not line.startswith('+++'))
    removed_lines = sum(1 for line in diff if line.startswith('-') and not line.startswith('---'))
    total_lines = max(len(cached_sections.splitlines()), 1)

    # Weighted calculation: additions weighted 1.0, removals weighted 1.5
    drift_score = (added_lines * 1.0 + removed_lines * 1.5) / total_lines * 100

    return min(drift_score, 100.0)

def determine_tier(drift_percentage: float) -> int:
    """Determine merge tier based on drift percentage."""
    if drift_percentage < 5.0:
        return 1
    elif drift_percentage <= 15.0:
        return 2
    else:
        return 3

Tier 1: Auto-Merge (< 5% Drift)

Trigger Conditions:

• Minor additions to PRD sections
• Threshold/limit updates
• Clarification text additions
• No structural changes

Auto-Merge Actions:

Change Type	Action	ID Assignment
New requirement in PRD	Add EARS statement	Next sequential ID (e.g., EARS.01.2513)
Updated threshold	Update constraint value	Keep existing ID
Added clarification	Append to existing statement	Keep existing ID

ID Generation for New Requirements:

def generate_next_ears_id(ears_doc: str, type_code: str = "25") -> str:
    """
    Generate next sequential EARS ID.

    ID Pattern: EARS.NN.xxxx
    - NN: Document number (01-99)
    - TT: Type code (25=Statement, 26=Constraint)
    - SS: Sequence number (01-99)

    Args:
        ears_doc: Path to EARS document
        type_code: Type code ("25" for statement, "26" for constraint)

    Returns:
        Next available EARS ID
    """
    # Extract document number from filename
    doc_num = extract_doc_number(ears_doc)  # e.g., "01" from "EARS-01.md"

    # Find highest existing sequence for this type
    pattern = rf'EARS\.{doc_num}\.{type_code}\.(\d{{2}})'
    existing_ids = re.findall(pattern, read_file(ears_doc))

    if existing_ids:
        max_seq = max(int(seq) for seq in existing_ids)
        next_seq = str(max_seq + 1).zfill(2)
    else:
        next_seq = "01"

    return f"EARS.{doc_num}.{type_code}.{next_seq}"

Version Update:

# Tier 1: Increment patch version
# 1.0.0 -> 1.0.1
current_version = "1.0.0"
new_version = increment_version(current_version, "patch")  # "1.0.1"

Tier 2: Auto-Merge with Changelog (5-15% Drift)

Trigger Conditions:

• Multiple new features in PRD
• Section reorganization (minor)
• Requirement refinements
• New constraint categories

Auto-Merge Actions:

Change Type	Action	Documentation
New feature section	Generate EARS statements	Changelog entry
Modified requirements	Update existing statements	Changelog + diff
New constraints	Add constraint statements	Changelog entry

Changelog Entry Format:

## Changelog Entry (Auto-Merge Tier 2)

**Date**: 2026-02-10T16:00:00
**Source**: PRD-01.md (v1.2.0 -> v1.3.0)
**Drift Percentage**: 8.3%

### Additions

| New ID | Statement Summary | Source PRD Section |
|--------|-------------------|-------------------|
| EARS.01.2513 | System shall support batch processing | PRD-01 Section 5.2 |
| EARS.01.2514 | System shall provide progress notifications | PRD-01 Section 5.3 |
| EARS.01.2605 | Response time constraint for batch ops | PRD-01 Section 7.1 |

### Modifications

| ID | Previous | Updated | Reason |
|----|----------|---------|--------|
| EARS.01.2507 | "within 100ms" | "within 50ms" | Performance threshold tightened |

### No Deletions (See No-Deletion Policy)

Version Update:

# Tier 2: Increment minor version
# 1.0.1 -> 1.1.0
current_version = "1.0.1"
new_version = increment_version(current_version, "minor")  # "1.1.0"

Tier 3: Archive and Regenerate (> 15% Drift)

Trigger Conditions:

• Major PRD restructuring
• Feature scope changes
• Fundamental requirement changes
• More than 15% content drift

Archive Process:

1. Create Archive Manifest:

---
title: "EARS-NN Archive Manifest"
tags:
  - ears
  - archive
  - drift-management
custom_fields:
  archive_date: "2026-02-10T16:00:00"
  archived_version: "1.1.0"
  drift_percentage: 23.5
  trigger: "Tier 3 - Major Drift"
  upstream_source: "PRD-01.md v2.0.0"
---

# EARS-NN Archive Manifest

## Archive Details

| Field | Value |
|-------|-------|
| Archive Date | 2026-02-10T16:00:00 |
| Archived Version | 1.1.0 |
| Archive Location | `archive/EARS-01_v1.1.0_20260210/` |
| Drift Percentage | 23.5% |
| Reason | Major PRD restructuring |

## Archived Files

| File | Original Location | Archive Location |
|------|-------------------|------------------|
| EARS-01.md | docs/03_EARS/ | archive/EARS-01_v1.1.0_20260210/ |
| EARS-01.1_core.md | docs/03_EARS/EARS-01_slug/ | archive/EARS-01_v1.1.0_20260210/ |
| EARS-01.2_requirements.md | docs/03_EARS/EARS-01_slug/ | archive/EARS-01_v1.1.0_20260210/ |

## Regeneration Instructions

1. Run `/doc-ears-autopilot PRD-01` to generate new EARS
2. New version will be 2.0.0
3. Review archived statements for potential reuse
4. Update downstream BDD references

2. Move to Archive:

def archive_ears_document(ears_path: str, version: str, drift_pct: float) -> str:
    """
    Archive EARS document before regeneration.

    Args:
        ears_path: Path to EARS document
        version: Current version being archived
        drift_pct: Drift percentage that triggered archive

    Returns:
        Archive directory path
    """
    timestamp = datetime.now().strftime('%Y%m%d')
    archive_dir = f"archive/EARS-{doc_num}_v{version}_{timestamp}/"

    # Create archive directory
    os.makedirs(archive_dir, exist_ok=True)

    # Copy all EARS files
    for ears_file in glob(f"{ears_dir}/EARS-{doc_num}*"):
        shutil.copy2(ears_file, archive_dir)

    # Generate archive manifest
    generate_archive_manifest(archive_dir, version, drift_pct)

    return archive_dir

3. Trigger Regeneration:

# Invoke doc-ears-autopilot with major version increment
regeneration_params = {
    "source_prd": "PRD-01",
    "version_override": "2.0.0",
    "archive_reference": archive_dir,
    "preserve_custom_statements": True
}

Version Update:

# Tier 3: Increment major version
# 1.1.0 -> 2.0.0
current_version = "1.1.0"
new_version = increment_version(current_version, "major")  # "2.0.0"

No-Deletion Policy

Critical: EARS requirements are NEVER deleted during auto-merge. Items removed from upstream PRD are marked as deprecated.

Deprecation Marker Format:

### EARS.01.2505 [DEPRECATED]

> **Deprecation Date**: 2026-02-10
> **Reason**: Removed from PRD-01 v1.3.0 (Section 4.2 deleted)
> **Downstream Impact**: BDD-01.2 scenarios affected

**Original Statement**:
When the user initiates export, the system shall generate CSV output within 5 seconds.

**Status**: Deprecated - Do not implement. Retained for traceability.

Deprecation Tracking:

def mark_deprecated(
    ears_id: str,
    reason: str,
    upstream_ref: str,
    downstream_refs: list[str]
) -> None:
    """
    Mark EARS requirement as deprecated instead of deleting.

    Args:
        ears_id: EARS ID to deprecate (e.g., "EARS.01.2505")
        reason: Reason for deprecation
        upstream_ref: PRD reference that triggered deprecation
        downstream_refs: List of downstream BDD references affected
    """
    deprecation_block = f"""
### {ears_id} [DEPRECATED]

> **Deprecation Date**: {datetime.now().strftime('%Y-%m-%d')}
> **Reason**: {reason}
> **Upstream Reference**: {upstream_ref}
> **Downstream Impact**: {', '.join(downstream_refs) if downstream_refs else 'None identified'}

**Status**: Deprecated - Do not implement. Retained for traceability.
"""
    # Insert deprecation block, preserve original statement

Enhanced Drift Cache

After processing drift issues, update .drift_cache.json:

{
  "ears_document": "EARS-01",
  "ears_version": "1.1.0",
  "ears_updated": "2026-02-10T16:00:00",
  "drift_reviewed": "2026-02-10T16:00:00",
  "upstream": {
    "document": "PRD-01.md",
    "version": "1.3.0",
    "last_sync": "2026-02-10T16:00:00"
  },
  "downstream": {
    "documents": ["BDD-01.md"],
    "notification_sent": "2026-02-10T16:05:00"
  },
  "section_hashes": {
    "PRD-01#section-3": "a1b2c3d4e5f6...",
    "PRD-01#section-5": "g7h8i9j0k1l2...",
    "PRD-01#section-7": "m3n4o5p6q7r8..."
  },
  "merge_history": [
    {
      "date": "2026-02-10T16:00:00",
      "tier": 2,
      "drift_percentage": 8.3,
      "version_before": "1.0.1",
      "version_after": "1.1.0",
      "additions": ["EARS.01.2513", "EARS.01.2514", "EARS.01.2605"],
      "modifications": ["EARS.01.2507"],
      "deprecations": []
    }
  ],
  "acknowledged_drift": [
    {
      "document": "PRD-01.md",
      "section": "section-8",
      "acknowledged_date": "2026-02-08",
      "reason": "Informational section - no EARS impact"
    }
  ]
}

Drift Acknowledgment Workflow

When drift is flagged but no EARS update is needed:

1. Run /doc-ears-fixer EARS-01 --acknowledge-drift
2. Fixer prompts: "Review drift for PRD-01.md Section 8?"
3. User confirms no EARS changes needed
4. Fixer adds to acknowledged_drift array
5. Future reviews skip this drift until upstream changes again

Downstream Notification

After any auto-merge, notify downstream BDD documents:

def notify_downstream(ears_id: str, changes: list[dict]) -> None:
    """
    Create notification for downstream BDD documents.

    Args:
        ears_id: EARS document ID (e.g., "EARS-01")
        changes: List of changes made during auto-merge
    """
    notification = {
        "type": "UPSTREAM_CHANGE",
        "source": ears_id,
        "timestamp": datetime.now().isoformat(),
        "changes": changes,
        "action_required": "Run /doc-bdd-fixer to sync"
    }

    # Write to .downstream_notifications.json
    write_notification(f"docs/04_BDD/.downstream_notifications.json", notification)

---

Command Usage

Basic Usage

# Fix EARS based on latest review
/doc-ears-fixer EARS-01

# Fix with explicit review report (legacy)
/doc-ears-fixer EARS-01 --review-report EARS-01.R_review_report_v001.md

# Fix with explicit audit report (preferred)
/doc-ears-fixer EARS-01 --review-report EARS-01.A_audit_report_v001.md

# Fix and re-run review
/doc-ears-fixer EARS-01 --revalidate

# Fix with iteration limit
/doc-ears-fixer EARS-01 --revalidate --max-iterations 3

Options

Option	Default	Description
--review-report	latest	Specific audit/review report to use (.A_audit_report preferred)
--revalidate	false	Run reviewer after fixes
--max-iterations	3	Max fix-review cycles
--fix-types	all	Specific fix types (comma-separated)
--create-missing	true	Create missing reference files
--backup	true	Backup EARS before fixing
--dry-run	false	Preview fixes without applying
--acknowledge-drift	false	Interactive drift acknowledgment mode
--update-drift-cache	true	Update .drift_cache.json after fixes
--auto-merge-tier	auto	Force specific tier (1, 2, 3, or auto)
--skip-archive	false	Skip archiving for Tier 3 (regenerate in-place)
--notify-downstream	true	Send notifications to downstream BDD documents
--preserve-deprecated	true	Keep deprecated items (no-deletion policy)

Report Selection Precedence:

1. Select latest report by timestamp.
2. If timestamps are equal, prefer EARS-NN.A_audit_report_vNNN.md over EARS-NN.R_review_report_vNNN.md.

Fix Types

Type	Description
missing_files	Create missing glossary, pattern, constraint docs
broken_links	Fix link paths
element_ids	Convert invalid/legacy element IDs
content	Fix placeholders, dates, names
references	Update traceability and cross-references
drift	Handle upstream drift detection issues
auto_merge	Apply tiered auto-merge for upstream changes
deprecate	Mark removed upstream items as deprecated
all	All fix types (default)

---

Output Artifacts

Fix Report

Nested Folder Rule: ALL EARS use nested folders (EARS-NN_{slug}/) regardless of size. Fix reports are stored alongside the EARS document in the nested folder.

File Naming: EARS-NN.F_fix_report_vNNN.md

Location: Inside the EARS nested folder: docs/03_EARS/EARS-NN_{slug}/

Structure:

---
title: "EARS-NN.F: Fix Report v001"
tags:
  - ears
  - fix-report
  - quality-assurance
custom_fields:
  document_type: fix-report
  artifact_type: EARS-FIX
  layer: 3
  parent_doc: EARS-NN
  source_review: EARS-NN.A_audit_report_v001.md
  fix_date: "YYYY-MM-DDTHH:MM:SS"
  fix_tool: doc-ears-fixer
  fix_version: "1.0"
---

# EARS-NN Fix Report v001

## Summary

| Metric | Value |
|--------|-------|
| Source Review | EARS-NN.A_audit_report_v001.md (or legacy `EARS-NN.R_review_report_v001.md`) |
| Issues in Review | 12 |
| Issues Fixed | 10 |
| Issues Remaining | 2 (manual review required) |
| Files Created | 2 |
| Files Modified | 4 |

## Files Created

| File | Type | Location |
|------|------|----------|
| EARS-00_GLOSSARY.md | Requirements Glossary | docs/03_EARS/ |
| EARS-01_PATTERN_LIB.md | Pattern Library Placeholder | docs/03_EARS/ |

## Fixes Applied

| # | Issue Code | Issue | Fix Applied | File |
|---|------------|-------|-------------|------|
| 1 | REV-L001 | Broken glossary link | Created EARS-00_GLOSSARY.md | EARS-01.3_constraints.md |
| 2 | REV-L004 | Broken PRD reference | Updated path to ../02_PRD/PRD-01.md | EARS-01.1_core.md |
| 3 | REV-N004 | Element type 01 invalid | Converted to type 25 | EARS-01.1_core.md |
| 4 | REV-L003 | Absolute path used | Converted to relative | EARS-01.2_requirements.md |

## Issues Requiring Manual Review

| # | Issue Code | Issue | Location | Reason |
|---|------------|-------|----------|--------|
| 1 | REV-E001 | Missing EARS keyword | EARS-01.2:L45 | Requirement syntax needed |
| 2 | REV-E002 | Invalid pattern structure | EARS-01.2:L120 | Pattern refinement required |

## Validation After Fix

| Metric | Before | After | Delta |
|--------|--------|-------|-------|
| Review Score | 92 | 97 | +5 |
| Errors | 2 | 0 | -2 |
| Warnings | 4 | 1 | -3 |

## Next Steps

1. Complete EARS-01_PATTERN_LIB.md placeholder
2. Address missing EARS keywords in flagged requirements
3. Run `/doc-ears-reviewer EARS-01` to verify fixes

---

Integration with Autopilot

This skill is invoked by doc-ears-autopilot in the Review -> Fix cycle:

flowchart LR
    subgraph Phase5["Phase 5: Review & Fix Cycle"]
        A[doc-ears-reviewer] --> B{Score >= 85?}
        B -->|No| C[doc-ears-fixer]
        C --> D{Iteration < Max?}
        D -->|Yes| A
        D -->|No| E[Flag for Manual Review]
        B -->|Yes| F[PASS]
    end

Autopilot Integration Points:

Phase	Action	Skill
Phase 5a	Run initial review	doc-ears-reviewer
Phase 5b	Apply fixes if issues found	doc-ears-fixer
Phase 5c	Re-run review	doc-ears-reviewer
Phase 5d	Repeat until pass or max iterations	Loop

---

Error Handling

Recovery Actions

Error	Action
Audit/review report not found	Prompt to run doc-ears-audit or doc-ears-reviewer first
Cannot create file (permissions)	Log error, continue with other fixes
Cannot parse report	Abort with clear error message
Max iterations exceeded	Generate report, flag for manual review
PRD not found	Log warning, skip PRD-dependent fixes

Backup Strategy

Before applying any fixes:

1. Create backup in tmp/backup/EARS-NN_YYYYMMDD_HHMMSS/
2. Copy all EARS files to backup location
3. Apply fixes to original files
4. If error during fix, restore from backup

---

Related Skills

Skill	Relationship
doc-ears-audit	Preferred combined audit report input
doc-ears-reviewer	Provides review report (input)
doc-ears-autopilot	Orchestrates Review -> Fix cycle
doc-ears-validator	Structural validation
doc-naming	Element ID standards
doc-ears	EARS creation rules
doc-prd-reviewer	Upstream PRD validation

---

Version History

Version	Date	Changes
2.2	2026-02-26	Migrated frontmatter to metadata; added compatibility for EARS-NN.A_audit_report_vNNN.md (preferred) with legacy EARS-NN.R_review_report_vNNN.md; defined deterministic precedence (latest timestamp, then .A_ over .R_ on ties)
2.1	2026-02-11	Structure Compliance: Added Phase 0 for nested folder rule enforcement (REV-STR001-STR003); Runs FIRST before other fix phases
2.0	2026-02-10	Enhanced Phase 6 with tiered auto-merge system; Tier 1 (< 5%): auto-merge additions with patch version; Tier 2 (5-15%): auto-merge with changelog and minor version; Tier 3 (> 15%): archive + regenerate with major version; No-deletion policy with deprecation markers; Auto-generated IDs (EARS.NN.xxxx pattern); Enhanced drift cache with merge history; Downstream BDD notification system
1.0	2026-02-10	Initial skill creation; 6-phase fix workflow; Glossary and pattern file creation; Element ID conversion for EARS codes (25, 26); Broken link fixes; PRD drift detection; EARS pattern syntax validation; Integration with autopilot Review->Fix cycle

Implementation Plan Consistency (IPLAN-004)

• Treat plan-derived outputs as valid source mode and verify intent preservation from implementation plan scope/objectives.
• Validate upstream autopilot precedence assumption: --iplan > --ref > --prompt.
• Flag objective/scope conflicts between plan context and artifact output as blocking issues requiring clarification.
• Do not introduce legacy fallback paths such as docs-v2.0/00_REF.