doc-brd-autopilot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

doc-brd-autopilot

Purpose

用途

Automated Business Requirements Document (BRD) generation pipeline that processes reference documents (

docs/00_REF/

REF/

) or user prompts to generate comprehensive BRDs with type determination, readiness validation, master index management, and parallel execution support.

Layer: 1 (Entry point - no upstream document dependencies)

Downstream Artifacts: PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5)

自动化**业务需求文档（BRD）**生成流水线，处理参考文档（

docs/00_REF/

或

REF/

）或用户提示，生成包含类型判定、就绪状态验证、主索引管理和并行执行支持的完整BRD文档。

层级：1（入口点 - 无上游文档依赖）

下游工件：PRD（层级2）、EARS（层级3）、BDD（层级4）、ADR（层级5）

Skill Dependencies

技能依赖

This autopilot orchestrates the following skills:

Skill	Purpose	Phase
`doc-naming`	Element ID format (BRD.NN.TT.SS), threshold tags, legacy pattern detection	All Phases
`doc-brd`	BRD creation rules, template, section structure, Platform vs Feature guidance	Phase 3: BRD Generation
`quality-advisor`	Real-time quality feedback during BRD generation	Phase 3: BRD Generation
`doc-brd-validator`	Validate BRD structure, content, PRD-Ready score	Phase 4: BRD Validation
`doc-brd-reviewer`	Content review, link validation, quality scoring	Phase 5: Review
`doc-brd-fixer`	Apply fixes from review report, create missing files	Phase 5: Fix

Delegation Principle: The autopilot orchestrates workflow but delegates:

BRD structure/content rules →
```
doc-brd
```
skill
Real-time quality feedback →
```
quality-advisor
```
skill
BRD validation logic →
```
doc-brd-validator
```
skill
Content review and scoring →
```
doc-brd-reviewer
```
skill
Issue resolution and fixes →
```
doc-brd-fixer
```
skill
Element ID standards →
```
doc-naming
```
skill

该自动流水线编排以下技能：

技能	用途	阶段
`doc-naming`	元素ID格式（BRD.NN.TT.SS）、阈值标签、遗留模式检测	所有阶段
`doc-brd`	BRD创建规则、模板、章节结构、平台型vs功能型指导	阶段3：BRD生成
`quality-advisor`	BRD生成期间的实时质量反馈	阶段3：BRD生成
`doc-brd-validator`	验证BRD结构、内容、PRD就绪分数	阶段4：BRD验证
`doc-brd-reviewer`	内容评审、链接验证、质量评分	阶段5：评审
`doc-brd-fixer`	应用评审报告中的修复、创建缺失文件	阶段5：修复

委托原则：自动流水线编排工作流，但将以下任务委托给对应技能：

BRD结构/内容规则 →
```
doc-brd
```
技能
实时质量反馈 →
```
quality-advisor
```
技能
BRD验证逻辑 →
```
doc-brd-validator
```
技能
内容评审与评分 →
```
doc-brd-reviewer
```
技能
问题解决与修复 →
```
doc-brd-fixer
```
技能
元素ID标准 →
```
doc-naming
```
技能

Smart Document Detection

智能文档检测

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

自动流水线根据输入文档类型自动确定操作。

Input Type Recognition (No Upstream - Layer 1)

输入类型识别（无上游 - 层级1）

BRD has no upstream document type. Smart detection works differently:

Input	Detected As	Action
`BRD-NN`	Self type	Review existing BRD document
`docs/00_REF/...`	Reference docs	Generate BRD from reference
`REF/...`	Reference docs	Generate BRD from reference
`--prompt "..."`	User prompt	Generate BRD from prompt

BRD没有上游文档类型，智能检测机制有所不同：

输入	识别为	操作
`BRD-NN`	自身类型	评审现有BRD文档
`docs/00_REF/...`	参考文档	从参考文档生成BRD
`REF/...`	参考文档	从参考文档生成BRD
`--prompt "..."`	用户提示	从用户提示生成BRD

Detection Algorithm

检测算法

1. Parse input: Determine input type
2. Determine action:
   - IF input matches "BRD-NN": Review Mode
   - ELSE IF input is a reference path: Generate Mode
   - ELSE IF input is --prompt: Generate Mode
   - ELSE: Error (invalid input for this autopilot)
3. For Review Mode:
   - Check: Does BRD-{NN} exist in docs/01_BRD/?
   - IF exists: Run doc-brd-reviewer on BRD-{NN}
   - ELSE: Error (BRD not found)

1. 解析输入：确定输入类型
2. 确定操作：
   - 如果输入匹配"BRD-NN"：评审模式
   - 否则如果输入是参考路径：生成模式
   - 否则如果输入是--prompt：生成模式
   - 否则：错误（该自动流水线不支持的输入）
3. 对于评审模式：
   - 检查：BRD-{NN}是否存在于docs/01_BRD/中？
   - 如果存在：对BRD-{NN}运行doc-brd-reviewer
   - 否则：错误（未找到BRD）

File Existence Check

文件存在性检查

bash

undefined

bash

undefined

Check for nested folder structure (mandatory)

检查嵌套文件夹结构（必填）

ls docs/01_BRD/BRD-{NN}_*/

undefined

ls docs/01_BRD/BRD-{NN}_*/

undefined

Examples

示例

bash

undefined

bash

undefined

Review mode (BRD input)

评审模式（BRD输入）

/doc-brd-autopilot BRD-01 # Reviews existing BRD-01

/doc-brd-autopilot BRD-01 # 评审现有BRD-01

Generate mode (reference input)

生成模式（参考输入）

/doc-brd-autopilot docs/00_REF/foundation/F1_IAM_Technical_Specification.md /doc-brd-autopilot all # Process all reference documents

/doc-brd-autopilot docs/00_REF/foundation/F1_IAM_Technical_Specification.md /doc-brd-autopilot all # 处理所有参考文档

Generate mode (prompt input)

生成模式（提示输入）

/doc-brd-autopilot --prompt "Create a BRD for user authentication system"

undefined

/doc-brd-autopilot --prompt "为用户认证系统创建BRD"

undefined

Action Determination Output

操作判定输出

Input: BRD-01
├── Detected Type: BRD (self)
├── BRD Exists: Yes → docs/01_BRD/BRD-01_f1_iam/
└── Action: REVIEW MODE - Running doc-brd-reviewer on BRD-01

Input: BRD-15
├── Detected Type: BRD (self)
├── BRD Exists: No
└── Action: ERROR - BRD-15 not found. Use reference docs or --prompt to generate.

Input: docs/00_REF/foundation/F1_IAM_Technical_Specification.md
├── Detected Type: Reference document
└── Action: GENERATE MODE - Creating BRD from reference specification

输入: BRD-01
├── 检测类型: BRD（自身）
├── BRD存在: 是 → docs/01_BRD/BRD-01_f1_iam/
└── 操作: 评审模式 - 对BRD-01运行doc-brd-reviewer

输入: BRD-15
├── 检测类型: BRD（自身）
├── BRD存在: 否
└── 操作: 错误 - 未找到BRD-15。请使用参考文档或--prompt生成。

输入: docs/00_REF/foundation/F1_IAM_Technical_Specification.md
├── 检测类型: 参考文档
└── 操作: 生成模式 - 从参考规范创建BRD

When to Use This Skill

何时使用该技能

Use
doc-brd-autopilot
when:

Starting a new project and need to create the initial BRD
Converting business requirements or strategy documents to formal BRD format
Creating multiple BRDs for a project (platform + feature BRDs)
Automating BRD generation in CI/CD pipelines
Ensuring consistent BRD quality across team members

Do NOT use when:

Manually reviewing an existing BRD (use
```
doc-brd-validator
```
)
Creating a simple single-section BRD (use
```
doc-brd
```
directly)
Editing specific BRD sections (use
```
doc-brd
```
for guidance)

当以下情况时使用
doc-brd-autopilot
:

启动新项目，需要创建初始BRD
将业务需求或战略文档转换为正式BRD格式
为项目创建多个BRD（平台型+功能型）
在CI/CD流水线中自动化BRD生成
确保团队成员之间BRD质量一致

请勿在以下情况使用:

手动评审现有BRD（使用
```
doc-brd-validator
```
）
创建简单的单章节BRD（直接使用
```
doc-brd
```
）
编辑BRD的特定章节（使用
```
doc-brd
```
获取指导）

Workflow Overview

工作流概述

mermaid

flowchart TD
    subgraph Phase1["Phase 1: Input Analysis"]
        A[Start] --> B[Read Strategy Documents]
        B --> C[Identify Stakeholder Requirements]
        C --> D[Extract Business Context]
        D --> E[Catalog Input Sources]
        E --> E1[Validate @ref Targets]
        E1 --> E2{All refs valid?}
        E2 -->|No| E3[Flag missing docs]
        E3 --> E4{Required doc?}
        E4 -->|Yes| E5[ABORT: Create missing doc first]
        E4 -->|No| E6[Continue with warning]
        E2 -->|Yes| E6
    end

    subgraph Phase2["Phase 2: BRD Type Determination"]
        E6 --> F[Run Platform vs Feature Questionnaire]
        F --> G{Platform BRD?}
        G -->|Yes| H[Configure Platform BRD Mode]
        G -->|No| I[Configure Feature BRD Mode]
        H --> J[Check for Platform BRD Dependencies]
        I --> K[Verify Platform BRD Exists]
        K -->|Missing| L[Queue Platform BRD First]
        L --> J
        K -->|Exists| J
    end

    subgraph Phase3["Phase 3: BRD Generation"]
        J --> M[Load BRD Template]
        M --> N[Generate Document Control]
        N --> O[Generate Core Sections 1-9]
        O --> O2[Generate Section 7.2: ADR Topics]
        O2 --> P[quality-advisor: Real-time Feedback]
        P --> Q[Generate Sections 10-18]
        Q --> Q2[Handle Master Glossary]
        Q2 --> Q3{Glossary exists?}
        Q3 -->|No| Q4[Create BRD-00_GLOSSARY.md]
        Q3 -->|Yes| Q5[Update path reference]
        Q4 --> Q5
        Q5 --> R[Add Traceability References]
        R --> S[Write BRD Files]
    end

    subgraph Phase4["Phase 4: BRD Validation"]
        S --> T[Run doc-brd-validator]
        T --> U{PRD-Ready >= 90?}
        U -->|No| V[Auto-Fix BRD Issues]
        V --> W[Re-validate BRD]
        W --> U
        U -->|Yes| X[Mark BRD Validated]
    end

    subgraph Phase5["Phase 5: Review & Fix Cycle"]
        X --> Y[Run doc-brd-reviewer]
        Y --> Y2{Score >= 90?}
        Y2 -->|No| Y3[Run doc-brd-fixer]
        Y3 --> Y4{Iteration < Max?}
        Y4 -->|Yes| Y
        Y4 -->|No| Y5[Flag Manual Review]
        Y2 -->|Yes| Z[Verify Quality Checks]
        Y5 --> Z
        Z --> AA[Generate PRD-Ready Report]
        AA --> AB[Update Traceability Matrix]
    end

    AB --> AC[Complete]

mermaid

