doc-brd-fixer

Purpose

Automated fix skill that reads the latest audit report and applies fixes to BRD documents. This skill bridges the gap between doc-brd-audit (which identifies issues) and the corrected BRD, enabling iterative improvement cycles.

Layer: 1 (BRD Quality Improvement)

Upstream: BRD document, Audit Report (BRD-NN.A_audit_report_vNNN.md )

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

2-Skill Model: Only doc-brd-audit and doc-brd-fixer exist. The deprecated doc-brd-validator and doc-brd-reviewer are merged into doc-brd-audit .

When to Use This Skill

Use doc-brd-fixer when:

• After Audit: Run after doc-brd-audit identifies issues (FAIL status)

• Iterative Improvement: Part of Audit → Fix → Audit cycle

• Automated Pipeline: CI/CD integration for quality gates

• Batch Fixes: Apply fixes to multiple BRDs based on audit reports

Do NOT use when:

• No audit report exists (run doc-brd-audit first)

• Creating new BRD (use doc-brd or doc-brd-autopilot )

• BRD already passes audit (score >= 90)

Skill Dependencies

Skill Purpose When Used

doc-brd-audit

Source of issues to fix (REQUIRED) Input (reads audit report)

doc-naming

Element ID standards Fix element IDs

doc-brd

BRD creation rules Create missing sections

2-Skill Model:

Skill Purpose

doc-brd-audit

All validation + scoring (runs FROM SCRATCH)

doc-brd-fixer

Apply fixes from audit report (this skill)

Deprecated: doc-brd-validator and doc-brd-reviewer are merged into doc-brd-audit .

Input: Latest BRD-NN.A_audit_report_vNNN.md

Workflow Overview

flowchart TD A[Input: BRD Path] --> B[Find Latest Audit Report] B --> C{Audit Found?} C -->|No| D[Run doc-brd-audit First] C -->|Yes| E[Parse Audit 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 BRD]
L --> M[Generate Fix Report]
M --> N{Re-run Audit?}
N -->|Yes| O[Invoke doc-brd-audit FROM SCRATCH]
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 BRDs that are not in nested folders. This phase runs FIRST because all subsequent phases depend on correct folder structure.

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

Required Structure:

BRD Type Required Location

Monolithic docs/01_BRD/BRD-NN_{slug}/BRD-NN_{slug}.md

Sectioned docs/01_BRD/BRD-NN_{slug}/BRD-NN.0_index.md , BRD-NN.1_*.md , etc.

Fix Actions:

Issue Code Issue Fix Action

REV-STR001 BRD not in nested folder Create folder, move file, update all links

REV-STR002 BRD folder name doesn't match BRD ID Rename folder to match

REV-STR003 Monolithic BRD >25KB should be sectioned Flag for manual review

Structure Fix Workflow:

def fix_brd_structure(brd_path: str) -> list[Fix]: """Fix BRD structure violations.""" fixes = []

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

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

brd_id = match.group(1)
slug = match.group(2)
expected_folder = f"BRD-{brd_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(brd_path, new_path)
    fixes.append(f"Moved {brd_path} to {new_path}")

    # Update reference links in moved file
    content = Path(new_path).read_text()
    updated_content = content.replace('../00_REF/', '../../00_REF/')
    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

../00_REF/foundation/spec.md

../../00_REF/foundation/spec.md

BRD-00_GLOSSARY.md

../BRD-00_GLOSSARY.md

Phase 1: Create Missing Files

Creates files that are referenced but don't exist.

Scope:

Missing File Action Template Used

BRD-00_GLOSSARY.md

Create master glossary Glossary template

GAP_*.md

Create placeholder with TODO sections GAP template

Reference docs (REF.md ) Create placeholder REF template

Glossary Template:

title: "BRD-00: Master Glossary" tags:

• brd
• glossary
• reference custom_fields: document_type: glossary artifact_type: BRD-REFERENCE layer: 1

BRD-00: Master Glossary

Common terminology used across all Business Requirements Documents.

Business Terms

Technical Terms

Domain Terms

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

GAP Analysis Placeholder Template:

title: "GAP Analysis: [Module Name]" tags:

• gap-analysis
• reference custom_fields: document_type: gap-analysis status: placeholder created_by: doc-brd-fixer

