# 文档-bdd-修复程序 ## 目的自动**修复技能**，读取最新的审计/审查报告并将修复应用于 BDD（行为驱动开发）文档。此技能弥合了“doc-bdd-reviewer”/“doc-bdd-audit”（识别问题）和纠正的 BDD 之间的差距，从而实现迭代改进周期。 **Layer** : 4 (BDD Quality Improvement) **上游**：BDD 文档、审核/审核报告（首选“BDD-NN.A_audit_report_vNNN.md”、“BDD-NN.R_review_report_vNNN.md”）、EARS（源要求） **下游**：修复BDD，修复报告（`BDD-NN.F_fix_report_vNNN.md`） ** ** ## 何时使用此技能 Use `doc-bdd-fixer` when: * **After Review** : Run after `doc-bdd-reviewer` identifies issues * **Iterative Improvement** : Part of Review -> Fix -> Review cycle * **自动化管道**：用于质量关卡的 CI/CD 集成 * **批量修复** ：根据审核报告将修复应用于多个 BDD **请勿在以下情况下使用**： * 不存在审核/审核报告（首先运行 `doc-bdd-audit` 或 `doc-bdd-reviewer`） * Creating new BDD (use `doc-bdd` or `doc-bdd-autopilot`) * Only need validation (use `doc-bdd-validator`) ** ** ## 技能依赖技能|目的|使用时 ---|---|--- `doc-bdd-审计` | Preferred source of normalized findings | Input (reads audit report) `doc-bdd-审稿人` |需要修复的遗留/替代问题源 | Input (reads review report) `文档命名` |元素 ID 标准 |修复元素 ID `doc-bdd` | BDD创建规则|创建缺失的部分 `doc-ears-审阅者` |上游 EARS 验证 |检查上游对齐情况 ** ** ## 工作流程概述流程图TD A[输入：BDD 路径] --> B[查找最新审核/审核报告] B --> C{找到报告？} C -->|否| D[Run doc-bdd-audit or doc-bdd-reviewer First] C -->|是| E[解析报告] E --> F[问题分类] 子图 FixPhases["修复阶段"] F --> F0[阶段 0：修复结构违规] F0 --> G[阶段 1: 创建丢失的文件] G --> H[Phase 2: Fix Broken Links] H --> I[阶段 3：修复元素 ID] I --> J[第 4 阶段：修复内容问题] J --> K[第 5 阶段：更新参考文献] K --> K2[Phase 6: Handle Upstream Drift] 结束 K2 --> L[写入固定 BDD] L --> M[生成修复报告] M --> N{重新运行审核？} N -->|是| O[调用 doc-bdd-reviewer] O --> P{分数 >= 阈值？} P -->|No, iterations < max| F P -->|是|问[完成] N -->|否|问 ** ** ## 修复阶段 ### 第 0 阶段：修复结构违规（严重） Fixes BDD documents that are not in nested folders.此阶段首先运行，因为所有后续阶段都依赖于正确的文件夹结构。 **Nested Folder Rule** : ALL BDD documents MUST be in nested folders regardless of document size. **所需结构**： BDD 类型 |所需地点 ---|--- 降价| `docs/04_BDD/BDD-NN_{slug}/BDD-NN_{slug}.md` 特色 | `docs/04_BDD/BDD-NN_{slug}/BDD-NN_{slug}.feature` **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-STR001 | BDD 不在嵌套文件夹中 |创建文件夹、移动文件、更新所有链接 REV-STR002 | BDD 文件夹名称与 BDD ID 不匹配 |重命名文件夹以匹配 REV-STR003 |应将 >25KB 的整体 BDD 进行分段 |手动审核标记 **结构修复工作流程**： def fix_bdd_struct(bdd_path: str) -> 列表[修复]: """Fix BDD structure violations.""" 修复=[] filename = os.path.basename(bdd_path) 父文件夹 = os.path.dirname(bdd_path) # 从文件名中提取 BDD ID 和 slug（支持 .md 和 .feature） match = re.match(r'BDD-(\d+)_([^/]+)\.(md|feature)', 文件名) 如果不匹配： return [] # 无法自动修复无效文件名 bdd_id = match.group(1) slug = match.group（2） Expected_folder = f“BDD-{bdd_id}_{slug}” # 检查是否已经在嵌套文件夹中如果 os.path.basename(parent_folder) != Expected_folder: # 创建嵌套文件夹 new_folder = os.path.join(os.path.dirname(parent_folder), Expected_folder) os.makedirs（new_folder，exist_ok = True） # 移动文件 new_path = os.path.join(new_folder, 文件名) Shutil.move(bdd_path, new_path) Fixs.append(f"已将 {bdd_path} 移动到 {new_path}") # 更新移动文件中的上游链接内容=路径(new_path).read_text() update_content = content.replace('../03_EARS/', '../../03_EARS/') 更新内容 = 更新内容.replace('../02_PRD/', '../../02_PRD/') 路径（新路径）.write_text（更新内容） Fixs.append(f“更新了嵌套文件夹结构的相对链接”) 返回修复 **移动后链接路径更新**：原始路径 |更新路径 ---|--- `../03_EARS/EARS-01_slug/EARS-01.md` | `../../03_EARS/EARS-01_slug/EARS-01.md` `../02_PRD/PRD-01_slug/PRD-01.md` | `../../02_PRD/PRD-01_slug/PRD-01.md` ** ** ### 第 1 阶段：创建丢失的文件创建被引用但不存在的文件。 **范围** ：丢失文件 |行动|使用的模板 ---|---|--- `BDD-00_GLOSSARY.md` | Create BDD glossary |词汇表模板 `BDD-NN_STEP_DEFS.md` |创建步骤定义占位符 |步骤定义模板功能文件 (`*.feature`) |使用 TODO 部分创建占位符 |特征模板共享上下文文件 |创建占位符 |上下文模板 **BDD 术语表模板**： --- 标题：“BDD-00：行为术语表” 标签： - BD - 词汇表 - 参考自定义字段： document_type：术语表 artifact_type：BDD-参考层数：4 --- # BDD-00：行为术语表所有 BDD 功能文档中使用的通用术语。 ## 小黄瓜关键词 |术语 |定义|背景 | |------|------------|---------| |特色 |高层行为描述|功能标题 | |场景|具体测试案例|测试定义| |场景概要|参数化场景|数据驱动测试 | |给定|前提条件设置 |背景 | |当 |动作触发|活动 | |然后| Expected outcome |断言| |和|附加步骤|继续 | |但是|负延续|例外 | |背景|共享先决条件 |可重复使用的设置 | |示例 |轮廓数据表|测试数据| ## 步骤定义术语 |术语 |定义|背景 | |------|------------|---------| |步骤定义| Gherkin 步骤的代码绑定 |实施| |世界 |共享上下文对象|状态管理| |钩|生命周期方法之前/之后 | Setup/teardown | |标签 |场景/特征标注|过滤 | ## 域名术语 |术语 |定义|背景 | |------|------------|---------| | [术语] | [定义] | [使用地点] | **功能占位符模板**： # 语言：en # 编码：UTF-8 @placeholder @needs-completion 功能：[功能名称] As a [role] 我想要【能力】这样[好处] # TODO：由 doc-bdd-fixer 创建作为占位符 # 完成此功能文件以解决断开的链接问题背景：鉴于[TODO：定义共享先决条件] @todo 场景：[TODO：定义场景名称] 给定 [TODO：定义前提条件] 当[TODO：定义操作]时然后[TODO：定义预期结果] **步骤定义占位符模板**： --- 标题：“BDD 步骤定义：[模块名称]” 标签： - bdd - 步骤定义 - reference custom_fields: document_type：步骤定义 status: placeholder 创建者：doc-bdd-fixer --- # BDD 步骤定义：[模块名称] > **状态**：占位符 - 需要完成 ## 1. 概述 [TODO：文档步骤定义概述] ## 2.给定步骤 | Step Pattern | Implementation |状态 | |--------------|----------------|--------| | `Given [pattern]` | [待办事项] |占位符 | ## 3. When Steps | Step Pattern |实施 |状态 | |--------------|----------------|--------| | `当[模式]` | [待办事项] |占位符 | ## 4. Then Steps |阶梯图案| Implementation |状态 | |--------------|----------------|--------| | `然后[模式]` | [待办事项] |占位符 | ## 5. 共享助手 [TODO：记录共享辅助函数] --- *由 doc-bdd-fixer 作为占位符创建。完成本文档以解决断开的链接问题。* ** ** ### 第 2 阶段：修复损坏的链接更新链接以指向正确的位置。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-L001 |内部链接失效 |更新路径或创建目标文件 REV-L002 |外部链接无法访问 |添加警告评论，保留链接 REV-L003 |使用绝对路径|转换为相对路径 REV-L004 |耳朵断了参考| Update to correct EARS path REV-L005 |损坏的功能文件参考 |更新或创建功能文件 **路径解析逻辑**： def fix_link_path(bdd_location: str, target_path: str) -> str: """根据BDD位置计算正确的相对路径。""" # 整体 BDD：docs/04_BDD/BDD-01.md # 分段 BDD：docs/04_BDD/BDD-01_slug/BDD-01.3_section.md # 功能文件：tests/bdd/features/*.feature if is_sectioned_bdd(bdd_location): # 需要再升一级返回“../”+calculate_relative_path(bdd_location,target_path) 其他：返回计算相对路径（bdd_location，目标路径） **EARS 链接修复**： BDD 类型 |原文链接 |固定链接 ---|---|--- 整体| `../03_EARS/EARS-01.md` | `../03_EARS/EARS-01.md` 切片| `../03_EARS/EARS-01.md` | `../../03_EARS/EARS-01.md` **功能文件链接修复**： BDD 类型 |原文链接 |固定链接 ---|---|--- 整体| `../../tests/bdd/features/auth.feature` | `../../tests/bdd/features/auth.feature` 切片| `../../tests/bdd/features/auth.feature` | `../../../tests/bdd/features/auth.feature` ** ** ### 第 3 阶段：修复元素 ID 将无效的元素 ID 转换为正确的格式。 **转换规则**：图案|问题 |转换 ---|---|--- `BDD.NN.01.SS` |代码 01 对于 BDD 无效 | `BDD.NN.35.SS`（功能规范） `BDD.NN.25.SS` |代码 25 对 BDD 无效 | `BDD.NN.36.SS`（场景规范） `BDD.NN.22.SS` |代码 22 对 BDD 无效 | `BDD.NN.37.SS`（步骤定义） `壮举-XXX` |遗留模式| `BDD.NN.35.SS` `场景-XXX` |遗留模式| `BDD.NN.36.SS` `步骤-XXX` |遗留模式| `BDD.NN.37.SS` **类型代码映射**（BDD 特定的有效代码：35、36、37）：无效代码 |有效代码 |元素类型 ---|---|--- 01 | 35 | 35特性规格 02 | 36 | 36场景规范 03 | 37 | 37步骤定义 05 | 36 | 36场景规范 06 | 37 | 37步骤定义 22 | 22 35 | 35特性规格 25 | 25 36 | 36场景规范 26 | 26 37 | 37步骤定义 **正则表达式模式**： # 查找 BDD 类型代码无效的元素 ID invalid_bdd_type_01 = r'BDD\.(\d{2})\.01\.(\d{2})' replacement_01 = r'BDD.\1.35.\2' invalid_bdd_type_25 = r'BDD\.(\d{2})\.25\.(\d{2})' replacement_25 = r'BDD.\1.36.\2' invalid_bdd_type_22 = r'BDD\.(\d{2})\.22\.(\d{2})' replacement_22 = r'BDD.\1.37.\2' # 查找遗留模式 Legacy_feat = r'###\s+FEAT-(\d+):' Legacy_scen = r'###\s+SCEN-(\d+):' Legacy_step = r'###\s+STEP-(\d+):' ** ** ### 第 4 阶段：修复内容问题解决了占位符、不完整的内容和 BDD 特定的语法问题。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-P001 | `[TODO]` 占位符 | Flag for manual completion (cannot auto-fix) REV-P002 | `[TBD]` 占位符 | 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 |空部分| Add minimum template content REV-B001 | Missing Gherkin keyword |手动审核标记 REV-B002 | Invalid scenario structure |手动审核标记 REV-B003 | Missing Given/When/Then |手动审核标记 REV-B004 |孤立步骤定义 |手动审核标记 **自动更换**：替换={ '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'), '[Feature Name]': extract_feature_name_from_metadata(), } **Gherkin Structure Validation** : 图案类型|所需结构|自动修复 ---|---|--- 特色 | Feature: [name] + user story format |否（标志）场景|场景：[名称] + 给定/何时/然后 | No (flag) 场景概要| Scenario Outline + Examples table |否（标志）背景| Background: + Given steps only |否（标志）步骤|给定/当/那么/和/但是 + 描述 | No (flag) ** ** ### 第 5 阶段：更新参考文献 Ensures traceability and cross-references are correct. **修复操作**：问题 |修复行动 ---|--- Missing `@ref:` for created files | Add reference tag Incorrect cross-BDD path | Update to correct relative path Missing EARS traceability | Add EARS reference with `@trace: EARS-NN` Missing traceability entry |添加到追溯矩阵缺少功能标签 |添加适当的标签 **Traceability Format** : @trace: EARS-01.25.01 -> BDD-01.35.01 @ref: [EARS-01 Section 3](../03_EARS/EARS-01.md#3-functional-requirements) **Tag Traceability in Feature Files** : @trace：EARS-01.25.01 @feature：BDD-01.35.01 Feature: User Authentication ** ** ### 第 6 阶段：处理上游漂移（自动合并） Addresses issues where upstream EARS documents have changed since BDD creation. Uses a tiered auto-merge system based on change percentage to automatically incorporate new requirements. #### 6.0.1 Hash Validation Fixes **FIX-H001: Invalid Hash Placeholder** Trigger: Hash contains placeholder instead of SHA-256 修复： sha256sum <上游文件路径> | cut -d' ' -f1 使用以下命令更新缓存：`sha256:<64_hex_output>` **FIX-H002: Missing Hash Prefix** Trigger: 64 hex chars but missing `sha256:` prefix Fix: Prepend `sha256:` to value **FIX-H003：找不到上游文件** 触发器：无法计算哈希（文件丢失） Fix: Set `drift_detected: true`, add to manual review 代码|描述 |自动修复 |严重性 ---|---|---|--- FIX-H001 | Replace placeholder hash with actual SHA-256 |是的 |错误 FIX-H002 | Add missing sha256: prefix |是的 | Warning FIX-H003 |找不到上游文件 |部分|错误 ** ** **Upstream** : EARS (Layer 3) **Downstream** : ADR (Layer 5) ** ** #### 6.1 变化百分比计算通过比较 EARS 内容哈希来计算漂移百分比： def 计算变化百分比( original_ears_hash: str, current_ears_hash：str， original_content: str, current_content: str ) -> float: """计算上游 EARS 中内容更改的百分比。""" if original_ears_hash == current_ears_hash: 返回 0.0 # 基于行的差异计算 Original_lines = set(original_content.strip().split('\n')) current_lines = set(current_content.strip().split('\n')) added_lines = current_lines - original_lines 删除的行数 = 原始行数 - 当前行数 total_original = len(original_lines) 如果total_original == 0： return 100.0 if current_lines else 0.0 更改百分比 = (len(添加的行数) + len(删除的行数)) / 原始总数 * 100 return round(change_percentage, 2) ** ** #### 6.2 Tiered Auto-Merge Thresholds 等级 | Change % |行动| Version Increment |用户认可 ---|---|---|---|--- **1 级** | < 5% | Auto-merge new scenarios |补丁（1.0.0 -> 1.0.1）|否 **Tier 2** | 5-15% | Auto-merge with detailed changelog |次要 (1.0.1 -> 1.1.0) |否 **Tier 3** | > 15% | Archive current, trigger regeneration | Major (1.1.0 -> 2.0.0) |是（推荐） ** ** #### 6.3 Tier 1: Minor Drift (< 5%) **触发器**：上游 EARS 中的少量补充或澄清。 **行动**： 1. 解析现有 BDD 场景未涵盖的新 EARS 要求 2. 使用自动生成的标签生成新场景 3. Append to appropriate feature file 4. Increment patch version **Auto-Generated Scenario Tag Format** : @BDD-{NN}-SC-{SS} 其中： * `NN` = BDD document number (01-99) * `SC` = Scenario identifier * `SS` = Sequential scenario number (01-99) **示例**： # Auto-merged from EARS-01 drift (2026-02-10) @BDD-01-SC-13 @auto-merged @trace:EARS-01.25.12 场景：用户收到密码过期通知 Given a user with password expiring in 7 days When the daily notification job runs Then the user receives an expiry warning email **Tier 1 Changelog Entry** : ### v1.0.1 (2026-02-10) - Patch **漂移合并**：第 1 层（EARS-01 中检测到 3.2% 的变化） |添加场景 |标签 |来源 | |-----------------|-----|--------| | User receives notification on password expiry | @BDD-01-SC-13 |耳朵-01.25.12 | ** ** #### 6.4 Tier 2: Moderate Drift (5-15%) **Trigger** : Significant additions or modifications in upstream EARS. **行动**： 1. Parse all new/modified EARS requirements 2. Generate new scenarios for additions 3. 如果源需求已修改，则标记现有场景以供审核 4. Generate detailed changelog 5. Increment minor version **详细变更日志格式**： ### v1.1.0 (2026-02-10) - 次要 **漂移合并**：第 2 层（在 EARS-01、EARS-02 中检测到 8.7% 的变化） #### 添加新场景 |场景|标签 |功能文件|来源 | |----------|-----|--------------|--------| |用户收到密码过期通知 | @BDD-01-SC-13 | auth.feature |耳朵-01.25.12 | |管理员可以强制重置密码 | @BDD-01-SC-14 | auth.feature |耳朵-01.25.13 | |每个角色的会话超时可配置 | @BDD-01-SC-15 |会话. 功能 |耳朵-05.25.2 | #### 标记为审查的场景 |场景|标签 |原因 |来源变更 | |----------|-----|--------|----------------| |用户使用有效凭据进行身份验证 | @BDD-01-SC-01 |修改源要求 | EARS-01.25.01 v2 | #### 上游变更摘要 |文件|章节已更改 |添加行 |删除行 | |----------|------------------|-------------|---------------| | EARS-01.md | 3.1、3.5、4.2 | 24 | 6 | | EARS-02.md | 5.1 | 8 | 0 | **修改源代码的审阅标记**： # 审核：源要求 EARS-01.25.01 于 2026 年 2 月 10 日修改 # 原：“用户必须使用用户名和密码进行身份验证” # 更新：“用户必须使用用户名和密码或 SSO 进行身份验证” @BDD-01-SC-01 @needs-review @trace:EARS-01.25.01 场景：用户使用有效凭据进行身份验证 # ...现有步骤... ** ** #### 6.5 第 3 级：严重漂移 (> 15%) **触发器**：表明主要需求演变的重大变化。 **行动**： 1. 归档当前BDD版本 2. 创建存档清单 3. 触发再生工作流程 4.增加主要版本 **无删除政策**：现有场景永远不会被删除。相反： # 已弃用：被 EARS-01 v3 更改取代 (2026-02-10) # 原因：重新设计身份验证流程以支持仅 SSO 模式 # 存档：BDD-01_v1.1.0_archive/auth.feature @BDD-01-SC-01 @已弃用 @archive:v1.1.0 场景：用户使用用户名和密码进行身份验证 # ...保留现有步骤... **存档清单创建**：位置：`docs/04_BDD/BDD-{NN}_v{X.Y.Z}_archive/MANIFEST.md` --- 标题：“BDD-01 存档清单 v1.1.0” 标签： - BD - 存档 - 清单自定义字段：存档日期：“2026-02-10T16:00:00” archive_reason：“第 3 层漂移（EARS-01 中的变化为 22.4%）” 原始版本：“1.1.0” 新版本：“2.0.0” 触发上游：“EARS-01 v3” --- # BDD-01 存档清单 v1.1.0 ## 档案摘要 |领域 |价值| |--------|--------| |存档版本 | 1.1.0 | |存档日期 | 2026-02-10T16:00:00 | |原因 |第 3 级上游漂移（变化 22.4%）| |触发上游 | EARS-01 v3 | |新版本 | 2.0.0（已触发再生）| ## 存档文件 |文件 |场景 |状态 | |------|------------|--------| | BDD-01.md | - |存档 | | auth.feature | 5 | 3 个已弃用，2 个已保留 | |会话. 功能 | 3 | 1 已弃用，2 已保留 | | api. 功能 | 8 | 4 个已弃用，4 个已保留 | ## 已弃用的场景 |标签 |场景|弃用原因 | |-----|----------|--------------------| | @BDD-01-SC-01 |用户使用用户名和密码进行身份验证 | v3 中的仅 SSO 身份验证 | | @BDD-01-SC-02 |用户因密码错误而身份验证失败 |被 SSO 错误处理取代 | | @BDD-01-SC-05 |密码复杂度验证 |已删除 - SSO 处理身份验证 | ## 保留的场景 |标签 |场景|保存于 | |-----|----------|--------------| | @BDD-01-SC-03 |用户会话超时后过期 | BDD-01 v2.0.0 | | @BDD-01-SC-04 |用户可以从所有设备注销 | BDD-01 v2.0.0 | ## 再生触发从更新的 EARS 重新生成 BDD 的命令： ````bash /doc-bdd-autopilot EARS-01 --version 2.0.0 --preserve-from BDD-01_v1.1.0_archive --- #### 6.6 增强型漂移缓存处理漂移问题后，更新`.drift_cache.json`： ```json { "bdd_id": "BDD-01", "bdd_version": "1.1.0", “bdd_updated”：“2026-02-10T16:00:00”， “drift_reviewed”：“2026-02-10T16:00:00”， "upstream_type": "EARS", "downstream_type": "ADR", “upstream_hashes”：{ “EARS-01.md”：{ “哈希”：“a1b2c3d4e5f6...”， “版本”：“2.0”， “最后检查”：“2026-02-10T16:00:00” }, “EARS-02.md”：{ “哈希”：“e5f6g7h8i9j0...”， “版本”：“1.5”， “最后检查”：“2026-02-10T16:00:00” } }, “合并历史记录”：[ { “日期”：“2026-02-08T10:00:00”， “等级”：1， “变化百分比”：3.2， "version_before": "1.0.0", "version_after": "1.0.1", "scenarios_add": ["@BDD-01-SC-10"], “scenarios_deprecated”：[]， "upstream_trigger": "EARS-01 v1.8" }, { “日期”：“2026-02-10T16:00:00”， “等级”：2， “变化百分比”：8.7， "version_before": "1.0.1", "version_after": "1.1.0", "scenarios_add": ["@BDD-01-SC-13", "@BDD-01-SC-14", "@BDD-01-SC-15"], “scenarios_deprecated”：[]， "upstream_trigger": "EARS-01 v2.0、EARS-02 v1.5" } ], “acknowledged_drift”：[ { “文档”：“EARS-03.md”， “acknowledged_date”：“2026-02-09”， "reason": "仅文档更改 - 没有 BDD 影响" } ], “下一个场景编号”：16 } ** ** #### 6.7 自动合并工作流程流程图TD A[检测上游漂移] --> B[计算变化%] B --> C{变化 < 5%？} C -->|是| D[第 1 层：自动合并] D --> D1[生成新场景] D1 --> D2[Add @BDD-NN-SC-SS tags] D2 --> D3[增量补丁版本] D3 --> E[更新漂移缓存] C -->|否| F{变化5-15%？} F -->|是| G[第 2 层：自动合并 + 变更日志] G --> G1[生成新场景] G1 --> G2[标记已修改以供审查] G2 --> G3[生成详细变更日志] G3 --> G4[Increment minor version] G4 --> E F -->|否| H[第 3 层：存档 + 重新生成] H --> H1[Archive current version] H1 --> H2[Create archive manifest] H2 --> H3[标记已弃用的场景] H3 --> H4[触发再生] H4 --> H5[增加主要版本] H5 --> E E --> I[更新.drift_cache.json] I --> J[生成修复报告] ** ** #### 6.8 漂移问题代码代码|严重性 |描述 |等级 |自动修复 ---|---|---|---|--- REV-D001 |信息 | EARS modified after BDD (< 5%) | 1 |是（自动合并） REV-D002 |警告| EARS modified after BDD (5-15%) | 2 |是（自动合并+变更日志） REV-D003 |信息 | EARS 版本增加 | 1-2 | 1-2是（更新版本参考） REV-D004 |信息 | New requirements added to EARS | 1-2 | 1-2是（生成场景） REV-D005 |警告| Critical EARS modification (> 15%) | 3 | Partial (archive + trigger regen) REV-D006 |信息 | Scenario added via auto-merge | - |不适用（仅供参考） REV-D007 |警告|场景标记为@deprecated | 3 |是（添加弃用标记） ** ** #### 6.9 漂移确认工作流程 When drift is flagged but no BDD update is needed: 1. Run `/doc-bdd-fixer BDD-01 --acknowledge-drift` 2. Fixer prompts: "Review drift for EARS-01.md?" 3. User confirms no BDD changes needed 4. Fixer adds to `acknowledged_drift` array 5. Future reviews skip this drift until upstream changes again ** ** ## 命令用法 ### 基本用法 # 根据最新评论修复 BDD /doc-bdd-修复程序 BDD-01 # 修复明确的审查报告（遗留） /doc-bdd-fixer BDD-01 --review-report BDD-01.R_review_report_v001.md # 使用明确的审计报告修复（首选） /doc-bdd-fixer BDD-01 --review-report BDD-01.A_audit_report_v001.md # 修复并重新运行审核 /doc-bdd-fixer BDD-01 --重新验证 # 修复迭代限制 /doc-bdd-fixer BDD-01 --revalidate --max-iterations 3 ### 选项选项 |默认 |描述 ---|---|--- `--审查报告` |最新 |要使用的特定审计/审查报告（首选`.A_audit_report`） `--重新验证` |假 |修复后运行审阅者 `--最大迭代次数` | 3 |最大修复审查周期 `--修复类型` |全部 |特定修复类型（以逗号分隔） `--创建缺失` |真实|创建缺失的参考文件 `--备份` |真实|修复前备份BDD `--试运行` |假 |预览修复而不应用 `--承认漂移` |假 |交互式漂移确认模式 `--更新漂移缓存` |真实|修复后更新 .drift_cache.json `--修复功能` |真实| Also fix linked .feature files **报告选择优先级**： 1. 按时间戳选择最新报告。 2. If timestamps are equal, prefer `BDD-NN.A_audit_report_vNNN.md` over `BDD-NN.R_review_report_vNNN.md`. ### 修复类型类型 |描述 ---|--- `丢失的文件` | Create missing glossary, step defs, feature files `损坏的链接` |修复链接路径 `element_ids` |转换无效/旧元素 ID `内容` | Fix placeholders, dates, names `参考文献` |更新可追溯性和交叉引用 ‘漂移’ |处理上游漂移检测问题 `小黄瓜` | Fix Gherkin syntax issues (limited) `全部` |所有修复类型（默认） ** ** ## 输出工件 ### 修复报告 **嵌套文件夹规则**：所有 BDD 套件都使用嵌套文件夹 (`BDD-NN_{slug}/`)。修复报告与 BDD 功能文件一起存储在嵌套文件夹中。 **File Naming** : `BDD-NN.F_fix_report_vNNN.md` **位置**：在 BDD 嵌套文件夹内：`docs/04_BDD/BDD-NN_{slug}/` **结构**： --- title: "BDD-NN.F: Fix Report v001" 标签： - BD - 修复报告 - 质量保证自定义字段： document_type：修复报告工件类型：BDD-FIX 层数：4 parent_doc: BDD-NN source_review: BDD-NN.A_audit_report_v001.md fix_date: "YYYY-MM-DDTHH:MM:SS" fix_tool: doc-bdd-fixer 修复版本：“1.0” --- # BDD-NN Fix Report v001 ## 总结 |公制|价值| |--------|--------| |来源评论 | BDD-NN.A_audit_report_v001.md（或旧版“BDD-NN.R_review_report_v001.md”）| |审查中的问题 | 12 | 12 |已解决的问题 | 10 | 10 |剩余问题 | 2（需要人工审核）| |文件已创建 | 3 | |文件修改 | 5 | |功能文件已修复 | 2 | ## 文件已创建 |文件|类型 |地点 | |------|------|----------| | BDD-00_GLOSSARY.md |行为术语|文档/04_BDD/ | | BDD-01_STEP_DEFS.md | Step Definitions Placeholder | docs/04_BDD/ | | auth_placeholder.feature | Feature Placeholder | tests/bdd/features/ | ## 应用的修复 | ＃|问题代码 |问题 |修复已应用 |文件| |---|------------|--------|-------------|-----| | 1 | REV-L001 |损坏的词汇表链接 | Created BDD-00_GLOSSARY.md | BDD-01.3_scenarios.md | | 2 | REV-L004 |耳朵断了参考| Updated path to ../03_EARS/EARS-01.md | BDD-01.1_core.md | | 3 | REV-N004 |元素类型 01 无效 | Converted to type 35 | BDD-01.1_core.md | | 4 | REV-L005 | Broken feature file link | Created auth_placeholder.feature | BDD-01.2_features.md | ## 功能文件修复 |文件|应用修复| |------|----------------| | auth.feature | Added @trace tag, fixed step reference | | api.feature | Updated Examples table format | ## 需要人工审核的问题 | ＃|问题代码 |问题 |地点 |原因 | |---|------------|--------|----------|--------| | 1 | REV-B001 | Missing Gherkin keyword | BDD-01.2：L45 |需要场景语法 | | 2 | REV-B003 |缺少给定/何时/那么 | auth.feature:L32 |所需的阶梯结构 | ## 修复后验证 |公制|之前 |之后|达美航空 | |--------|--------|--------|--------| |评论分数 | 92 | 92 97 | 97 +5 | |错误 | 2 | 0 | -2 | |警告| 4 | 1 | -3 | ## 后续步骤 1. Complete BDD-01_STEP_DEFS.md placeholder 2. 在适当的场景下完成auth_placeholder.feature 3. 解决标记场景中缺失的 Gherkin 关键字问题 4. 运行“/doc-bdd-reviewer BDD-01”来验证修复 ** ** ## 与自动驾驶仪集成该技能由 Review -> Fix 周期中的 doc-bdd-autopilot 调用：流程图LR 子图 Phase5[“第 5 阶段：审查和修复周期”] A[doc-bdd-reviewer] --> B{分数 >= 85?} B -->|否| C[doc-bdd-fixer] C --> D{迭代 < 最大值？} D -->|是|一个 D -->|否| E[手动审核标志] B -->|是| F[通过] 结束 **自动驾驶仪集成点**：相|行动|技能 ---|---|--- 5a 阶段 |进行初步审查 | `doc-bdd-审稿人` 5b 阶段 |如果发现问题，请应用修复程序 | `doc-bdd-修复程序` 5c 阶段 |重新运行审核 | `doc-bdd-审稿人` 5d 阶段 |重复直到通过或最大迭代 |循环 ** ** ## 错误处理 ### 恢复行动错误 |行动 ---|--- 未找到审计/审查报告 |提示先运行 `doc-bdd-audit` 或 `doc-bdd-reviewer` 无法创建文件（权限）|记录错误，继续其他修复无法解析审计/审查报告 |中止并显示明确的错误消息超出最大迭代次数 |生成报告、标记以供手动审核未找到耳朵 |记录警告，跳过依赖于 EARS 的修复特征文件解析错误 |记录错误，跳过对该文件的 Gherkin 修复 ### 备份策略在应用任何修复之前： 1. 在 `tmp/backup/BDD-NN_YYYYMMDD_HHMMSS/` 中创建备份 2. 将所有BDD文件和链接的功能文件复制到备份位置 3. 对原始文件应用修复 4. 如果修复过程中出现错误，请从备份恢复 ** ** ## 相关技能技能|关系 ---|--- `doc-bdd-审计` |首选组合审计源（输入） `doc-bdd-审稿人` |提供审查报告（输入） `doc-bdd-自动驾驶仪` |协调审核 -> 修复周期 `doc-bdd-验证器` |结构验证 `文档命名` |元素 ID 标准 `doc-bdd` | BDD创建规则 `doc-ears-审阅者` |上游 EARS 验证 ** ** ## 版本历史版本 |日期 |变化 ---|---|--- 2.2 | 2.2 2026-02-27 |将 frontmatter 迁移到“元数据”；添加了“BDD-NN.A_audit_report_vNNN.md”（首选）与旧版“BDD-NN.R_review_report_vNNN.md”的兼容性；定义的确定性优先级（最新时间戳，然后“.A_”优先于“.R_”） 2.1 | 2.1 2026-02-11 | **结构合规性**：添加了用于嵌套文件夹规则实施的阶段 0 (REV-STR001-STR003)；在其他修复阶段之前首先运行 2.0 | 2026-02-10 |增强第 6 阶段，具有分层自动合并系统；添加了 Tier 1 (< 5%) 自动与补丁版本合并；添加了第 2 层 (5-15%) 自动合并，包含详细的变更日志和次要版本；添加了第 3 层 (> 15%) 存档和主要版本的重新生成；使用@deprecated标记实施不删除政策；添加了存档清单创建；增强了带有合并历史记录的漂移缓存；添加场景标签模式@BDD-NN-SC-SS；将 EARS 定义为上游，ADR 定义为下游 1.0 | 2026-02-10 |初始技能创造； 6 阶段修复工作流程；术语表、步骤定义和功能文件创建； BDD代码的元素ID转换（35、36、37）；修复了损坏的链接，包括功能文件； EARS漂移检测； Gherkin 语法验证；与自动驾驶仪集成审核->修复周期 ## 实施计划一致性 (IPLAN-004) * 将计划派生的输出视为有效的源模式，并验证实施计划范围/目标的意图保留。 * 验证上游自动驾驶仪优先级假设：`--iplan > --ref > --prompt`。 * 将计划上下文和工件输出之间的目标/范围冲突标记为需要澄清的阻塞问题。 * 不要引入旧的后备路径，例如“docs-v2.0/00_REF”。

Doc Bdd 修复程序

包含技能