flowchart TD
    subgraph Phase1["阶段1: 输入分析"]
        A[开始] --> B[读取战略文档]
        B --> C[识别干系人需求]
        C --> D[提取业务上下文]
        D --> E[编目输入来源]
        E --> E1[验证@ref目标]
        E1 --> E2{所有引用有效？}
        E2 -->|否| E3[标记缺失文档]
        E3 --> E4{是否为必填文档？}
        E4 -->|是| E5[终止：先创建缺失文档]
        E4 -->|否| E6[带警告继续]
        E2 -->|是| E6
    end

    subgraph Phase2["阶段2: BRD类型判定"]
        E6 --> F[运行平台型vs功能型问卷]
        F --> G{平台型BRD？}
        G -->|是| H[配置平台型BRD模式]
        G -->|否| I[配置功能型BRD模式]
        H --> J[检查平台型BRD依赖]
        I --> K[验证平台型BRD是否存在]
        K -->|缺失| L[优先排队平台型BRD]
        L --> J
        K -->|存在| J
    end

    subgraph Phase3["阶段3: BRD生成"]
        J --> M[加载BRD模板]
        M --> N[生成文档控制]
        N --> O[生成核心章节1-9]
        O --> O2[生成章节7.2: ADR主题]
        O2 --> P[quality-advisor: 实时反馈]
        P --> Q[生成章节10-18]
        Q --> Q2[处理主术语表]
        Q2 --> Q3{术语表存在？}
        Q3 -->|否| Q4[创建BRD-00_GLOSSARY.md]
        Q3 -->|是| Q5[更新路径引用]
        Q4 --> Q5
        Q5 --> R[添加可追溯性引用]
        R --> S[写入BRD文件]
    end

    subgraph Phase4["阶段4: BRD验证"]
        S --> T[运行doc-brd-validator]
        T --> U{PRD就绪分数≥90？}
        U -->|否| V[自动修复BRD问题]
        V --> W[重新验证BRD]
        W --> U
        U -->|是| X[标记BRD已验证]
    end

    subgraph Phase5["阶段5: 评审与修复循环"]
        X --> Y[运行doc-brd-reviewer]
        Y --> Y2{分数≥90？}
        Y2 -->|否| Y3[运行doc-brd-fixer]
        Y3 --> Y4{迭代次数<最大值？}
        Y4 -->|是| Y
        Y4 -->|否| Y5[标记为需要手动评审]
        Y2 -->|是| Z[验证质量检查]
        Y5 --> Z
        Z --> AA[生成PRD就绪报告]
        AA --> AB[更新可追溯性矩阵]
    end

    AB --> AC[完成]

Detailed Workflow

详细工作流

Phase 1: Input Analysis

阶段1: 输入分析

Analyze available input sources to extract business requirements.

Input Sources (priority order):

Priority	Source	Location	Content Type
1	Reference Documents	`docs/00_REF/`	Technical specs, gap analysis, architecture
2	Reference Documents (alt)	`REF/`	Alternative location for reference docs
3	Existing Documentation	`docs/` or `README.md`	Project context, scope
4	User Prompts	Interactive	Business context, objectives, constraints

Analysis Process:

bash

undefined

分析可用输入来源以提取业务需求。

输入来源（优先级顺序）:

优先级	来源	位置	内容类型
1	参考文档	`docs/00_REF/`	技术规范、差距分析、架构
2	参考文档（备选）	`REF/`	参考文档的备选位置
3	现有文档	`docs/` 或 `README.md`	项目上下文、范围
4	用户提示	交互式	业务上下文、目标、约束

分析流程:

bash

undefined

Check for reference documents (primary location)

检查参考文档（主位置）

ls -la docs/00_REF/

Alternative location

备选位置

ls -la REF/

Expected structure:

预期结构:

docs/00_REF/

├── foundation/ # Foundation module specs (F1-F7)

├── foundation/ # 基础模块规范（F1-F7）

│ ├── F1_IAM_Technical_Specification.md

│ ├── F2_Session_Technical_Specification.md

│ └── GAP_Foundation_Module_Gap_Analysis.md

├── domain/ # Domain module specs (D1-D7)

├── domain/ # 领域模块规范（D1-D7）

│ ├── D1_Agent_Technical_Specification.md

│ └── architecture/ # Architecture documents

│ └── architecture/ # 架构文档

└── external/ # External references

└── external/ # 外部引用


**Output**: Input catalog with extracted requirements, objectives, and constraints.


**输出**：包含提取的需求、目标和约束的输入编目。

1.1 Source Document Link Validation (NEW in v2.3)

1.1 源文档链接验证（v2.3新增）

Purpose: Validate that all referenced source documents exist before proceeding to generation. This prevents broken

@ref:

links in the generated BRD.

Validation Checks:

Check	Action	Severity
Reference documents exist	Verify files in `docs/00_REF/` or `REF/`	Error - blocks generation
`@ref:` targets in source docs	Verify referenced files exist	Error - blocks generation
Gap analysis documents	Verify `GAP_*.md` files if referenced	Warning - flag for creation
Cross-reference documents	Verify upstream docs exist	Warning - document dependency

Validation Process:

bash

undefined

用途：在生成开始前验证所有引用的源文档是否存在，防止生成的BRD中出现无效的

@ref:

链接。

验证检查:

检查	操作	严重程度
参考文档存在	验证 `docs/00_REF/` 或 `REF/` 中的文件	错误 - 阻止生成
源文档中的 `@ref:` 目标	验证引用的文件是否存在	错误 - 阻止生成
差距分析文档	如果被引用，验证 `GAP_*.md` 文件是否存在	警告 - 标记需要创建
交叉引用文档	验证上游文档是否存在	警告 - 记录依赖

验证流程:

bash

undefined

Check for referenced documents

检查引用的文档

grep -h "@ref:" docs/00_REF//*.md REF//.md 2>/dev/null |
grep -oP '[.?](([^)]+))' |
while read link; do file=$(echo "$link" | grep -oP '(([^)]+))' | tr -d '()') if [ ! -f "$file" ]; then echo "WARNING: Referenced file not found: $file" fi done


**Error Handling**:

| Scenario | Action |
|----------|--------|
| Required source doc missing | Abort with clear error message |
| Optional reference missing | Log warning, continue with placeholder note |
| Gap analysis doc missing | Prompt user: create doc or update references |

**Example Output**:

Phase 1: Input Analysis

Reference documents found: 5 ✅ docs/00_REF/foundation/F1_IAM_Technical_Specification.md ✅ docs/00_REF/foundation/F2_Session_Technical_Specification.md ✅ docs/00_REF/foundation/F3_Observability_Technical_Specification.md ✅ docs/00_REF/domain/D1_Agent_Technical_Specification.md ✅ docs/00_REF/GLOSSARY_Master.md

Reference Validation: ✅ docs/00_REF/foundation/F1_IAM_Technical_Specification.md ❌ docs/00_REF/foundation/GAP_Foundation_Module_Gap_Analysis.md (NOT FOUND)

ACTION REQUIRED: Create missing reference document or update source references.

undefined


**错误处理**:

| 场景 | 操作 |
|----------|--------|
| 缺失必填源文档 | 终止并显示清晰的错误消息 |
| 缺失可选引用 | 记录警告，使用占位符注释继续 |
| 缺失差距分析文档 | 提示用户：创建文档或更新引用 |

**示例输出**:

阶段1: 输入分析

找到参考文档: 5 ✅ docs/00_REF/foundation/F1_IAM_Technical_Specification.md ✅ docs/00_REF/foundation/F2_Session_Technical_Specification.md ✅ docs/00_REF/foundation/F3_Observability_Technical_Specification.md ✅ docs/00_REF/domain/D1_Agent_Technical_Specification.md ✅ docs/00_REF/GLOSSARY_Master.md

引用验证: ✅ docs/00_REF/foundation/F1_IAM_Technical_Specification.md ❌ docs/00_REF/foundation/GAP_Foundation_Module_Gap_Analysis.md（未找到）

需要操作: 创建缺失的参考文档或更新源引用。

undefined

Phase 2: BRD Type Determination

阶段2: BRD类型判定

Determine if creating a Platform BRD or Feature BRD.

Skill Delegation: This phase follows rules defined in
doc-brd
skill. See:
.claude/skills/doc-brd/SKILL.md
Section "BRD Categorization: Platform vs Feature"

Questionnaire (automated):

Question	Platform Indicator	Feature Indicator
Defines infrastructure/technology stack?	Yes	No
Describes specific user-facing workflow?	No	Yes
Other BRDs will depend on this?	Yes	No
Establishes patterns/standards for multiple features?	Yes	No
Implements functionality on existing platform?	No	Yes

Auto-Detection Logic:

python

def determine_brd_type(title: str, content: str) -> str:
    platform_keywords = ["Platform", "Architecture", "Infrastructure", "Integration", "Foundation"]
    feature_keywords = ["B2C", "B2B", "Workflow", "User", "Feature", "Module"]

    if any(kw in title for kw in platform_keywords):
        return "PLATFORM"
    if any(kw in title for kw in feature_keywords):
        return "FEATURE"
    if references_platform_brd(content):
        return "FEATURE"
    return "PLATFORM"  # Default to Platform for new projects

Feature BRD Dependency Check:

bash

undefined

确定要创建的是平台型BRD还是功能型BRD。

技能委托：该阶段遵循
doc-brd
技能中定义的规则。参见：
.claude/skills/doc-brd/SKILL.md
中的“BRD分类：平台型vs功能型”部分

问卷（自动化）:

问题	平台型指标	功能型指标
是否定义基础设施/技术栈？	是	否
是否描述特定的用户面向工作流？	否	是
其他BRD是否会依赖于此？	是	否
是否为多个功能建立模式/标准？	是	否
是否在现有平台上实现功能？	否	是

自动检测逻辑:

python

def determine_brd_type(title: str, content: str) -> str:
    platform_keywords = ["Platform", "Architecture", "Infrastructure", "Integration", "Foundation"]
    feature_keywords = ["B2C", "B2B", "Workflow", "User", "Feature", "Module"]

    if any(kw in title for kw in platform_keywords):
        return "PLATFORM"
    if any(kw in title for kw in feature_keywords):
        return "FEATURE"
    if references_platform_brd(content):
        return "FEATURE"
    return "PLATFORM"  # 新项目默认平台型

功能型BRD依赖检查:

bash

undefined

Verify Platform BRD exists before creating Feature BRD

在创建功能型BRD之前验证平台型BRD是否存在

ls docs/01_BRD/BRD-01_* 2>/dev/null || echo "ERROR: Platform BRD-01 required"

undefined

ls docs/01_BRD/BRD-01_* 2>/dev/null || echo "ERROR: 需要平台型BRD-01"

undefined

Phase 3: BRD Generation

阶段3: BRD生成

Generate the BRD document with real-time quality feedback.

Skill Delegation: This phase follows rules defined in
doc-brd
skill. See:
.claude/skills/doc-brd/SKILL.md
for complete BRD 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:

Reserve BRD ID:

bash

# Check for next available ID
ls docs/01_BRD/BRD-*.md docs/01_BRD/BRD-*/BRD-*.0_*.md 2>/dev/null | \
  grep -oP 'BRD-\K\d+' | sort -n | tail -1
# Increment for new BRD

Load BRD Template:

Primary:
```
ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md
```
Comprehensive:
```
ai_dev_flow/01_BRD/BRD-TEMPLATE.md
```

Generate Document Control Section:

Field	Value
Project Name	From input analysis
Document Version	0.1.0
Date Created	Current date (YYYY-MM-DD)
Last Updated	Current date (YYYY-MM-DD)
Document Owner	From stakeholder input
Prepared By	AI Assistant
Status	Draft
PRD-Ready Score	Calculated after generation

Generate Core Sections (1-9):
- Section 1: Executive Summary
- Section 2: Business Context
- Section 3: Stakeholder Analysis
- Section 4: Business Requirements (using BRD.NN.01.SS format)
- Section 5: Success Criteria
- Section 6: Constraints and Assumptions
- Section 7: Architecture Decision Requirements
- Section 8: Risk Assessment
- Section 9: Traceability

Generate Section 7.2: Architecture Decision Requirements:

7 Mandatory ADR Topic Categories (per

doc-brd

skill):

#	Category	Element ID	Fields Required
1	Infrastructure	BRD.NN.32.01	Status, Business Driver, Constraints, Alternatives, Cloud Comparison
2	Data Architecture	BRD.NN.32.02	Status, Business Driver, Constraints, Alternatives, Cloud Comparison
3	Integration	BRD.NN.32.03	Status, Business Driver, Constraints, Alternatives, Cloud Comparison
4	Security	BRD.NN.32.04	Status, Business Driver, Constraints, Alternatives, Cloud Comparison
5	Observability	BRD.NN.32.05	Status, Business Driver, Constraints, Alternatives, Cloud Comparison
6	AI/ML	BRD.NN.32.06	Status, Business Driver, Constraints, Alternatives, Cloud Comparison
7	Technology Selection	BRD.NN.32.07	Status, Business Driver, Constraints, Alternatives, Cloud Comparison