GAP Analysis: [Module Name]

Status: Placeholder - Requires completion

1. Current State

[TODO: Document current implementation state]

2. Identified Gaps

3. Remediation Plan

[TODO: Document remediation approach]

Created by doc-brd-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

Path Resolution Logic:

def fix_link_path(brd_location: str, target_path: str) -> str: """Calculate correct relative path based on BRD location."""

# Monolithic BRD: docs/01_BRD/BRD-01.md
# Sectioned BRD: docs/01_BRD/BRD-01_slug/BRD-01.3_section.md

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

Glossary Link Fix:

BRD Type Original Link Fixed Link

Monolithic BRD-00_GLOSSARY.md

BRD-00_GLOSSARY.md

Sectioned BRD-00_GLOSSARY.md

../BRD-00_GLOSSARY.md

Phase 3: Fix Element IDs

Converts invalid element IDs to correct format.

Conversion Rules:

Pattern Issue Conversion

BRD.NN.25.SS

Code 25 invalid for BRD Manual remap to context-appropriate valid BRD code (23 , 24 , 22 , 08 , etc.)

BO-XXX

Legacy pattern BRD.NN.23.SS

FR-XXX

Legacy pattern BRD.NN.01.SS

AC-XXX

Legacy pattern BRD.NN.06.SS

BC-XXX

Legacy pattern BRD.NN.03.SS

Type Code Mapping (BRD-specific):

Invalid Code Valid Code Element Type

19 22 Feature Item (deprecated 19)

31 32 Architecture Topic (deprecated 31)

For code 25 in BRD context, do not auto-convert to a fixed code; classify by section semantics and remap manually.

Regex Patterns:

Find element IDs with invalid type codes for BRD

invalid_brd_type_25 = r'BRD.(\d{2}).25.(\d{2})'

No fixed replacement for BRD type 25; requires section-aware remapping

Find legacy patterns

legacy_bo = r'###\s+BO-(\d+):' legacy_fr = r'###\s+FR-(\d+):'

Phase 4: Fix Content Issues

Addresses placeholders and incomplete content.

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-MVP001 Missing 2.1 MVP Hypothesis

Add explicit subsection with hypothesis and measurable validation signals

REV-MVP002 Missing 3.2 MVP Core Features

Add explicit subsection and checklist; preserve existing scope details

REV-MVP003 Missing 9.1 MVP Launch Criteria

Add explicit go/no-go launch gate table

REV-MVP004 Missing 14.5 Approval and Sign-off

Add stakeholder sign-off table

REV-MVP008 Missing test coverage traceability Add explicit 16.3 Test Coverage Traceability view

REV-MVP010 Missing glossary structure 17.1-17.6 Add missing glossary subsections without deleting existing terms

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'), }

4.1 MVP Subsection Semantic Normalization (NEW in v2.4)

Before adding new subsections, detect equivalent headings and normalize in place to avoid duplicate content.

Required Header Acceptable Equivalent Patterns

2.1 MVP Hypothesis

2.1 Background and Context , 2.1 Hypothesis

3.2 MVP Core Features

3.2 In-Scope Items , 3.2 Scope Items

9.1 MVP Launch Criteria

9.1 Business Acceptance Criteria , 9.1 Launch Readiness

Normalization Rule:

• If equivalent heading exists, rename heading to required canonical title.

• Preserve existing table/list content under that section.

• Insert template block only when section content is missing or below minimum structure.

4.2 Safe Subsection Renumbering (NEW in v2.4)

When inserting missing required subsection numbers, perform deterministic renumbering for subsequent sibling subsections.

def renumber_sibling_headings(content: str, section_prefix: str, insert_at: float) -> str: """Shift sibling subsection numbers after insertion point. Example: insert 9.1 -> existing 9.1 becomes 9.2, 9.2 becomes 9.3. """

1) parse headings matching '^##\s+{section_prefix}.\d+'

2) process from highest to lowest subsection number

3) increment only siblings >= insert_at

4) do not modify sub-subsection identifiers beyond parent prefix

return content

Safety Constraints:

• Apply only within same section file.

• Skip renumbering when explicit cross-reference anchors would break (flag manual review).

• Log all renumber actions in fix report.