Status Values:

Selected

Pending

N/A

Required Tables (for Status=Selected):

Alternatives Overview table (Option | Function | Est. Monthly Cost | Selection Rationale)
Cloud Provider Comparison table (Criterion | GCP | Azure | AWS)

Real-Time Quality Feedback (via
```
quality-advisor
```
skill):
- Monitor section completion as content is generated
- Detect anti-patterns (AP-001 to AP-017) during creation
- Validate element ID format compliance (BRD.NN.TT.SS)
- Check for placeholder text ([TBD], TODO, XXX)
- Flag issues early to reduce post-generation rework
Generate Sections 10-18:
- Section 10: Market Context
- Section 11: Regulatory Compliance
- Section 12: Integration Requirements
- Section 13: Data Requirements
- Section 14: Performance Requirements
- Section 15: Security Requirements
- Section 16: Operational Requirements
- Section 17: Glossary
- Section 18: Appendices
Platform vs Feature Section Handling:

BRD Type Section 3.6 Section 3.7
Platform MUST populate with technology details MUST populate with conditions
Feature "N/A - See Platform BRD-NN Section 3.6" "N/A - See Platform BRD-NN Section 3.7"

BRD Type	Section 3.6	Section 3.7
Platform	MUST populate with technology details	MUST populate with conditions
Feature	"N/A - See Platform BRD-NN Section 3.6"	"N/A - See Platform BRD-NN Section 3.7"

Traceability References:

markdown

## 9. Traceability

### Upstream Sources
| Source | Type | Reference |
|--------|------|-----------|
| docs/00_REF/foundation/F1_Technical_Specification.md | Reference Document | Technical specifications |
| docs/00_REF/foundation/GAP_Analysis.md | Reference Document | Gap analysis |
| [Stakeholder] | Business Input | Initial requirements |

### Downstream Artifacts
| Artifact | Type | Status |
|----------|------|--------|
| PRD-NN | Product Requirements | Pending |
| ADR-NN | Architecture Decisions | Pending |

Master Glossary Handling (NEW in v2.3):

The BRD template references a master glossary. The autopilot MUST handle this reference correctly.

Glossary Check Process:

Scenario	Action
`docs/BRD-00_GLOSSARY.md` exists	Use correct relative path in Section 14
Glossary missing, first BRD	Create `docs/01_BRD/BRD-00_GLOSSARY.md` with template
Glossary missing, subsequent BRD	Reference existing glossary or create if missing

Glossary Creation Template:

markdown

---
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

| Term | Definition | Context |
|------|------------|---------|
| MVP | Minimum Viable Product | Scope definition |
| SLA | Service Level Agreement | Quality requirements |

## Technical Terms

| Term | Definition | Context |
|------|------------|---------|
| API | Application Programming Interface | Integration |
| JWT | JSON Web Token | Authentication |

## Domain Terms

[Add project-specific terminology here]

Section 14 Glossary Reference Format:

markdown

## 14. Glossary

📚 **Master Glossary**: For common terminology, see [BRD-00_GLOSSARY.md](../BRD-00_GLOSSARY.md)

### {BRD-NN}-Specific Terms

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

Path Resolution:

BRD Location	Glossary Path
`docs/01_BRD/BRD-01.md` (monolithic)	`BRD-00_GLOSSARY.md`
`docs/01_BRD/BRD-01_slug/BRD-01.3_*.md` (sectioned)	`../BRD-00_GLOSSARY.md`

BRD Index Handling (NEW in v2.4):

The autopilot MUST create or update

BRD-00_index.md

to serve as the master index for all BRD documents.

Index Check Process:

Scenario	Action
`docs/01_BRD/BRD-00_index.md` exists	Update with new BRD entry
Index missing	Create `docs/01_BRD/BRD-00_index.md` with template

BRD-00_index.md Creation Template:

markdown

---
title: "BRD-00: Business Requirements Document Index"
tags:
  - brd
  - index
  - layer-1-artifact
custom_fields:
  document_type: brd-index
  artifact_type: BRD-INDEX
  layer: 1
  last_updated: "YYYY-MM-DDTHH:MM:SS"
---

# BRD-00: Business Requirements Document Index

Master index of all Business Requirements Documents for the project.

---

## Document Registry

| BRD ID | Module | Type | Status | PRD-Ready | Location |
|--------|--------|------|--------|-----------|----------|
| BRD-01 | F1 IAM | Foundation | Draft | 97% | [BRD-01](BRD-01_f1_iam/BRD-01.0_index.md) |

---

## Module Categories

### Foundation Modules (F1-F7)

Domain-agnostic, reusable infrastructure modules.

| ID | Module Name | BRD | Status |
|----|-------------|-----|--------|
| F1 | Identity & Access Management | [BRD-01](BRD-01_f1_iam/BRD-01.0_index.md) | Draft |
| F2 | Session Management | Pending | - |
| F3 | Observability | Pending | - |
| F4 | SecOps | Pending | - |
| F5 | Events | Pending | - |
| F6 | Infrastructure | Pending | - |
| F7 | Configuration | Pending | - |

### Domain Modules (D1-D7)

Business-specific modules for cost monitoring.

| ID | Module Name | BRD | Status |
|----|-------------|-----|--------|
| D1 | Agent Orchestration | Pending | - |
| D2 | Cloud Accounts | Pending | - |
| D3 | Cost Analytics | Pending | - |
| D4 | Recommendations | Pending | - |
| D5 | Reporting | Pending | - |
| D6 | Alerting | Pending | - |
| D7 | Budgets | Pending | - |

---

## Quick Links

- **Glossary**: [BRD-00_GLOSSARY.md](BRD-00_GLOSSARY.md)
- **Reference Documents**: [00_REF](../00_REF/)
- **PRD Layer**: [02_PRD](../02_PRD/)

---

## Statistics

| Metric | Value |
|--------|-------|
| Total BRDs | 1 |
| Foundation Modules | 1/7 |
| Domain Modules | 0/7 |
| Average PRD-Ready Score | 97% |

---

*Last Updated: YYYY-MM-DDTHH:MM:SS*

Index Update Logic:

After generating each BRD:

Read existing
```
BRD-00_index.md
```
Parse Document Registry table
Add or update entry for new BRD
Update Statistics section
Update
```
last_updated
```
timestamp
Write updated index

Entry Format:

markdown

| BRD-NN | {Module Name} | {Foundation/Domain} | {Status} | {Score}% | [BRD-NN](BRD-NN_{slug}/BRD-NN.0_index.md) |

File Output (ALWAYS use nested folder):
- Monolithic (<20k tokens):
```
docs/01_BRD/BRD-NN_{slug}/BRD-NN_{slug}.md
```
- Sectioned (>=20k tokens):
```
docs/01_BRD/BRD-NN_{slug}/BRD-NN.0_index.md
```
  ,
```
BRD-NN.1_core.md
```
  , etc.
- Master Index (always):
```
docs/01_BRD/BRD-00_index.md
```
  (create or update)
Nested Folder Rule: ALL BRDs use nested folders (
```
BRD-NN_{slug}/
```
) regardless of size. This keeps companion files (review reports, fix reports, drift cache) organized with their parent document.

生成带有实时质量反馈的BRD文档。

技能委托：该阶段遵循
doc-brd
技能中定义的规则。参见：
.claude/skills/doc-brd/SKILL.md
获取完整的BRD创建指导。
质量指导：使用
quality-advisor
技能在生成期间提供实时反馈。参见：
.claude/skills/quality-advisor/SKILL.md
获取质量监控信息。

生成流程:

预留BRD ID:

bash

# 检查下一个可用ID
ls docs/01_BRD/BRD-*.md docs/01_BRD/BRD-*/BRD-*.0_*.md 2>/dev/null | \
  grep -oP 'BRD-\K\d+' | sort -n | tail -1
# 为新BRD递增ID

加载BRD模板:

基础版：
```
ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md
```
完整版：
```
ai_dev_flow/01_BRD/BRD-TEMPLATE.md
```

生成文档控制章节:

字段	值
项目名称	来自输入分析
文档版本	0.1.0
创建日期	当前日期（YYYY-MM-DD）
最后更新	当前日期（YYYY-MM-DD）
文档所有者	来自干系人输入
编制者	AI助手
状态	草稿
PRD就绪分数	生成后计算

生成核心章节（1-9）:
- 章节1：执行摘要
- 章节2：业务上下文
- 章节3：干系人分析
- 章节4：业务需求（使用BRD.NN.01.SS格式）
- 章节5：成功标准
- 章节6：约束与假设
- 章节7：架构决策需求
- 章节8：风险评估
- 章节9：可追溯性

生成章节7.2: 架构决策需求:

7个必填ADR主题类别（根据

doc-brd

技能）:

#	类别	元素ID	必填字段
1	基础设施	BRD.NN.32.01	状态、业务驱动因素、约束、备选方案、云供应商对比
2	数据架构	BRD.NN.32.02	状态、业务驱动因素、约束、备选方案、云供应商对比
3	集成	BRD.NN.32.03	状态、业务驱动因素、约束、备选方案、云供应商对比
4	安全	BRD.NN.32.04	状态、业务驱动因素、约束、备选方案、云供应商对比
5	可观测性	BRD.NN.32.05	状态、业务驱动因素、约束、备选方案、云供应商对比
6	AI/ML	BRD.NN.32.06	状态、业务驱动因素、约束、备选方案、云供应商对比
7	技术选型	BRD.NN.32.07	状态、业务驱动因素、约束、备选方案、云供应商对比

状态值：

Selected

（已选）,

Pending

（待处理）,

N/A

（不适用）

必填表格（当状态=Selected时）:

备选方案概述表（选项 | 功能 | 预计月度成本 | 选型理由）
云供应商对比表（标准 | GCP | Azure | AWS）

实时质量反馈（通过
```
quality-advisor
```
技能）:
- 在内容生成时监控章节完成情况
- 在创建期间检测反模式（AP-001至AP-017）
- 验证元素ID格式合规性（BRD.NN.TT.SS）
- 检查占位符文本（[TBD], TODO, XXX）
- 提前标记问题以减少生成后的返工
生成章节10-18:
- 章节10：市场上下文
- 章节11：合规要求
- 章节12：集成要求
- 章节13：数据要求
- 章节14：性能要求
- 章节15：安全要求
- 章节16：运维要求
- 章节17：术语表
- 章节18：附录
平台型vs功能型章节处理:

BRD类型章节3.6 章节3.7
平台型必须填充技术细节必须填充条件
功能型 "不适用 - 参见平台型BRD-NN章节3.6" "不适用 - 参见平台型BRD-NN章节3.7"

BRD类型	章节3.6	章节3.7
平台型	必须填充技术细节	必须填充条件
功能型	"不适用 - 参见平台型BRD-NN章节3.6"	"不适用 - 参见平台型BRD-NN章节3.7"

可追溯性引用:

markdown

## 9. 可追溯性

### 上游来源
| 来源 | 类型 | 引用 |
|--------|------|-----------|
| docs/00_REF/foundation/F1_Technical_Specification.md | 参考文档 | 技术规范 |
| docs/00_REF/foundation/GAP_Analysis.md | 参考文档 | 差距分析 |
| [干系人] | 业务输入 | 初始需求 |

### 下游工件
| 工件 | 类型 | 状态 |
|----------|------|--------|
| PRD-NN | 产品需求 | 待处理 |
| ADR-NN | 架构决策 | 待处理 |

主术语表处理（v2.3新增）:

BRD模板引用主术语表，自动流水线必须正确处理此引用。

术语表检查流程:

场景	操作
`docs/BRD-00_GLOSSARY.md` 存在	在章节14中使用正确的相对路径
术语表缺失，且是第一个BRD	使用模板创建 `docs/01_BRD/BRD-00_GLOSSARY.md`
术语表缺失，且不是第一个BRD	引用现有术语表或在缺失时创建

术语表创建模板:

markdown

---
title: "BRD-00: 主术语表"
tags:
  - brd
  - glossary
  - reference
custom_fields:
  document_type: glossary
  artifact_type: BRD-REFERENCE
  layer: 1
---

# BRD-00: 主术语表

所有业务需求文档中使用的通用术语。

## 业务术语

| 术语 | 定义 | 上下文 |
|------|------------|---------|
| MVP | 最小可行产品 | 范围定义 |
| SLA | 服务水平协议 | 质量要求 |

## 技术术语

| 术语 | 定义 | 上下文 |
|------|------------|---------|
| API | 应用程序编程接口 | 集成 |
| JWT | JSON Web令牌 | 认证 |

## 领域术语

[在此添加项目特定术语]

章节14术语表引用格式:

markdown

## 14. 术语表

📚 **主术语表**：通用术语请参见[BRD-00_GLOSSARY.md](../BRD-00_GLOSSARY.md)

### {BRD-NN}特定术语

| 术语 | 定义 | 上下文 |
|------|------------|---------|
| [术语1] | [定义] | [使用位置] |

路径解析:

BRD位置	术语表路径
`docs/01_BRD/BRD-01.md` （单文件）	`BRD-00_GLOSSARY.md`
`docs/01_BRD/BRD-01_slug/BRD-01.3_*.md` （分章节）	`../BRD-00_GLOSSARY.md`

BRD索引处理（v2.4新增）:

自动流水线必须创建或更新

BRD-00_index.md

作为所有BRD文档的主索引。

索引检查流程:

场景	操作
`docs/01_BRD/BRD-00_index.md` 存在	更新新BRD条目
索引缺失	使用模板创建 `docs/01_BRD/BRD-00_index.md`

BRD-00_index.md创建模板:

markdown

---
title: "BRD-00: 业务需求文档索引"
tags:
  - brd
  - index
  - layer-1-artifact
custom_fields:
  document_type: brd-index
  artifact_type: BRD-INDEX
  layer: 1
  last_updated: "YYYY-MM-DDTHH:MM:SS"
---

# BRD-00: 业务需求文档索引

项目所有业务需求文档的主索引。

---

## 文档注册表

| BRD ID | 模块 | 类型 | 状态 | PRD就绪 | 位置 |
|--------|--------|------|--------|-----------|----------|
| BRD-01 | F1 IAM | 基础 | 草稿 | 97% | [BRD-01](BRD-01_f1_iam/BRD-01.0_index.md) |

---

## 模块分类

### 基础模块（F1-F7）

领域无关的可重用基础设施模块。

| ID | 模块名称 | BRD | 状态 |
|----|-------------|-----|--------|
| F1 | 身份与访问管理 | [BRD-01](BRD-01_f1_iam/BRD-01.0_index.md) | 草稿 |
| F2 | 会话管理 | 待处理 | - |
| F3 | 可观测性 | 待处理 | - |
| F4 | 安全运维 | 待处理 | - |
| F5 | 事件 | 待处理 | - |
| F6 | 基础设施 | 待处理 | - |
| F7 | 配置 | 待处理 | - |

### 领域模块（D1-D7）

用于成本监控的业务特定模块。

| ID | 模块名称 | BRD | 状态 |
|----|-------------|-----|--------|
| D1 | Agent编排 | 待处理 | - |
| D2 | 云账户 | 待处理 | - |
| D3 | 成本分析 | 待处理 | - |
| D4 | 建议 | 待处理 | - |
| D5 | 报告 | 待处理 | - |
| D6 | 告警 | 待处理 | - |
| D7 | 预算 | 待处理 | - |

---

## 快速链接

- **术语表**: [BRD-00_GLOSSARY.md](BRD-00_GLOSSARY.md)
- **参考文档**: [00_REF](../00_REF/)
- **PRD层级**: [02_PRD](../02_PRD/)

---

## 统计信息

| 指标 | 值 |
|--------|-------|
| 总BRD数量 | 1 |
| 基础模块 | 1/7 |
| 领域模块 | 0/7 |
| 平均PRD就绪分数 | 97% |

---

*最后更新: YYYY-MM-DDTHH:MM:SS*

索引更新逻辑:

生成每个BRD后:

读取现有
```
BRD-00_index.md
```
解析文档注册表
添加或更新新BRD的条目
更新统计信息章节
更新
```
last_updated
```
时间戳
写入更新后的索引

条目格式:

markdown

| BRD-NN | {模块名称} | {基础/领域} | {状态} | {分数}% | [BRD-NN](BRD-NN_{slug}/BRD-NN.0_index.md) |

文件输出（必须使用嵌套文件夹）:
- 单文件（<20k tokens）:
```
docs/01_BRD/BRD-NN_{slug}/BRD-NN_{slug}.md
```
- 分章节（≥20k tokens）:
```
docs/01_BRD/BRD-NN_{slug}/BRD-NN.0_index.md
```
  ,
```
BRD-NN.1_core.md
```
  等
- 主索引（始终生成）:
```
docs/01_BRD/BRD-00_index.md
```
  （创建或更新）
嵌套文件夹规则：所有BRD无论大小都使用嵌套文件夹（
```
BRD-NN_{slug}/
```
），这使得配套文件（评审报告、修复报告、漂移缓存）与父文档保持组织一致。

Phase 4: BRD Validation

阶段4: BRD验证

After BRD generation, validate structure and PRD-Ready score.

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

Validation Command:

bash

python ai_dev_flow/scripts/validate_brd.py docs/01_BRD/BRD-NN_{slug}.md --verbose

Validation Checks:

Check	Requirement	Error Code
YAML Frontmatter	Valid metadata fields	BRD-E001 to BRD-E005
Section Structure	18 required sections	BRD-E006 to BRD-E008
Document Control	All required fields	BRD-E009
Business Objectives	BRD.NN.23.SS format	BRD-W001
Business Requirements	BRD.NN.01.SS format	BRD-W002
Section 7.2 ADR Topics	All 7 categories present	BRD-E013 to BRD-E018
Element ID Format	BRD.NN.TT.SS (4-segment)	BRD-E019 to BRD-E021
PRD-Ready Score	>= 90%	BRD-W004

Auto-Fix Actions:

Issue	Auto-Fix Action
Invalid element ID format	Convert to BRD.NN.TT.SS format
Missing traceability section	Insert from template
Missing Document Control fields	Add placeholder fields
Deprecated ID patterns (BO-XXX, FR-XXX)	Convert to unified format
Missing PRD-Ready Score	Calculate and insert

Validation Loop:

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

BRD生成后，验证结构和PRD就绪分数。

技能委托：该阶段使用
doc-brd-validator
技能中的验证规则。参见：
.claude/skills/doc-brd-validator/SKILL.md
获取完整的验证规则。

验证命令:

bash

python ai_dev_flow/scripts/validate_brd.py docs/01_BRD/BRD-NN_{slug}.md --verbose

验证检查:

检查	要求	错误代码
YAML前置元数据	有效的元数字段	BRD-E001至BRD-E005
章节结构	18个必填章节	BRD-E006至BRD-E008
文档控制	所有必填字段	BRD-E009
业务目标	BRD.NN.23.SS格式	BRD-W001
业务需求	BRD.NN.01.SS格式	BRD-W002
章节7.2 ADR主题	所有7个类别存在	BRD-E013至BRD-E018
元素ID格式	BRD.NN.TT.SS（4段式）	BRD-E019至BRD-E021
PRD就绪分数	≥90%	BRD-W004

自动修复操作:

问题	自动修复操作
无效元素ID格式	转换为BRD.NN.TT.SS格式
缺失可追溯性章节	从模板插入
缺失文档控制字段	添加占位符字段
已废弃的ID模式（BO-XXX, FR-XXX）	转换为统一格式
缺失PRD就绪分数	计算并插入

验证循环:

循环（最多3次迭代）:
  1. 运行doc-brd-validator
  2. 如果发现错误：应用自动修复
  3. 如果发现警告：评审并处理关键问题
  4. 如果PRD就绪分数<90%：增强章节
  5. 如果无问题：标记为已验证，继续
  6. 如果达到最大迭代次数：记录问题，标记为需要手动评审

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

阶段5: 评审与修复循环（v2.3）

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

mermaid

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

迭代式评审与修复循环，确保完成前BRD的质量。

mermaid

flowchart TD
    A[阶段5开始] --> B[运行doc-brd-reviewer]
    B --> C[生成评审报告]
    C --> D{评审分数≥90？}

    D -->|是| E[通过 - 进入阶段6]
    D -->|否| F{迭代次数<最大值？}

    F -->|是| G[运行doc-brd-fixer]
    G --> H[应用修复]
    H --> I[生成修复报告]
    I --> J[递增迭代次数]
    J --> B

    F -->|否| K[标记为需要手动评审]
    K --> L[生成包含剩余问题的最终报告]
    L --> E

5.1 Initial Review

5.1 初始评审

Run

doc-brd-reviewer

to identify issues.

bash

/doc-brd-reviewer BRD-NN

Output:

BRD-NN.R_review_report_v001.md

运行

doc-brd-reviewer

识别问题。

bash

/doc-brd-reviewer BRD-NN

输出：

BRD-NN.R_review_report_v001.md

5.2 Fix Cycle

5.2 修复循环

If review score < 90%, invoke

doc-brd-fixer

bash

/doc-brd-fixer BRD-NN --revalidate

Fix Categories:

Category	Fixes Applied
Missing Files	Create glossary, GAP placeholders, reference docs
Broken Links	Update paths, create targets
Element IDs	Convert legacy patterns, fix invalid type codes
Content	Replace template placeholders, dates
References	Update traceability tags

Output:

BRD-NN.F_fix_report_v001.md

如果评审分数<90%，调用

doc-brd-fixer

。

bash

/doc-brd-fixer BRD-NN --revalidate

修复类别:

类别	应用的修复
缺失文件	创建术语表、GAP占位符、参考文档
无效链接	更新路径、创建目标
元素ID	转换遗留模式、修复无效类型代码
内容	替换模板占位符、日期
引用	更新可追溯性标签

输出：

BRD-NN.F_fix_report_v001.md

5.3 Re-Review

5.3 重新评审

After fixes, automatically re-run reviewer.

bash

/doc-brd-reviewer BRD-NN

Output:

BRD-NN.R_review_report_v002.md

修复后自动重新运行评审。

bash

/doc-brd-reviewer BRD-NN

输出：

BRD-NN.R_review_report_v002.md

5.4 Iteration Control

5.4 迭代控制

Parameter	Default	Description
`max_iterations`	3	Maximum fix-review cycles
`target_score`	90	Minimum passing score
`stop_on_manual`	false	Stop if only manual issues remain

Iteration Example:

Iteration 1:
  Review v001: Score 85 (2 errors, 4 warnings)
  Fix v001: Fixed 5 issues, created 2 files

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

参数	默认值	描述
`max_iterations`	3	最大修复-评审循环次数
`target_score`	90	最低通过分数
`stop_on_manual`	false	如果仅剩余手动问题则停止

迭代示例:

迭代1:
  评审v001: 分数85（2个错误，4个警告）
  修复v001: 修复5个问题，创建2个文件

迭代2:
  评审v002: 分数94（0个错误，2个警告）
  状态: 通过（分数≥90）

5.5 Quality Checks (Post-Fix)

5.5 质量检查（修复后）

After passing the fix cycle:

Section Completeness:
- All 18 sections present and populated
- No placeholder text remaining ([TBD], TODO, XXX)
- Minimum content length per section
ADR Topics Coverage:
- All 7 mandatory categories addressed
- Selected topics have Alternatives Overview table
- Selected topics have Cloud Provider Comparison table
- N/A topics have explicit reasons
Element ID Compliance (per
```
doc-naming
```
skill):
- All IDs use BRD.NN.TT.SS format
- Element type codes valid for BRD (01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 22, 23, 24, 32, 33)
- No legacy patterns (BO-XXX, FR-XXX, AC-XXX, BC-XXX)