4.3 Template Compliance Contract (NEW in v2.5)

All content fixes MUST align to the canonical template:

• docs_flow_framework/ai_dev_ssd_flow/01_BRD/BRD-MVP-TEMPLATE.md

• docs_flow_framework/ai_dev_ssd_flow/01_BRD/BRD-MVP-TEMPLATE.yaml

Canonical Subsection Anchors (MVP):

Section Required Anchors

1 1.1-1.4

2 2.1-2.5

3 3.1-3.5, 3.4.1, 3.4.2

5 5.1-5.2

6 6.1-6.5

8 8.1-8.2

9 9.1-9.2

11 11.1-11.2

12 12.1-12.3

14 14.1-14.5

15 15.1-15.3

16 16.1-16.4

17 17.1-17.6 (17.5 Cross-References, 17.6 External Standards)

18 18.1-18.5

If existing headings use legacy names, normalize to template-canonical labels before validation.

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-BRD path Update to correct relative path

Missing traceability entry Add to traceability matrix

5.1 Markdown Normalization for Generated Reports (NEW in v2.4)

Normalize fixer-generated markdown artifacts to reduce lint friction.

Scope:

• Fix/Fix-validation report headings (## title under YAML frontmatter)

• Table separator style normalization

• Blank lines around lists and tables

Applies To:

• BRD-NN.F_fix_report_vNNN.md

• Any fixer-generated supplemental notes

Phase 5.5: Fix Confidence Classification (NEW in v2.4)

Each fix action is tagged for downstream gating.

Confidence Meaning Typical Examples

auto-safe

Deterministic structural/text fix with low semantic risk link path correction, section header normalization, ID conversion

auto-assisted

Template insertion with partial semantic assumptions generated launch criteria table, glossary subsection scaffolding

manual-required

Domain-specific content cannot be reliably inferred unresolved TODO/TBD, business strategy rationale gaps

Fix Report Requirement:

• Add confidence column in Fixes Applied table.

• Include summary counts by confidence level.

Phase 6: Handle Upstream Configuration

Fixes upstream configuration issues before handling drift.

6.0 Metadata Fixes

FIX-M001: Add Missing deliverable_type

Trigger: BRD has no deliverable_type in YAML frontmatter

Fix Action: Add deliverable_type: code (default) to custom_fields

Before

custom_fields: document_type: brd-document artifact_type: BRD

After

custom_fields: document_type: brd-document artifact_type: BRD deliverable_type: code

FIX-M002: Fix Invalid deliverable_type

Trigger: deliverable_type value is not one of: code , document , ux , risk , process

Fix Action: Suggest correct value based on BRD content analysis or reset to code (default)

Before

custom_fields: deliverable_type: software # Invalid

After (auto-detect or default)

custom_fields: deliverable_type: code

Content-Based Detection Logic:

def detect_deliverable_type(brd_content: str) -> str: """Detect appropriate deliverable_type from BRD content.""" # Check for UX indicators if any(kw in brd_content.lower() for kw in ['wireframe', 'mockup', 'user interface', 'ui/ux', 'design system']): return 'ux'

# Check for documentation indicators
if any(kw in brd_content.lower() for kw in ['user guide', 'api documentation', 'technical manual', 'help content']):
    return 'document'

# Check for risk/compliance indicators
if any(kw in brd_content.lower() for kw in ['risk assessment', 'compliance framework', 'audit trail', 'security audit']):
    return 'risk'

# Check for process indicators
if any(kw in brd_content.lower() for kw in ['workflow automation', 'process improvement', 'business process', 'operational procedure']):
    return 'process'

# Default to code
return 'code'

FIX-M003: Fix document_type for Instance

Trigger: BRD instance has document_type: template instead of document_type: brd-document

Fix Action: Change to brd-document

Before

custom_fields: document_type: template # Wrong for instance

After

custom_fields: document_type: brd-document

6.1 Upstream Configuration Fixes

FIX-U001: Add Missing upstream_mode

Trigger: BRD has no upstream_mode in YAML frontmatter

Fix Action: Add upstream_mode: "none" to custom_fields

Before

custom_fields: artifact_type: BRD

After

custom_fields: artifact_type: BRD upstream_mode: "none"

FIX-U002: Suggest upstream_ref_path

Trigger: BRD has @ref: tags pointing to 00_REF/ but upstream_mode: "none"

Detection:

• Scan BRD content for @ref: tags

• Extract referenced paths

• Determine common parent directory in 00_REF/

Fix Action: Suggest updating to upstream_mode: "ref" with detected path

Suggested fix (requires confirmation)

custom_fields: upstream_mode: "ref" upstream_ref_path: "../../00_REF/source_docs/"

FIX-U003: Remove Invalid upstream_ref_path

Trigger: upstream_mode: "none" but upstream_ref_path is set

Fix Action: Remove upstream_ref_path field (it's ignored anyway)

Before

custom_fields: upstream_mode: "none" upstream_ref_path: "../../00_REF/" # Ignored

After

custom_fields: upstream_mode: "none"

Metadata Fix Codes:

Code Description Auto-Fix

FIX-M001 Add deliverable_type: code Yes

FIX-M002 Fix invalid deliverable_type Auto-detect or prompt

FIX-M003 Fix document_type to brd-document Yes

Upstream Configuration Fix Codes:

Code Description Auto-Fix

FIX-U001 Add upstream_mode: "none" Yes

FIX-U002 Suggest upstream_mode: "ref" with detected path Prompt

FIX-U003 Remove unnecessary upstream_ref_path Yes

6.2 Hash Validation Fixes

Fixes invalid hash values in .drift_cache.json that prevent drift detection from working correctly.

FIX-H001: Invalid Hash Placeholder

Field Value

Trigger Hash field contains placeholder instead of actual SHA-256

Detection Hash matches: verified_no_drift , pending_verification , TBD , or length != 64 hex

Severity Error

Auto-Fix Yes

Detection Algorithm:

Check for placeholder values in drift cache

grep -E '"hash":\s*"(sha256:)?(verified_no_drift|pending_verification|TBD)"' .drift_cache.json

Fix Action:

Compute actual hash for upstream file

HASH=$(sha256sum <upstream_file_path> | cut -d' ' -f1)

Update cache with: "hash": "sha256:$HASH"

Example:

// Before (INVALID) "hash": "sha256:pending_verification"

// After (VALID) "hash": "sha256:a9ca05f4e9b2379465526221271672954feff29e40c57f2a91fe8a050eb46105"

FIX-H002: Missing Hash Prefix

Field Value

Trigger Hash value is 64 hex chars but missing sha256: prefix

Detection Matches ^[0-9a-f]{64}$ without prefix

Severity Warning

Auto-Fix Yes

Fix Action: Prepend sha256: to existing hash value

// Before "hash": "a9ca05f4e9b2379465526221271672954feff29e40c57f2a91fe8a050eb46105"

// After "hash": "sha256:a9ca05f4e9b2379465526221271672954feff29e40c57f2a91fe8a050eb46105"

FIX-H003: Upstream File Not Found

Field Value

Trigger Cannot compute hash because upstream file does not exist

Detection File at upstream_ref_path returns error from sha256sum

Severity Error

Auto-Fix Partial

Fix Action:

• Log warning: Upstream file not found: <path>

• Set drift_detected: true in cache

• Set hash to sha256:FILE_NOT_FOUND

• Add note to manual review queue

Hash Fix Codes Summary:

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

Phase 6.3: Handle Upstream Drift (Auto-Merge)

Automatically merges upstream changes into the document based on change percentage thresholds.

Note: This phase only runs when upstream_mode: "ref" . When upstream_mode: "none" (default), drift detection is skipped.

Drift Detection Workflow:

flowchart TD A[Detect Upstream Changes] --> B[Calculate Change %] B --> C{Change Analysis}

C -->|< 5%| D[TIER 1: Auto-Merge]
C -->|5-15%| E[TIER 2: Auto-Merge + Detailed Log]
C -->|> 15%| F[TIER 3: Archive + Regenerate]

D --> D1[Add new requirements]
D1 --> D2[Update thresholds]
D2 --> D3[Update references]
D3 --> D4[Increment patch: 1.0→1.0.1]

E --> E1[Add new requirements]
E1 --> E2[Update thresholds]
E2 --> E3[Update references]
E3 --> E4[Generate detailed changelog]
E4 --> E5[Increment minor: 1.0→1.1]

F --> F1[Mark current as ARCHIVED]
F1 --> F2[Update status in frontmatter]
F2 --> F3[Trigger regeneration via autopilot]
F3 --> F4[Increment major: 1.x→2.0]

D4 --> G[Update Drift Cache]
E5 --> G
F4 --> G
G --> H[Add to Fix Report]

6.3.1 Change Percentage Calculation

def calculate_change_percentage(upstream_old: str, upstream_new: str) -> dict: """ Calculate change percentage between upstream versions.

Returns:
    {
        'total_change_pct': float,      # Overall change percentage
        'additions_pct': float,          # New content added
        'modifications_pct': float,      # Existing content modified
        'deletions_pct': float,          # Content removed (tracked, not applied)
        'change_type': str               # 'minor' | 'moderate' | 'major'
    }
"""
old_lines = upstream_old.strip().split('\n')
new_lines = upstream_new.strip().split('\n')

# Use difflib for precise change detection
import difflib
diff = difflib.unified_diff(old_lines, new_lines)

additions = sum(1 for line in diff if line.startswith('+') and not line.startswith('+++'))
deletions = sum(1 for line in diff if line.startswith('-') and not line.startswith('---'))

total_lines = max(len(old_lines), len(new_lines))
total_change_pct = ((additions + deletions) / total_lines) * 100 if total_lines > 0 else 0

return {
    'total_change_pct': round(total_change_pct, 2),
    'additions_pct': round((additions / total_lines) * 100, 2) if total_lines > 0 else 0,
    'modifications_pct': round((min(additions, deletions) / total_lines) * 100, 2) if total_lines > 0 else 0,
    'deletions_pct': round((deletions / total_lines) * 100, 2) if total_lines > 0 else 0,
    'change_type': 'minor' if total_change_pct < 5 else 'moderate' if total_change_pct < 15 else 'major'
}

6.3.2 Tier 1: Auto-Merge (< 5% Change)

Trigger: Total change percentage < 5%

Actions:

Change Type Auto-Action Example

New requirement added Append with generated ID BRD.01.01.13

Threshold value changed Find & replace value timeout: 30 → 45

Reference updated Update @ref: path Path correction

Version incremented Update version reference v1.2 → v1.3

ID Generation for New Requirements:

def generate_next_id(doc_type: str, doc_num: str, element_type: str, existing_ids: list) -> str: """ Generate next sequential ID for new requirement.

Args:
    doc_type: 'BRD', 'PRD', etc.
    doc_num: '01', '02', etc.
    element_type: '01' (Functional), '02' (Quality), etc.
    existing_ids: List of existing IDs in document

Returns:
    Next available ID (e.g., 'BRD.01.01.13')
"""
pattern = f"{doc_type}.{doc_num}.{element_type}."
matching = [id for id in existing_ids if id.startswith(pattern)]

if not matching:
    return f"{pattern}01"

max_seq = max(int(id.split('.')[-1]) for id in matching)
return f"{pattern}{str(max_seq + 1).zfill(2)}"

Auto-Merge Template for New Requirements:

{GENERATED_ID}: {Requirement Title}

Source: Auto-merged from {upstream_doc} ({change_date})

Requirement: {requirement_text}

Acceptance Criteria: {acceptance_criteria}

Priority: {priority}

<!-- AUTO-MERGED: {timestamp} from {upstream_doc}#{section} -->

Version Update:

• Increment patch version: 1.0 → 1.0.1

• Update last_updated in frontmatter

• Add changelog entry

6.3.3 Tier 2: Auto-Merge with Detailed Log (5-15% Change)

Trigger: Total change percentage between 5% and 15%

Actions: Same as Tier 1, plus:

Additional Action Description

Detailed changelog Section-by-section change log

Impact analysis Which downstream artifacts affected

Merge markers <!-- MERGED: ... --> comments

Version history Detailed version history entry

Changelog Entry Format:

Changelog

Version 1.1 (2026-02-10T16:00:00)

Upstream Sync: Auto-merged 8.5% changes from upstream documents

New Requirements Added:

• BRD.01.01.13: Passkey Authentication Support
• BRD.01.01.14: WebAuthn Fallback Mechanism

Thresholds Updated:

• BRD.01.02.05: session_idle_timeout: 30→45 min

Impact: PRD-01, EARS-01, ADR-01 may require review

Version Update:

• Increment minor version: 1.0 → 1.1

• Update last_updated in frontmatter

• Add detailed changelog entry

6.3.4 Tier 3: Archive and Regenerate (> 15% Change)

Trigger: Total change percentage > 15%

Actions:

Step Action Result

1 Mark current version as ARCHIVED Status update in frontmatter

2 Create archive copy BRD-01_v1.0_archived.md

3 Update frontmatter status status: archived

4 Trigger autopilot regeneration New version generated

5 Increment major version 1.x → 2.0

Archive Frontmatter Update:

title: "BRD-01: F1 Identity & Access Management" custom_fields: version: "1.2" status: "archived" # Changed from 'current' archived_date: "2026-02-10T16:00:00" archived_reason: "upstream_drift_major" superseded_by: "BRD-01_v2.0" upstream_change_pct: 18.5

Archive File Naming:

docs/01_BRD/BRD-01_f1_iam/ ├── BRD-01.0_index.md # Current (v2.0) ├── BRD-01.1_core.md # Current (v2.0) ├── .archive/ │ ├── v1.2/ │ │ ├── BRD-01.0_index.md # Archived v1.2 │ │ ├── BRD-01.1_core.md │ │ └── ARCHIVE_MANIFEST.md # Archive metadata

ARCHIVE_MANIFEST.md:

Archive Manifest: BRD-01 v1.2

Change Summary

Downstream Impact

Documents requiring update after regeneration:

• PRD-01 (references BRD-01)
• EARS-01 (derived from PRD-01)
• ADR-01 (architecture decisions)

No Deletion Policy:

• Upstream content marked as deleted is NOT removed from document

• Instead, marked with [DEPRECATED] status:

BRD.01.01.05: Legacy Authentication Method [DEPRECATED]

Status: DEPRECATED (upstream removed 2026-02-10T16:00:00) Reason: Replaced by BRD.01.01.13 (Passkey Authentication) Action: Retain for traceability; do not implement

Original Requirement: {original_text}

6.3.5 Drift Cache Update

After processing drift, update .drift_cache.json :

{ "document_version": "1.1", "last_synced": "2026-02-10T16:00:00", "sync_status": "auto-merged", "upstream_state": { "../../00_REF/foundation/F1_IAM_Technical_Specification.md": { "hash": "sha256:a1b2c3d4e5f6...", "version": "2.3", "last_modified": "2026-02-10T15:30:00", "change_pct": 4.2, "sync_action": "tier1_auto_merge" }, "../../00_REF/foundation/GAP_Analysis.md": { "hash": "sha256:g7h8i9j0k1l2...", "version": "1.5", "last_modified": "2026-02-10T14:00:00", "change_pct": 8.7, "sync_action": "tier2_auto_merge_detailed" } }, "merge_history": [ { "date": "2026-02-10T16:00:00", "tier": 1, "change_pct": 4.2, "items_added": 1, "items_updated": 2, "version_before": "1.0", "version_after": "1.0.1" } ], "deprecated_items": [ { "id": "BRD.01.01.05", "deprecated_date": "2026-02-10T16:00:00", "reason": "Upstream removal", "replaced_by": "BRD.01.01.13" } ] }

6.3.6 Fix Report: Drift Section

Drift Summary in Fix Report:

Phase 6: Upstream Drift Resolution

Drift Analysis Summary

Tier 1 Auto-Merges (< 5%)

Tier 2 Auto-Merges (5-15%)

Tier 3 Archives (> 15%)

Archive Location: docs/01_BRD/BRD-01_f1_iam/.archive/v1.2/

Deprecated Items (No Deletion)

Version Changes

Command Usage

Basic Usage

Fix BRD based on latest review

/doc-brd-fixer BRD-01

Fix with explicit review report

/doc-brd-fixer BRD-01 --review-report BRD-01.R_review_report_v001.md

Fix and re-run review

/doc-brd-fixer BRD-01 --revalidate

Fix with iteration limit

/doc-brd-fixer BRD-01 --revalidate --max-iterations 3

Options

Option Default Description

--review-report

latest Specific review report to use

--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 BRD before fixing

--dry-run

false Preview fixes without applying

--normalize-markdown

true Normalize generated report markdown style

--acknowledge-drift

false Interactive drift acknowledgment mode

--update-drift-cache

true Update .drift_cache.json after fixes

Fix Types

Type Description

missing_files

Create missing glossary, GAP, reference 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

all

All fix types (default)

Report Cleanup Policy (MANDATORY)

After generating a new fix report, delete all previous fix reports. Old reports serve no purpose since:

• Each fix cycle produces a complete new report

• Only the latest report reflects current document state

• Multiple old reports clutter the BRD folder

Cleanup Rules

File Pattern Action Reason

BRD-NN.F_fix_report_v*.md (older versions) DELETE Superseded by new fix report

BRD-NN.A_audit_report_v*.md

KEEP Managed by doc-brd-audit

.drift_cache.json

KEEP Tracks review/fix history metadata

Cleanup Execution

After writing the new fix report, run:

In the BRD folder (e.g., docs/01_BRD/BRD-50_octo_agent_orchestration/)

BRD_FOLDER="$1" NEW_REPORT="$2" # e.g., BRD-50.F_fix_report_v003.md

Delete old fix reports (keep only the new one)

find "${BRD_FOLDER}" -name "BRD-.F_fix_report_v.md" ! -name "$(basename ${NEW_REPORT})" -delete

Cleanup Confirmation

The fix report should include a cleanup summary:

Cleanup Summary

• Deleted: 2 old fix reports (v001, v002)

Output Artifacts

Fix Report

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

File Naming: BRD-NN.F_fix_report_vNNN.md

Location: Inside the BRD nested folder: docs/01_BRD/BRD-NN_{slug}/

Structure:

title: "BRD-NN.F: Fix Report v001" tags:

• brd
• fix-report
• quality-assurance custom_fields: document_type: fix-report artifact_type: BRD-FIX layer: 1 parent_doc: BRD-NN source_review: BRD-NN.R_review_report_v001.md fix_date: "YYYY-MM-DDTHH:MM:SS" fix_tool: doc-brd-fixer fix_version: "1.0"

BRD-NN Fix Report v001

Summary

Files Created

Fixes Applied

Issues Requiring Manual Review

Validation After Fix

Next Steps

1. Run unified BRD core validation wrapper: bash ai_dev_ssd_flow/01_BRD/scripts/validate_brd_wrapper.sh docs/01_BRD --skip-advisory
2. Complete GAP_Foundation_Module_Gap_Analysis.md placeholder
3. Address remaining [TODO] placeholders
4. Run /doc-brd-audit BRD-01 to verify fixes

Integration with Autopilot

This skill is invoked by doc-brd-autopilot in the Audit → Fix cycle:

flowchart LR subgraph Phase5["Phase 5: Audit & Fix Cycle"] A[doc-brd-audit] --> B{Score >= 90?} B -->|No| C[doc-brd-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 audit doc-brd-audit

Phase 5b Apply fixes if issues found doc-brd-fixer

Phase 5c Re-run unified core validation wrapper validate_brd_wrapper.sh

Phase 5d Re-run audit doc-brd-audit

Phase 5e Repeat until pass or max iterations Loop

Diagram Contract Fix Rules

Apply these fixes when reviewer/audit reports include diagram contract findings.

Issue Code Fix Action

REV-DC001 Insert missing mandatory BRD tags: @diagram: c4-l1 and @diagram: dfd-l0

REV-DC002 If sequence diagram exists, insert one sequence contract tag: `@diagram: sequence-sync

REV-DC003 Add missing intent header fields above mandatory diagram blocks: diagram_type , level , scope_boundary , upstream_refs , downstream_refs

REV-DC004 Add trust-boundary annotation where data-boundary movement is described

Safety Rule:

• Do not rewrite diagram logic unless syntax is invalid.

• Prefer minimal edits to headers/tags and preserve existing narrative semantics.

Error Handling

Recovery Actions

Error Action

Audit report not found Prompt to run doc-brd-audit first

Cannot create file (permissions) Log error, continue with other fixes

Cannot parse review report Abort with clear error message

Max iterations exceeded Generate report, flag for manual review

Backup Strategy

Before applying any fixes:

• Create backup in tmp/backup/BRD-NN_YYYYMMDD_HHMMSS/

• Copy all BRD files to backup location

• Apply fixes to original files

• If error during fix, restore from backup

Related Skills

Skill Relationship

doc-brd-audit

Provides audit report (input) - unified validation + scoring

doc-brd-autopilot

Orchestrates Audit → Fix cycle

doc-naming

Element ID standards

doc-brd

BRD creation rules

2-Skill Model: Only doc-brd-audit and doc-brd-fixer are active. The deprecated doc-brd-validator and doc-brd-reviewer are merged into doc-brd-audit .

Version History

Version Date Changes

3.1 2026-03-05 Metadata Fixes: Added Phase 6.0 for deliverable_type validation fixes (FIX-M001, FIX-M002, FIX-M003); Auto-detects deliverable_type from content (code , document , ux , risk , process ); Fixes document_type for instances; Renumbered Phase 6 subsections (6.1→6.1, 6.0.1→6.2, 6.1→6.3)

3.0 2026-03-05 Report Cleanup Policy: Added mandatory cleanup of old fix reports after generating new one; Deletes previous BRD-NN.F_fix_report_v*.md files; Added cleanup summary section to fix report

2.9 2026-03-01 2-Skill Model: Updated Related Skills to reference doc-brd-audit only; deprecated doc-brd-validator and doc-brd-reviewer merged into unified audit

2.7 2026-02-28 Standardized validator parity: Removed 25→33 auto-conversion guidance; code 25 in BRD now requires manual context-based remapping to valid BRD codes, aligned with validate_standardized_element_codes.py .

2.6 2026-02-27 Hash Validation Fixes: Added Section 6.0.1 with FIX-H001 (placeholder replacement via sha256sum), FIX-H002 (missing prefix), FIX-H003 (file not found); Auto-fix invalid hash placeholders like verified_no_drift and pending_verification

1.2 2026-02-26 Unified template-based versioning: Skill version now tracks ai_dev_ssd_flow/01_BRD/BRD-MVP-TEMPLATE schema version for reviewer/fixer/autopilot consistency.

2.5 2026-02-26 Template contract enforcement: Added explicit compliance anchors to ai_dev_ssd_flow/01_BRD/BRD-MVP-TEMPLATE.md

• YAML variant; required subsection map now includes 3.4.1/3.4.2, 12.1-12.3, and 18.1-18.5 for fixer normalization and insertion logic.

2.4 2026-02-26 Fix quality upgrade: Added semantic normalization for MVP subsection headers (REV-MVP001/002/003), safe sibling subsection renumbering, explicit auto-fixes for REV-MVP004/008/010, markdown normalization for generated fix artifacts, and confidence tagging (auto-safe , auto-assisted , manual-required ) for each applied fix.

2.3 2026-02-25 Template alignment: Updated for 18-section structure with sections 12 (Support), 14 (Governance/Approval), 15 (QA), 16 (Traceability 16.1-16.4), 17 (Glossary 17.1-17.6); Added fixes for missing section subsections

2.2 2026-02-24T21:30:00 Upstream Configuration Fixes: Added Phase 6.0 for upstream_mode fixes (FIX-U001, FIX-U002, FIX-U003); Detects @ref: tags and suggests upstream_mode: "ref"; Cleans up ignored upstream_ref_path when mode is "none"

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-10T16:00:00 Major: Implemented tiered auto-merge system - Tier 1 (<5%): auto-merge additions/updates; Tier 2 (5-15%): auto-merge with detailed changelog; Tier 3 (>15%): archive current version and trigger regeneration; No deletion policy (mark as DEPRECATED instead); Auto-generated IDs for new requirements; Archive manifest creation; Enhanced drift cache with merge history

1.1 2026-02-10T14:30:00 Added Phase 6: Handle Upstream Drift - processes REV-D001-D005 issues from reviewer Check #9; drift marker insertion; drift cache management; acknowledgment workflow

1.0 2026-02-10T12:00:00 Initial skill creation; 5-phase fix workflow; Glossary and GAP file creation; Element ID conversion (type 25→33); Broken link fixes; Integration with autopilot Review→Fix cycle