PRD-Ready Report:

PRD-Ready Score Breakdown
=========================
Business Objectives:    15/15 (BRD.NN.23.SS format)
Requirements Complete:  20/20 (BRD.NN.01.SS format)
Success Metrics:        10/10 (quantifiable)
Constraints Defined:    10/10 (documented)
Stakeholder Analysis:   10/10 (complete)
Risk Assessment:        10/10 (identified)
Traceability:           10/10 (sources cited)
ADR Topics:             15/15 (all 7 categories)
----------------------------
Total PRD-Ready Score:  100/100 (Target: >= 90)
Status: READY FOR PRD GENERATION

Traceability Matrix Update:

bash

# Update BRD-00_TRACEABILITY_MATRIX.md
python ai_dev_flow/scripts/update_traceability_matrix.py \
  --brd docs/01_BRD/BRD-NN_{slug}.md \
  --matrix docs/01_BRD/BRD-00_TRACEABILITY_MATRIX.md

通过修复循环后:

章节完整性:
- 所有18个章节存在并已填充
- 无剩余占位符文本（[TBD], TODO, XXX）
- 每个章节达到最小内容长度
ADR主题覆盖:
- 所有7个必填类别已处理
- 已选主题包含备选方案概述表
- 已选主题包含云供应商对比表
- 不适用的主题有明确理由
元素ID合规性（根据
```
doc-naming
```
技能）:
- 所有ID使用BRD.NN.TT.SS格式
- 元素类型代码对BRD有效（01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 22, 23, 24, 32, 33）
- 无遗留模式（BO-XXX, FR-XXX, AC-XXX, BC-XXX）

PRD就绪报告:

PRD就绪分数明细
=========================
业务目标:    15/15（BRD.NN.23.SS格式）
需求完整性:  20/20（BRD.NN.01.SS格式）
成功指标:        10/10（可量化）
约束定义:    10/10（已记录）
干系人分析:   10/10（完整）
风险评估:        10/10（已识别）
可追溯性:           10/10（已引用来源）
ADR主题:             15/15（所有7个类别）
----------------------------
总PRD就绪分数:  100/100（目标: ≥90）
状态: 已准备好生成PRD

可追溯性矩阵更新:

bash

# 更新BRD-00_TRACEABILITY_MATRIX.md
python ai_dev_flow/scripts/update_traceability_matrix.py \
  --brd docs/01_BRD/BRD-NN_{slug}.md \
  --matrix docs/01_BRD/BRD-00_TRACEABILITY_MATRIX.md

Execution Modes

执行模式

Single BRD Mode

单BRD模式

Generate one BRD from input sources.

bash

undefined

从输入源生成一个BRD。

bash

undefined

Example: Generate Platform BRD from reference documents

示例：从参考文档生成平台型BRD

python ai_dev_flow/scripts/brd_autopilot.py
--ref docs/00_REF/
--type platform
--output docs/01_BRD/
--id 01
--slug platform_architecture

Alternative: Generate from REF/ directory

备选：从REF/目录生成

python ai_dev_flow/scripts/brd_autopilot.py
--ref REF/
--type platform
--output docs/01_BRD/
--id 01
--slug platform_architecture

undefined

python ai_dev_flow/scripts/brd_autopilot.py
--ref REF/
--type platform
--output docs/01_BRD/
--id 01
--slug platform_architecture

undefined

Batch Mode

批量模式

Generate multiple BRDs in sequence with dependency awareness.

bash

undefined

按顺序生成多个BRD，支持依赖感知。

bash

undefined

Example: Generate Platform BRD then Feature BRDs

示例：先生成平台型BRD，再生成功能型BRD

python ai_dev_flow/scripts/brd_autopilot.py
--batch config/brd_batch.yaml
--output docs/01_BRD/


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

```yaml
brds:
  - id: "01"
    slug: "f1_iam"
    type: "platform"
    priority: 1
    sources:
      - docs/00_REF/foundation/F1_IAM_Technical_Specification.md
      - docs/00_REF/foundation/GAP_Foundation_Module_Gap_Analysis.md

  - id: "02"
    slug: "f2_session"
    type: "platform"
    priority: 1
    sources:
      - docs/00_REF/foundation/F2_Session_Technical_Specification.md

  - id: "03"
    slug: "f3_observability"
    type: "platform"
    priority: 1
    sources:
      - docs/00_REF/foundation/F3_Observability_Technical_Specification.md

execution:
  parallel: true
  max_parallel: 3        # HARD LIMIT - do not exceed
  chunk_size: 3          # Documents per chunk
  pause_between_chunks: true
  max_workers: 2
  fail_fast: false

python ai_dev_flow/scripts/brd_autopilot.py
--batch config/brd_batch.yaml
--output docs/01_BRD/


**批量配置**（`config/brd_batch.yaml`）:

```yaml
brds:
  - id: "01"
    slug: "f1_iam"
    type: "platform"
    priority: 1
    sources:
      - docs/00_REF/foundation/F1_IAM_Technical_Specification.md
      - docs/00_REF/foundation/GAP_Foundation_Module_Gap_Analysis.md

  - id: "02"
    slug: "f2_session"
    type: "platform"
    priority: 1
    sources:
      - docs/00_REF/foundation/F2_Session_Technical_Specification.md

  - id: "03"
    slug: "f3_observability"
    type: "platform"
    priority: 1
    sources:
      - docs/00_REF/foundation/F3_Observability_Technical_Specification.md

execution:
  parallel: true
  max_parallel: 3        # 硬限制 - 不要超过
  chunk_size: 3          # 每个批次的文档数量
  pause_between_chunks: true
  max_workers: 2
  fail_fast: false

Dry Run Mode

试运行模式

Preview execution plan without generating files.

bash

python ai_dev_flow/scripts/brd_autopilot.py \
  --ref docs/00_REF/ \
  --output docs/01_BRD/ \
  --dry-run

预览执行计划但不生成文件。

bash

python ai_dev_flow/scripts/brd_autopilot.py \
  --ref docs/00_REF/ \
  --output docs/01_BRD/ \
  --dry-run

Review Mode (v2.1)

评审模式（v2.1）

Validate existing BRD documents and generate a quality report without modification.

Purpose: Audit existing BRD documents for compliance, quality scores, and identify issues.

Command:

bash

undefined

验证现有BRD文档并生成质量报告，不进行修改。

用途：审计现有BRD文档的合规性、质量分数并识别问题。

命令:

bash

undefined

Review single BRD

评审单个BRD

python ai_dev_flow/scripts/brd_autopilot.py
--brd docs/01_BRD/BRD-01_platform.md
--mode review

Review all BRDs

评审所有BRD

python ai_dev_flow/scripts/brd_autopilot.py
--brd docs/01_BRD/
--mode review
--output-report tmp/brd_review_report.md


**Review Process**:

```mermaid
flowchart TD
    A[Input: Existing BRD] --> B[Load BRD Documents]
    B --> C[Run Validation Checks]
    C --> D[Calculate PRD-Ready Score]
    D --> E[Check Section 7.2 ADR Topics]
    E --> F[Validate Platform vs Feature]
    F --> G[Identify Issues]
    G --> H{Generate Report}
    H --> I[Fixable Issues List]
    H --> J[Manual Review Items]
    H --> K[Score Breakdown]
    I --> L[Output: Review Report]
    J --> L
    K --> L

Review Report Structure:

markdown

undefined

python ai_dev_flow/scripts/brd_autopilot.py
--brd docs/01_BRD/
--mode review
--output-report tmp/brd_review_report.md


**评审流程**:

```mermaid
flowchart TD
    A[输入: 现有BRD] --> B[加载BRD文档]
    B --> C[运行验证检查]
    C --> D[计算PRD就绪分数]
    D --> E[检查章节7.2 ADR主题]
    E --> F[验证平台型vs功能型]
    F --> G[识别问题]
    G --> H{生成报告}
    H --> I[可自动修复问题列表]
    H --> J[需要手动评审的项目]
    H --> K[分数明细]
    I --> L[输出: 评审报告]
    J --> L
    K --> L

评审报告结构:

markdown

undefined

BRD Review Report: BRD-01_platform

BRD评审报告: BRD-01_platform

Summary

摘要

PRD-Ready Score: 87% 🟡
Total Issues: 14
Auto-Fixable: 10
Manual Review: 4

PRD就绪分数: 87% 🟡
总问题数: 14
可自动修复: 10
需要手动评审: 4

Score Breakdown

分数明细

Category	Score	Status
Business Objectives	14/15	🟡
Requirements Complete	18/20	🟡
Success Metrics	10/10	✅
Constraints Defined	10/10	✅
Stakeholder Analysis	10/10	✅
Risk Assessment	8/10	🟡
Traceability	10/10	✅
ADR Topics	12/15	🟡

类别	分数	状态
业务目标	14/15	🟡
需求完整性	18/20	🟡
成功指标	10/10	✅
约束定义	10/10	✅
干系人分析	10/10	✅
风险评估	8/10	🟡
可追溯性	10/10	✅
ADR主题	12/15	🟡

Section 7.2 ADR Topics Check

章节7.2 ADR主题检查

Category	Status	Details
Infrastructure	✅	Complete with tables
Data Architecture	✅	Complete with tables
Integration	🟡	Missing Cloud Comparison
Security	✅	Complete with tables
Observability	❌	Missing alternatives table
AI/ML	✅	Complete with tables
Technology Selection	✅	Complete with tables

类别	状态	详情
基础设施	✅	包含表格
数据架构	✅	包含表格
集成	🟡	缺失云供应商对比
安全	✅	包含表格
可观测性	❌	缺失备选方案表
AI/ML	✅	包含表格
技术选型	✅	包含表格

Platform vs Feature Check

平台型vs功能型检查

Check	Status	Details
BRD Type	Platform	Correctly identified
Section 3.6	✅	Technology details present
Section 3.7	✅	Conditions populated
Cross-references	✅	Valid references

检查	状态	详情
BRD类型	平台型	识别正确
章节3.6	✅	包含技术细节
章节3.7	✅	已填充条件
交叉引用	✅	引用有效

Auto-Fixable Issues

可自动修复问题

#	Issue	Location	Fix Action
1	Legacy element ID	Section 4:L45	Convert BO-001 to BRD.01.23.01
2	Missing PRD-Ready score	Document Control	Calculate and insert
3	Invalid ID format	Section 5:L78	Convert FR-001 to BRD.01.01.01
...	...	...	...

#	问题	位置	修复操作
1	遗留元素ID	章节4:L45	将BO-001转换为BRD.01.23.01
2	缺失PRD就绪分数	文档控制	计算并插入
3	无效ID格式	章节5:L78	将FR-001转换为BRD.01.01.01
...	...	...	...

Manual Review Required

需要手动评审

#	Issue	Location	Reason
1	Incomplete risk assessment	Section 8:L102	Domain knowledge needed
2	Missing Observability tables	Section 7.2.5	Architecture decision required
...	...	...	...

#	问题	位置	原因
1	风险评估不完整	章节8:L102	需要领域知识
2	缺失可观测性表格	章节7.2.5	需要架构决策
...	...	...	...

Recommendations

建议

Run fix mode to address 10 auto-fixable issues
Complete Observability ADR topic tables
Review and complete risk assessment section


**Review Configuration**:

```yaml
review_mode:
  enabled: true
  checks:
    - structure_validation      # 18 sections, Document Control
    - element_id_compliance     # BRD.NN.TT.SS format
    - adr_topics_validation     # 7 ADR categories in Section 7.2
    - platform_feature_check    # Correct section handling
    - cumulative_tags           # Traceability references
    - score_calculation         # PRD-Ready score
  output:
    format: markdown           # markdown, json, html
    include_line_numbers: true
    include_fix_suggestions: true
  thresholds:
    pass: 90
    warning: 85
    fail: 0

运行修复模式处理10个可自动修复问题
完成可观测性ADR主题表格
评审并完成风险评估章节


**评审配置**:

```yaml
review_mode:
  enabled: true
  checks:
    - structure_validation      # 18个章节，文档控制
    - element_id_compliance     # BRD.NN.TT.SS格式
    - adr_topics_validation     # 章节7.2中的7个ADR类别
    - platform_feature_check    # 正确的章节处理
    - cumulative_tags           # 可追溯性引用
    - score_calculation         # PRD就绪分数
  output:
    format: markdown           # markdown, json, html
    include_line_numbers: true
    include_fix_suggestions: true
  thresholds:
    pass: 90
    warning: 85
    fail: 0

Fix Mode (v2.1)

修复模式（v2.1）

Auto-repair existing BRD documents while preserving manual content.

Purpose: Apply automated fixes to BRD documents to improve quality scores and compliance.

Command:

bash

undefined

自动修复现有BRD文档，同时保留手动内容。

用途：对BRD文档应用自动修复以提高质量分数和合规性。

命令:

bash

undefined

Fix single BRD

修复单个BRD

python ai_dev_flow/scripts/brd_autopilot.py
--brd docs/01_BRD/BRD-01_platform.md
--mode fix

Fix with backup

修复并备份

python ai_dev_flow/scripts/brd_autopilot.py
--brd docs/01_BRD/BRD-01_platform.md
--mode fix
--backup

Fix specific issue types only

仅修复特定类型的问题

python ai_dev_flow/scripts/brd_autopilot.py
--brd docs/01_BRD/BRD-01_platform.md
--mode fix
--fix-types "element_ids,sections,adr_topics"

Dry-run fix (preview changes)

试运行修复（预览更改）

python ai_dev_flow/scripts/brd_autopilot.py
--brd docs/01_BRD/BRD-01_platform.md
--mode fix
--dry-run


**Fix Process**:

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

    subgraph FixCategories["Fix Categories"]
        G --> H[Element ID Fixes]
        G --> I[Section Fixes]
        G --> J[ADR Topics Fixes]
        G --> K[Traceability Fixes]
        G --> L[Score Fixes]
    end

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

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

Fix Categories and Actions:

Category	Issue	Auto-Fix Action	Preserves Content
Element IDs	Legacy BO-XXX format	Convert to BRD.NN.23.SS	✅
Element IDs	Legacy FR-XXX format	Convert to BRD.NN.01.SS	✅
Element IDs	Legacy AC-XXX format	Convert to BRD.NN.06.SS	✅
Element IDs	Legacy BC-XXX format	Convert to BRD.NN.09.SS	✅
Element IDs	Invalid type code for BRD	Suggest correct code (e.g., 25→33 for Benefits)	✅
Sections	Missing Document Control fields	Add from template	✅
Sections	Missing traceability section	Insert from template	✅
Sections	Missing PRD-Ready score	Calculate and insert	✅
ADR Topics	Missing category	Add template entry	✅
ADR Topics	Missing Alternatives table	Add table template	✅
ADR Topics	Missing Cloud Comparison table	Add table template	✅
Traceability	Missing upstream sources	Add template structure	✅
Traceability	Missing downstream artifacts	Add template structure	✅
Score	Missing PRD-Ready breakdown	Calculate and add	✅
Broken Links	Missing glossary file	Create BRD-00_GLOSSARY.md	✅
Broken Links	Missing reference doc	Prompt to create or update link	⚠️
Broken Links	Invalid relative path	Fix path based on BRD location	✅

Content Preservation Rules:

Never delete existing business requirements
Never modify executive summary content
Never change stakeholder analysis details
Only add missing sections and metadata
Only replace legacy element IDs with unified format
Backup first if
```
--backup
```
flag is set

Element ID Migration:

Legacy Pattern	New Format	Example
`BO-XXX`	`BRD.NN.23.SS`	BO-001 → BRD.01.23.01
`FR-XXX`	`BRD.NN.01.SS`	FR-001 → BRD.01.01.01
`AC-XXX`	`BRD.NN.06.SS`	AC-001 → BRD.01.06.01
`BC-XXX`	`BRD.NN.09.SS`	BC-001 → BRD.01.09.01
`ADR-T-XXX`	`BRD.NN.32.SS`	ADR-T-001 → BRD.01.32.01

Element Type Code Migration (v2.3):

Invalid Code	Correct Code	Context	Example
25 in BRD	33	Benefits section	BRD.01.25.01 → BRD.01.33.01

Note: Code 25 is valid only for EARS documents (EARS Statement). For BRD Benefits, use code 33 (Benefit Statement).

Broken Link Fixes (v2.3):

Issue	Fix Action	Creates File
Missing `BRD-00_GLOSSARY.md`	Create from template	✅ Yes
Missing reference doc (GAP, REF)	Prompt user with options: (1) Create placeholder, (2) Update link, (3) Remove reference	⚠️ Optional
Wrong relative path	Recalculate path based on BRD location	❌ No
Cross-BRD reference to non-existent BRD	Log warning, suggest creating BRD	❌ No

Fix Report Structure:

markdown

undefined

python ai_dev_flow/scripts/brd_autopilot.py
--brd docs/01_BRD/BRD-01_platform.md
--mode fix
--dry-run


**修复流程**:

```mermaid
flowchart TD
    A[输入: 现有BRD] --> B[运行评审模式]
    B --> C[识别可修复问题]
    C --> D{已启用备份？}
    D -->|是| E[创建备份]
    D -->|否| F[跳过备份]
    E --> G[按类别应用修复]
    F --> G

    subgraph FixCategories["修复类别"]
        G --> H[元素ID修复]
        G --> I[章节修复]
        G --> J[ADR主题修复]
        G --> K[可追溯性修复]
        G --> L[分数修复]
    end

    H --> M[保留手动内容]
    I --> M
    J --> M
    K --> M
    L --> M

    M --> N[重新验证]
    N --> O{分数已提升？}
    O -->|是| P[生成修复报告]
    O -->|否| Q[记录警告]
    Q --> P
    P --> R[输出: 修复后的BRD + 报告]

修复类别与操作:

类别	问题	自动修复操作	保留内容
元素ID	遗留BO-XXX格式	转换为BRD.NN.23.SS	✅
元素ID	遗留FR-XXX格式	转换为BRD.NN.01.SS	✅
元素ID	遗留AC-XXX格式	转换为BRD.NN.06.SS	✅
元素ID	遗留BC-XXX格式	转换为BRD.NN.09.SS	✅
元素ID	BRD中使用无效类型代码	建议正确代码（例如，25→33用于收益）	✅
章节	缺失文档控制字段	从模板添加	✅
章节	缺失可追溯性章节	从模板插入	✅
章节	缺失PRD就绪分数	计算并插入	✅
ADR主题	缺失类别	添加模板条目	✅
ADR主题	缺失备选方案表	添加模板表	✅
ADR主题	缺失云供应商对比表	添加模板表	✅
可追溯性	缺失上游来源	添加模板结构	✅
可追溯性	缺失下游工件	添加模板结构	✅
分数	缺失PRD就绪明细	计算并添加	✅
无效链接	缺失术语表文件	创建BRD-00_GLOSSARY.md	✅
无效链接	缺失参考文档	提示用户选项：(1) 创建占位符，(2) 更新链接，(3) 删除引用	⚠️
无效链接	相对路径错误	根据BRD位置修复路径	✅

内容保留规则:

绝不删除现有业务需求
绝不修改执行摘要内容
绝不更改干系人分析细节
仅添加缺失的章节和元数据
仅替换遗留元素ID为统一格式
如果设置了
```
--backup
```
标志则先备份

元素ID迁移:

遗留模式	新格式	示例
`BO-XXX`	`BRD.NN.23.SS`	BO-001 → BRD.01.23.01
`FR-XXX`	`BRD.NN.01.SS`	FR-001 → BRD.01.01.01
`AC-XXX`	`BRD.NN.06.SS`	AC-001 → BRD.01.06.01
`BC-XXX`	`BRD.NN.09.SS`	BC-001 → BRD.01.09.01
`ADR-T-XXX`	`BRD.NN.32.SS`	ADR-T-001 → BRD.01.32.01

元素类型代码迁移（v2.3）:

无效代码	正确代码	上下文	示例
BRD中的25	33	收益章节	BRD.01.25.01 → BRD.01.33.01

注意：代码25仅对EARS文档（EARS声明）有效。对于BRD收益，请使用代码33（收益声明）。

无效链接修复（v2.3）:

问题	修复操作	是否创建文件
缺失 `BRD-00_GLOSSARY.md`	从模板创建	✅ 是
缺失参考文档（GAP, REF）	提示用户选项：(1) 创建占位符，(2) 更新链接，(3) 删除引用	⚠️ 可选
相对路径错误	根据BRD位置重新计算路径	❌ 否
引用不存在的BRD的交叉引用	记录警告，建议创建BRD	❌ 否

修复报告结构:

markdown

undefined

BRD Fix Report: BRD-01_platform

BRD修复报告: BRD-01_platform

Summary

摘要

Before PRD-Ready Score: 87% 🟡
After PRD-Ready Score: 94% ✅
Issues Fixed: 10
Issues Remaining: 4 (manual review required)

修复前PRD就绪分数: 87% 🟡
修复后PRD就绪分数: 94% ✅
已修复问题数: 10
剩余问题数: 4（需要手动评审）

Fixes Applied

已应用修复

#	Issue	Location	Fix Applied
1	Legacy element ID	Section 4:L45	Converted BO-001 → BRD.01.23.01
2	Missing PRD-Ready score	Document Control	Added 94% with breakdown
3	Missing Cloud Comparison	Section 7.2.3	Added template table
...	...	...	...

#	问题	位置	应用的修复
1	遗留元素ID	章节4:L45	将BO-001转换为BRD.01.23.01
2	缺失PRD就绪分数	文档控制	添加94%及明细
3	缺失云供应商对比	章节7.2.3	添加模板表
...	...	...	...

Files Modified

修改的文件

docs/01_BRD/BRD-01_platform.md

docs/01_BRD/BRD-01_platform.md

Backup Location

备份位置

tmp/backup/BRD-01_platform_20260209_143022.md

tmp/backup/BRD-01_platform_20260209_143022.md

Remaining Issues (Manual Review)

剩余问题（需要手动评审）

#	Issue	Location	Reason
1	Incomplete risk assessment	Section 8:L102	Domain knowledge needed
2	Missing Observability tables	Section 7.2.5	Architecture decision required
...	...	...	...

#	问题	位置	原因
1	风险评估不完整	章节8:L102	需要领域知识
2	缺失可观测性表格	章节7.2.5	需要架构决策
...	...	...	...

Score Breakdown Impact

分数明细影响

Category	Before	After	Delta
Business Objectives	14/15	15/15	+1
Requirements Complete	18/20	20/20	+2
ADR Topics	12/15	14/15	+2
Traceability	10/10	10/10	0

类别	修复前	修复后	变化
业务目标	14/15	15/15	+1
需求完整性	18/20	20/20	+2
ADR主题	12/15	14/15	+2
可追溯性	10/10	10/10	0

Next Steps

下一步

Review manually flagged items
Complete Observability ADR topic
Re-run validation to confirm score


**Fix Configuration**:

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

  fix_categories:
    element_ids: true        # Legacy ID conversion
    sections: true           # Missing sections
    adr_topics: true         # Section 7.2 ADR topics
    traceability: true       # Upstream/downstream refs
    score: true              # PRD-Ready score

  preservation:
    executive_summary: true      # Never modify
    business_requirements: true  # Never modify content
    stakeholder_analysis: true   # Never modify
    comments: true               # Preserve user comments

  validation:
    re_validate_after_fix: true
    require_score_improvement: false
    max_fix_iterations: 3

  element_id_migration:
    BO_XXX_to_BRD_NN_23_SS: true   # BO-001 → BRD.01.23.01
    FR_XXX_to_BRD_NN_01_SS: true   # FR-001 → BRD.01.01.01
    AC_XXX_to_BRD_NN_06_SS: true   # AC-001 → BRD.01.06.01
    BC_XXX_to_BRD_NN_09_SS: true   # BC-001 → BRD.01.09.01

Command Line Options (Review/Fix):

Option	Mode	Default	Description
`--mode review`	Review	-	Run review mode only
`--mode fix`	Fix	-	Run fix mode
`--output-report`	Both	auto	Report output path
`--backup`	Fix	true	Create backup before fixing
`--fix-types`	Fix	all	Comma-separated fix categories
`--dry-run`	Fix	false	Preview fixes without applying
`--preserve-all`	Fix	false	Extra cautious preservation

评审手动标记的项目
完成可观测性ADR主题
重新运行验证确认分数


**修复配置**:

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

  fix_categories:
    element_ids: true        # 遗留ID转换
    sections: true           # 缺失章节
    adr_topics: true         # 章节7.2 ADR主题
    traceability: true       # 上游/下游引用
    score: true              # PRD就绪分数

  preservation:
    executive_summary: true      # 绝不修改
    business_requirements: true  # 绝不修改内容
    stakeholder_analysis: true   # 绝不修改
    comments: true               # 保留用户注释

  validation:
    re_validate_after_fix: true
    require_score_improvement: false
    max_fix_iterations: 3

  element_id_migration:
    BO_XXX_to_BRD_NN_23_SS: true   # BO-001 → BRD.01.23.01
    FR_XXX_to_BRD_NN_01_SS: true   # FR-001 → BRD.01.01.01
    AC_XXX_to_BRD_NN_06_SS: true   # AC-001 → BRD.01.06.01
    BC_XXX_to_BRD_NN_09_SS: true   # BC-001 → BRD.01.09.01

命令行选项（评审/修复）:

选项	模式	默认值	描述
`--mode review`	评审	-	仅运行评审模式
`--mode fix`	修复	-	运行修复模式
`--output-report`	两者	自动	报告输出路径
`--backup`	修复	true	修复前创建备份
`--fix-types`	修复	全部	逗号分隔的修复类别
`--dry-run`	修复	false	预览修复但不应用
`--preserve-all`	修复	false	额外谨慎的内容保留

Parallel Execution

并行执行

Execute independent BRDs concurrently after Platform BRD.

mermaid

flowchart LR
    A[Platform BRD-01] --> B[Feature BRD-02]
    A --> C[Feature BRD-03]
    A --> D[Feature BRD-04]
    B --> E[All BRDs Complete]
    C --> E
    D --> E

Dependency Rules:

Platform BRD (BRD-01) must complete first
Feature BRDs can execute in parallel after Platform BRD
Cross-dependent Feature BRDs execute sequentially

在平台型BRD完成后，并行执行独立的功能型BRD。

mermaid

flowchart LR
    A[平台型BRD-01] --> B[功能型BRD-02]
    A --> C[功能型BRD-03]
    A --> D[功能型BRD-04]
    B --> E[所有BRD完成]
    C --> E
    D --> E

依赖规则:

平台型BRD（BRD-01）必须首先完成
功能型BRD可在平台型BRD完成后并行执行
相互依赖的功能型BRD按顺序执行

Output Artifacts

输出工件

Generated Files

生成的文件

All BRDs use nested folders (

BRD-NN_{slug}/

) regardless of size. Document sectioning (monolithic vs sectioned) depends only on document size (>20k tokens = sectioned).

File	Purpose	Location
BRD-00_index.md	Master BRD index (created/updated)	`docs/01_BRD/`
BRD-00_GLOSSARY.md	Master glossary (created if missing)	`docs/01_BRD/`
BRD-NN_{slug}/	BRD folder (ALWAYS created)	`docs/01_BRD/`
BRD-NN_{slug}.md	Main BRD document (monolithic <20k tokens)	`docs/01_BRD/BRD-NN_{slug}/`
BRD-NN.0_index.md	Section index (sectioned ≥20k tokens)	`docs/01_BRD/BRD-NN_{slug}/`
BRD-NN.S_{section}.md	Section files (sectioned ≥20k tokens)	`docs/01_BRD/BRD-NN_{slug}/`

所有BRD无论大小都使用嵌套文件夹（

BRD-NN_{slug}/

）。文档分章节（单文件vs分章节）仅取决于文档大小（>20k tokens = 分章节）。

文件	用途	位置
BRD-00_index.md	BRD主索引（创建/更新）	`docs/01_BRD/`
BRD-00_GLOSSARY.md	主术语表（缺失时创建）	`docs/01_BRD/`
BRD-NN_{slug}/	BRD文件夹（始终创建）	`docs/01_BRD/`
BRD-NN_{slug}.md	主BRD文档（单文件 <20k tokens）	`docs/01_BRD/BRD-NN_{slug}/`
BRD-NN.0_index.md	章节索引（分章节 ≥20k tokens）	`docs/01_BRD/BRD-NN_{slug}/`
BRD-NN.S_{section}.md	章节文件（分章节 ≥20k tokens）	`docs/01_BRD/BRD-NN_{slug}/`

Review Reports (v2.3)

评审报告（v2.3）

IMPORTANT: Review reports are project documents and MUST be stored alongside the reviewed documents in the nested folder, not in temporary folders.

Report Type	File Name	Location
BRD Review Report	`BRD-NN.R_review_report_v{VVV}.md`	`docs/01_BRD/BRD-NN_{slug}/`
BRD Fix Report	`BRD-NN.F_fix_report_v{VVV}.md`	`docs/01_BRD/BRD-NN_{slug}/`
Drift Cache	`.drift_cache.json`	`docs/01_BRD/BRD-NN_{slug}/`

Note: ALL BRDs (both monolithic and sectioned) use nested folders, so all companion files go in the same location.

Review Document Requirements:

Review reports are formal project documents and MUST comply with all project document standards:

YAML Frontmatter (MANDATORY):

yaml

---
title: "BRD-NN.R: {Module Name} - Review Report"
tags:
  - brd
  - {module-type}
  - layer-1-artifact
  - review-report
  - quality-assurance
custom_fields:
  document_type: review-report
  artifact_type: BRD-REVIEW
  layer: 1
  parent_doc: BRD-NN
  reviewed_document: BRD-NN_{slug}
  module_id: {module_id}
  module_name: {module_name}
  review_date: "YYYY-MM-DD"
  review_tool: doc-brd-autopilot
  review_version: "{version}"
  review_mode: read-only
  prd_ready_score_claimed: {claimed}
  prd_ready_score_validated: {validated}
  validation_status: PASS|FAIL
  errors_count: {n}
  warnings_count: {n}
  info_count: {n}
  auto_fixable_count: {n}
---

Parent Document Reference (MANDATORY):
- Navigation link to parent document index
- ```
@parent-brd: BRD-NN
```
  tag in Traceability section
- Cross-references using relative paths

Section Structure (MANDATORY):

Section	Content
0. Document Control	Report metadata, review date, tool version
1. Executive Summary	Score, status, issue counts
2. Document Overview	Reviewed document details, files reviewed
3. Score Breakdown	Category scores with max values
4-N. Validation Details	Section-specific validation results
N+1. Issues Summary	Errors, warnings, info categorized
N+2. Recommendations	Priority-ordered fix recommendations
N+3. Traceability	Parent document reference

File Naming Convention:
- Pattern:
```
{ARTIFACT}-NN.R_review_report.md
```
- ```
R
```
  suffix indicates Review document type
- Example:
```
BRD-03.R_review_report.md
```

Example Folder Structures:

undefined

重要：评审报告是项目文档，必须存储在被评审文档的嵌套文件夹中，而不是临时文件夹中。

报告类型	文件名	位置
BRD评审报告	`BRD-NN.R_review_report_v{VVV}.md`	`docs/01_BRD/BRD-NN_{slug}/`
BRD修复报告	`BRD-NN.F_fix_report_v{VVV}.md`	`docs/01_BRD/BRD-NN_{slug}/`
漂移缓存	`.drift_cache.json`	`docs/01_BRD/BRD-NN_{slug}/`

注意：所有BRD（单文件和分章节）都使用嵌套文件夹，因此所有配套文件都存储在同一位置。

评审文档要求:

评审报告是正式项目文档，必须符合所有项目文档标准：

YAML前置元数据（必填）:

yaml

---
title: "BRD-NN.R: {模块名称} - 评审报告"
tags:
  - brd
  - {模块类型}
  - layer-1-artifact
  - review-report
  - quality-assurance
custom_fields:
  document_type: review-report
  artifact_type: BRD-REVIEW
  layer: 1
  parent_doc: BRD-NN
  reviewed_document: BRD-NN_{slug}
  module_id: {模块ID}
  module_name: {模块名称}
  review_date: "YYYY-MM-DD"
  review_tool: doc-brd-autopilot
  review_version: "{版本}"
  review_mode: read-only
  prd_ready_score_claimed: {声明分数}
  prd_ready_score_validated: {验证分数}
  validation_status: PASS|FAIL
  errors_count: {n}
  warnings_count: {n}
  info_count: {n}
  auto_fixable_count: {n}
---

父文档引用（必填）:
- 指向父文档索引的导航链接
- 可追溯性章节中的
```
@parent-brd: BRD-NN
```
  标签
- 使用相对路径的交叉引用

章节结构（必填）:

章节	内容
0. 文档控制	报告元数据、评审日期、工具版本
1. 执行摘要	分数、状态、问题数量
2. 文档概述	被评审文档详情、评审的文件
3. 分数明细	带最大值的类别分数
4-N. 验证详情	特定章节的验证结果
N+1. 问题摘要	按类别分类的错误、警告、信息
N+2. 建议	按优先级排序的修复建议
N+3. 可追溯性	父文档引用

文件命名规范:
- 模式:
```
{ARTIFACT}-NN.R_review_report.md
```
- ```
R
```
  后缀表示评审文档类型
- 示例:
```
BRD-03.R_review_report.md
```

示例文件夹结构:

undefined

Monolithic BRD (document <20k tokens)

单文件BRD（文档<20k tokens）

docs/01_BRD/ ├── BRD-07_f7_config/ │ ├── BRD-07_f7_config.md # ← Monolithic document │ ├── BRD-07.R_review_report_v001.md # ← Review report │ ├── BRD-07.F_fix_report_v001.md # ← Fix report │ └── .drift_cache.json # ← Drift cache

docs/01_BRD/ ├── BRD-07_f7_config/ │ ├── BRD-07_f7_config.md # ← 单文件文档 │ ├── BRD-07.R_review_report_v001.md # ← 评审报告 │ ├── BRD-07.F_fix_report_v001.md # ← 修复报告 │ └── .drift_cache.json # ← 漂移缓存

Sectioned BRD (document ≥20k tokens)

分章节BRD（文档≥20k tokens）

docs/01_BRD/ ├── BRD-01_f1_iam/ │ ├── BRD-01.0_index.md # ← Section index │ ├── BRD-01.1_core.md # ← Section 1 │ ├── BRD-01.2_requirements.md # ← Section 2 │ ├── BRD-01.3_quality_ops.md # ← Section 3 │ ├── BRD-01.R_review_report_v001.md # ← Review report │ ├── BRD-01.F_fix_report_v001.md # ← Fix report │ └── .drift_cache.json # ← Drift cache

undefined

docs/01_BRD/ ├── BRD-01_f1_iam/ │ ├── BRD-01.0_index.md # ← 章节索引 │ ├── BRD-01.1_core.md # ← 章节1 │ ├── BRD-01.2_requirements.md # ← 章节2 │ ├── BRD-01.3_quality_ops.md # ← 章节3 │ ├── BRD-01.R_review_report_v001.md # ← 评审报告 │ ├── BRD-01.F_fix_report_v001.md # ← 修复报告 │ └── .drift_cache.json # ← 漂移缓存

undefined

Temporary Files

临时文件

Report	Purpose	Location
brd_validation_report.json	Machine-readable validation data	`tmp/`
prd_ready_score.json	PRD-Ready score calculation	`tmp/`
autopilot_log.md	Execution log	`tmp/`

Note: JSON reports in

tmp/

are for programmatic access. Human-readable review reports MUST be stored with the reviewed documents.

报告	用途	位置
brd_validation_report.json	机器可读的验证数据	`tmp/`
prd_ready_score.json	PRD就绪分数计算	`tmp/`
autopilot_log.md	执行日志	`tmp/`

注意：

tmp/

中的JSON报告用于程序访问，人类可读的评审报告必须与被评审文档一起存储。

Error Handling

错误处理

Error Categories

错误类别

Category	Handling	Example
Input Missing	Abort with message	No strategy documents found
Validation Failure	Auto-fix, retry	Missing required section
PRD-Ready Below 90%	Enhance sections, retry	Score at 85%
Platform BRD Missing	Queue Platform BRD first	Feature BRD without BRD-01
Max Retries Exceeded	Flag for manual review	Persistent validation errors

类别	处理方式	示例
输入缺失	终止并显示消息	未找到战略文档
验证失败	自动修复，重试	缺失必填章节
PRD就绪分数低于90%	增强章节，重试	分数为85%
平台型BRD缺失	优先排队平台型BRD	无BRD-01的功能型BRD
超过最大重试次数	标记为需要手动评审	持续的验证错误

Recovery Actions

恢复操作

python

def handle_error(error_type: str, context: dict) -> Action:
    match error_type:
        case "INPUT_MISSING":
            return Action.ABORT_WITH_MESSAGE
        case "VALIDATION_FAILURE":
            if context["retry_count"] < 3:
                return Action.AUTO_FIX_RETRY
            return Action.FLAG_MANUAL_REVIEW
        case "PRD_READY_LOW":
            return Action.ENHANCE_SECTIONS
        case "PLATFORM_BRD_MISSING":
            return Action.QUEUE_PLATFORM_FIRST
        case _:
            return Action.FLAG_MANUAL_REVIEW

python

def handle_error(error_type: str, context: dict) -> Action:
    match error_type:
        case "INPUT_MISSING":
            return Action.ABORT_WITH_MESSAGE
        case "VALIDATION_FAILURE":
            if context["retry_count"] < 3:
                return Action.AUTO_FIX_RETRY
            return Action.FLAG_MANUAL_REVIEW
        case "PRD_READY_LOW":
            return Action.ENHANCE_SECTIONS
        case "PLATFORM_BRD_MISSING":
            return Action.QUEUE_PLATFORM_FIRST
        case _:
            return Action.FLAG_MANUAL_REVIEW

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:

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

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

Execution Pattern:

For BRD batch of N documents:
  Chunk 1: BRD-01, BRD-02, BRD-03 → Complete → Summary
  [Context compaction opportunity]
  Chunk 2: BRD-04, BRD-05, BRD-06 → Complete → Summary
  [Context compaction opportunity]
  ...continue until all documents processed

Chunk Completion Template:

markdown

undefined

关键：为防止对话上下文溢出错误（"提示过长"、"对话过长"），所有自动流水线操作必须遵循分块执行规则：

分块大小限制：每个分块最多3个文档

分块规则:

分块形成：将文档分组为最多3个文档的分块
分块顺序处理：一次处理一个分块，完成一个分块中的所有文档后再开始下一个
上下文暂停：完成每个分块后，提供摘要并暂停等待用户确认
进度跟踪：显示分块进度（例如，"分块2/5：处理BRD-04、BRD-05、BRD-06..."）

为什么需要分块:

防止批量处理期间出现"对话过长"错误
允许分块之间的上下文压缩
支持从故障中恢复而不丢失所有进度
为用户评审提供自然的检查点

执行模式:

对于N个文档的BRD批量:
  分块1: BRD-01, BRD-02, BRD-03 → 完成 → 摘要
  [上下文压缩机会]
  分块2: BRD-04, BRD-05, BRD-06 → 完成 → 摘要
  ...继续直到所有文档处理完成

分块完成模板:

markdown

undefined

Chunk N/M Complete

分块N/M完成

Generated:

BRD-XX: PRD-Ready Score 94%
BRD-YY: PRD-Ready Score 92%
BRD-ZZ: PRD-Ready Score 95%

Proceeding to next chunk...

---

已生成:

BRD-XX: PRD就绪分数94%
BRD-YY: PRD就绪分数92%
BRD-ZZ: PRD就绪分数95%

继续下一个分块...

---

Integration Points

集成点

Pre-Execution Hooks

预执行钩子

bash

undefined

bash

undefined

Hook: pre_brd_generation

钩子: pre_brd_generation

Runs before BRD generation starts

在BRD生成开始前运行

./hooks/pre_brd_generation.sh

Example: Validate input sources exist

示例: 验证输入源是否存在

if [ ! -d "docs/00_REF/" ] && [ ! -d "REF/" ]; then echo "ERROR: docs/00_REF/ or REF/ directory required" exit 1 fi

undefined

if [ ! -d "docs/00_REF/" ] && [ ! -d "REF/" ]; then echo "ERROR: 需要docs/00_REF/或REF/目录" exit 1 fi

undefined

Post-Execution Hooks

后执行钩子

bash

undefined

bash

undefined

Hook: post_brd_generation

钩子: post_brd_generation

Runs after BRD generation completes

在BRD生成完成后运行

./hooks/post_brd_generation.sh

Example: Trigger PRD autopilot for validated BRD

示例: 为已验证的BRD触发PRD自动流水线

if [ "$BRD_VALIDATED" = "true" ]; then python ai_dev_flow/scripts/prd_autopilot.py
--brd "$BRD_PATH"
--output docs/02_PRD/ fi

undefined

if [ "$BRD_VALIDATED" = "true" ]; then python ai_dev_flow/scripts/prd_autopilot.py
--brd "$BRD_PATH"
--output docs/02_PRD/ fi

undefined

CI/CD Integration

CI/CD集成

yaml

undefined

yaml

undefined

.github/workflows/brd_autopilot.yml

name: BRD Autopilot

on: push: paths: - 'docs/00_REF/' - 'REF/'

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

  - name: Run BRD Autopilot
    run: |
      python ai_dev_flow/scripts/brd_autopilot.py \
        --ref docs/00_REF/ \
        --output docs/01_BRD/ \
        --validate

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

---

name: BRD自动流水线

on: push: paths: - 'docs/00_REF/' - 'REF/'

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

  - name: 运行BRD自动流水线
    run: |
      python ai_dev_flow/scripts/brd_autopilot.py \
        --ref docs/00_REF/ \
        --output docs/01_BRD/ \
        --validate

  - name: 上传验证报告
    uses: actions/upload-artifact@v4
    with:
      name: brd-validation
      path: tmp/brd_validation_report.json

---

Quality Gates

质量门

Phase Gates

阶段门

Phase	Gate	Criteria
Phase 1	Input Gate	At least one reference document found in `docs/00_REF/` or `REF/` , or user prompts provided
Phase 2	Type Gate	BRD type determined (Platform/Feature)
Phase 3	Generation Gate	All 18 sections generated
Phase 4	Validation Gate	PRD-Ready Score >= 90%
Phase 5	Review Gate	No blocking issues remaining

阶段	门	标准
阶段1	输入门	在 `docs/00_REF/` 或 `REF/` 中至少找到一个参考文档，或提供了用户提示
阶段2	类型门	已确定BRD类型（平台型/功能型）
阶段3	生成门	所有18个章节已生成
阶段4	验证门	PRD就绪分数≥90%
阶段5	评审门	无阻塞问题剩余

Blocking vs Non-Blocking

阻塞vs非阻塞

Issue Type	Blocking	Action
Missing required section	Yes	Must fix before proceeding
PRD-Ready Score < 90%	Yes	Must enhance sections
Invalid element ID format	Yes	Must convert to unified format
Missing optional section	No	Log warning, continue
Style/formatting issues	No	Auto-fix, continue

问题类型	是否阻塞	操作
缺失必填章节	是	必须修复后才能继续
PRD就绪分数<90%	是	必须增强章节
无效元素ID格式	是	必须转换为统一格式
缺失可选章节	否	记录警告，继续
样式/格式问题	否	自动修复，继续

Related Resources

Version History

版本历史

Version	Date	Changes
2.5	2026-02-11	Smart Document Detection: Added automatic document type recognition; Self-type input (BRD-NN) triggers review mode; Reference docs and prompts trigger generation; Special handling for Layer 1 (no upstream documents)
2.4	2026-02-10	Source Directory Update: Changed input sources from `strategy/` , `docs/inputs/` to `docs/00_REF/` (primary), `REF/` (alternative), user prompts (fallback); BRD Index: Added automatic creation/update of `BRD-00_index.md` master index with Document Registry, Module Categories, Statistics; Updated all examples and CI/CD configurations
2.3	2026-02-10	Review & Fix Cycle: Replaced Phase 5 with iterative Review → Fix cycle using `doc-brd-reviewer` and `doc-brd-fixer` ; Added `doc-brd-fixer` skill dependency; Link Validation: Added Phase 1.1 Source Document Link Validation to verify `@ref:` targets exist before generation; Glossary Handling: Added Phase 3 Step 10 Master Glossary Handling with automatic creation/path resolution; Element ID Fixes: Added type code migration (25→33) and broken link fix categories
2.2	2026-02-10	Added Review Document Standards: review reports stored alongside reviewed documents (not in tmp/); review reports require YAML frontmatter, parent document references, and structured sections; file naming convention `{ARTIFACT}-NN.R_review_report.md`
2.1	2026-02-09	Added Review Mode for validating existing BRD documents without modification; Added Fix Mode for auto-repairing BRD documents while preserving manual content; Added fix categories (element_ids, sections, adr_topics, traceability, score); Added content preservation rules; Added backup functionality; Added element ID migration (BO_XXX, FR_XXX, AC_XXX, BC_XXX to unified format)
1.0	2026-02-08	Initial skill creation with 5-phase workflow; Integrated doc-naming, doc-brd, doc-brd-validator, quality-advisor skills; Added Platform vs Feature BRD handling; Added Section 7.2 ADR Topics generation

版本	日期	变更
2.5	2026-02-11	智能文档检测: 添加自动文档类型识别；自身类型输入（BRD-NN）触发评审模式；参考文档和提示触发生成模式；针对层级1（无上游文档）的特殊处理
2.4	2026-02-10	源目录更新: 将输入源从 `strategy/` , `docs/inputs/` 更改为 `docs/00_REF/` （主）、 `REF/` （备选）、用户提示（ fallback）；BRD索引: 添加自动创建/更新 `BRD-00_index.md` 主索引，包含文档注册表、模块分类、统计信息；更新所有示例和CI/CD配置
2.3	2026-02-10	评审与修复循环: 使用 `doc-brd-reviewer` 和 `doc-brd-fixer` 将阶段5替换为迭代式评审→修复循环；添加 `doc-brd-fixer` 技能依赖；链接验证: 添加阶段1.1源文档链接验证，在生成前验证 `@ref:` 目标是否存在；术语表处理: 添加阶段3步骤10主术语表处理，支持自动创建/路径解析；元素ID修复: 添加类型代码迁移（25→33）和无效链接修复类别
2.2	2026-02-10	添加评审文档标准：评审报告存储在被评审文档旁边（而非tmp/）；评审报告需要YAML前置元数据、父文档引用和结构化章节；文件命名规范 `{ARTIFACT}-NN.R_review_report.md`
2.1	2026-02-09	添加评审模式用于验证现有BRD文档而不修改；添加修复模式用于自动修复BRD文档同时保留手动内容；添加修复类别（element_ids, sections, adr_topics, traceability, score）；添加内容保留规则；添加备份功能；添加元素ID迁移（BO_XXX, FR_XXX, AC_XXX, BC_XXX到统一格式）
1.0	2026-02-08	初始技能创建，包含5阶段工作流；集成doc-naming, doc-brd, doc-brd-validator, quality-advisor技能；添加平台型vs功能型BRD处理；添加章节7.2 ADR主题生成