doc-brd-fixer

doc-brd-fixer

用途

读取最新的审计报告并修复 BRD，衔接 ../doc-brd-audit/SKILL.md 与通过审计的 BRD，使审计↔修复循环能够 收敛。

层级：1（BRD 质量改进）。 上游：BRD 文档 + .aidoc/audit/01_BRD-audit.md。 下游：修复后的 BRD + BRD-NN.F_fix_report_vNNN.md。

适用场景

在 doc-brd-audit 返回 FAIL 后，作为“审计 → 修复 → 审计”循环的一部分使用。 不要在没有审计报告时使用（请先运行审计），也不要用于创建新 BRD（请使用 ../doc-brd/SKILL.md / ../doc-brd-autopilot/SKILL.md）。

输入约定

使用 .aidoc/audit/01_BRD-audit.md（.aidoc/ 来源层级）中的最新审计报告。编辑前 备份 BRD（tmp/backup/BRD-NN_<ts>/）；出错时还原。元素 ID 标准来自 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md； 结构规则来自 ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml 和 README.md。

修复模式

从 .aidoc/profile.yaml 中解析 review_mode；若未设置，则根据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md 中的优先级链， 回退至框架默认值 team。其他适配选项（section_toggles）也采用相同的 回退方式。

team mode（参见 REVIEW_TEAM.md §Operations §Remediate）

1. 阅读审计报告 .aidoc/audit/01_BRD-audit.md，以及（如有）综合器的 verdict.json 和位于 .aidoc/review/01_BRD/<BRD-id>/ 的各角色槽位文件（其中 <BRD-id> 是简短的制品 ID，例如 BRD-01）。

   • 对于阻塞问题数量和覆盖范围摘要，优先使用 verdict.json——这是综合器（agents/synthesizer.md）写入的确定性 JSON。
   • 对于结构化问题，优先使用各角色槽位文件——其中包含稳定 ID、优先级、位置和建议。
   • 槽位文件和 verdict.json 均为可选项——若缺失（例如 single_pass 运行未生成综合器输出），则改为直接解析审计报告中的 Findings 部分。

2. 确定每项问题的负责视角。 每项阻塞问题（P0 + P1）都包含综合器精简格式中的 personas 数组（参见 verdict.json:findings[*].personas），也可以根据各视角槽位文件的归属推断。分派规则：

   • 单视角问题（1 个 persona）：分派给该视角。
   • 多视角问题（2 个或更多 persona，例如 architect 与 business_analyst 之间的矛盾）：并行分派给所有列出的视角。每个视角都写入自己的 <persona>.fix_<N>.json 槽位文件。只有在所有被分派的视角均未发现新的 P0/P1 时，才接受修复（任一视角发现回归都会撤销补丁）。
   • 无视角／孤立问题（personas 为空或缺失）：默认分派给 BRD 团队的作者视角（参见 REVIEW_CREWS.yaml：BRD 对应 business_analyst）。回退到作者视角而非跳过，可确保每项阻塞问题至少经过一次验证。 P2/P3 属于建议项——确定性地应用，不进行视角验证。

   BRD 的视角 → Agent 映射：

   视角	Agent
   architect	aidoc-flow:solutions-architect
   business_analyst	aidoc-flow:requirements-analyst
   auditor	aidoc-flow:traceability-auditor
   chaos_engineer	aidoc-flow:chaos-engineer
   security_engineer	aidoc-flow:security-engineer

3. 针对每项阻塞问题提出并应用补丁。 下文的修复阶段 0–7 描述了补丁形式；两种模式使用相同的目录。按照现有输入约定，先备份。

4. 验证是否存在回归。 对于步骤 2 中确定的每个负责视角，以补丁验证模式分派一个 Task 子 Agent：subagent_type=<mapped agent>（映射见上文）；任务说明 = 已修补区域 + 原始问题 + 补丁差异；形成 lens_score 时，该视角不得读取、引用或加权任何作者自评得分（*_ready_score/*_score/readiness_score/audit_score）（参见 REVIEW_TEAM.md GD-05）；输出 = 一条新的 persona-output 记录（包含已修补区域的 lens_score 和任何新问题）。 将每个视角的输出保存为 .aidoc/review/01_BRD/<BRD-id>/<persona>.fix_<N>.json（<N> = 从 1 开始递增的修复迭代计数）。多视角问题在同一个 <N> 下，为每个负责视角生成一个槽位文件。

5. 撤销回归修复。 如果任何视角对补丁提出新的 P0/P1，则撤销该补丁，并将原始问题标记为 manual_required。绝不可悄悄保留导致回归的修复。

6. 仅分派一次综合器（subagent_type=aidoc-flow:synthesizer），在所有补丁完成验证后，生成统一修复报告。将 .aidoc/remediation/01_BRD-fix.md 保存为包含 Fixes Applied 表格和 Validation Slots 索引的文件。

single_pass 模式（回退）

直接独立执行 Phase 0–7，不进行透镜验证。保持旧有行为不变——当配置文件要求如此、无法调度 Task 子代理，或不存在插槽时，必须使用此模式。

在两种模式下，都会应用 P2/P3 建议性发现，无需透镜验证；只有阻塞性发现（P0/P1）会在团队模式下进入补丁验证循环。

Saga 交互

当由 doc-brd-autopilot 调用（或直接调用）时，此技能会按照 ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md 读取和更新 saga 日志： .aidoc/review/01_BRD/<BRD-id>/saga.json。修复器充当 saga 的修复阶段：在补丁验证期间将分支转换为 BRANCH_COMPENSATING，然后转换回 BRANCH_COMPLETED（已验证）或 BRANCH_FAILED（检测到回归）。

进入时

进入时，写入修复器的启动时间戳：

Bash: mkdir -p .aidoc/review/01_BRD/<BRD-id>/ && date +%s > .aidoc/review/01_BRD/<BRD-id>/.skill-start.fixer

如果 .aidoc/review/01_BRD/<BRD-id>/saga.json 存在，则读取。验证当前 saga 的 status 是否为 FANIN_REDUCED（审计后）或 BRANCH_FAILED（先前修复器检测到回归后重新进入）。如果状态不是上述值，记录警告并继续。

多透镜验证期间（团队模式）

对于每个需要透镜验证的阻塞性发现（P0/P1）：

1. 在调度负责的透镜验证器之前：针对发现的 personas[] 列表中的每个透镜，追加一条转换记录： {"ts": "<now>", "from": "BRANCH_COMPLETED", "to": "BRANCH_COMPENSATING", "scope": "branch:<lens>"}。将 branches[<lens>].status 更新为 "BRANCH_COMPENSATING"。在 compensation_actions[] 中追加一条记录： {"ts": "<now>", "branch": "<lens>", "reason": "<finding_id>: <message>", "action": "retry"}。
2. 验证 Task 子代理返回后：
   • 如果补丁通过验证（没有回归）：转换回 BRANCH_COMPLETED。使用验证结果更新 compensation_actions[] 中的最后一条记录。
   • 如果补丁导致回归（透镜在修补区域发现新的 P0/P1）：转换为 BRANCH_FAILED。将 compensation_actions[] 中最后一条记录的 action 设为 "escalate"。该发现变为 manual_required。

断路检查点（多透镜验证调度之间）

根据 REVIEW_SAGA.md §“断路策略”——修复器的检查点边界位于多透镜验证调度之间（每个阻塞性发现的逐透镜验证都构成一个边界）。调度下一次验证之前：

Bash: echo $(( $(date +%s) - $(cat .aidoc/review/01_BRD/<BRD-id>/.skill-start.fixer) ))

如果已用时间 > SOFT_DEADLINE（1500s）：

• 追加转换记录：{"ts": "<now>", "from": "BRANCH_COMPENSATING", "to": "PARTIAL_TIMEOUT", "scope": "run"}。
• 将 saga 的 status 设为 "PARTIAL_TIMEOUT"。保留所有已完成的验证（其 fix_N.json 插槽仍然有效）。将 current_phase 设为 "fixer"，以便恢复执行时知道继续剩余的验证。
• 更新 updated_at。写入 saga.json。正常退出。

剩余验证将在下次调用时根据 doc-brd-autopilot §3.4 的恢复逻辑继续执行。

所有阻塞性发现的补丁均通过验证后

• 追加转换记录：{"ts": "<now>", "from": "BRANCH_COMPENSATING", "to": "BRANCH_COMPLETED", "scope": "run"}（运行级：修复器执行完成）。
• 将 saga 的 status 更新为 "BRANCH_COMPLETED"（autopilot 的下一阶段将为 re-review）。
• 更新 updated_at。写入 saga.json。

独立调用时（进入时没有 saga.json）

如果 .aidoc/review/01_BRD/<BRD-id>/saga.json 不存在（用户在 autopilot 循环之外直接运行 /aidoc-flow:doc-brd-fixer），则不要初始化完整的 saga 架构。记录 saga.json not present; running fixer without saga journal (standalone mode)。按常规执行修复阶段；写入修复报告；跳过所有 saga.json 转换。兼容直接调用技能的旧有方式。

以 single_pass 模式调用时

如果启用了 review_mode: single_pass，修复器会以确定性方式应用补丁，不进行透镜验证，也不写入 saga.json。保留现有行为。

熔断策略

根据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md §“熔断策略”，此技能会在一个检查点边界检查已耗费的墙钟时间：在多视角验证分派之间 （依据 REVIEW_SAGA.md 中的表格）。SOFT_DEADLINE 为 1500s （ORCHESTRATOR_TIMEOUT=1800s 减去 300s 缓冲时间）。

如果已超过软截止时间，则根据上文 §“熔断检查点”，以 saga status: "PARTIAL_TIMEOUT" 状态正常退出。 修复器的部分进度（已写入的 fix_N.json 槽位）会持久保留；恢复调用会从熔断触发的位置继续执行。

修复阶段

按顺序运行；后续阶段假设前面的阶段已成功完成。

阶段	范围	代表性操作
0 — 结构	嵌套文件夹规则	将 BRD 移至 docs/01_BRD/BRD-NN_{slug}/；将文件夹重命名为与 ID 一致；移动后修复相对链接
1 — 缺失文件	被引用但不存在	根据模板创建词汇表／GAP／参考占位文件
2 — 链接	失效／绝对路径	重新计算相对路径；将绝对路径转换为相对路径
3 — 元素 ID	旧版／无效 ID	重新生成 BRD.NN.SS.xxxx（章节编号 + 内容哈希）；移除旧版 BRD.NN.xxxx、数字类型代码、FR-XXX／BO-XXX 前缀
4 — 内容	占位符、缺失的子章节	填写模板日期；原位规范化 MVP 子章节标题；安全地重新编号同级项目；标记 [TODO]／[TBD] 以供手动补全
5 — 参考	可追溯性	添加缺失的 @ref: 标签；修复跨 BRD 路径；更新可追溯性矩阵
6 — 上游	元数据 + 偏差	修复 deliverable_type／document_type／upstream_mode；当 upstream_mode: "ref" 时，应用分级偏差合并（见下文）
7 — 风格	STY01 禁用短语、STY02/03 过长文本、FM01 frontmatter 不匹配	替换填充语（in order to → to；删除 the fact that、it should be noted、please note、as a matter of fact）；替换标记出的最高级表达（amazing、seamless、cutting-edge、state-of-the-art）；将包含 ≥ 3 个禁用短语的段落压缩为项目符号；协调 frontmatter ↔ Document Control ↔ 修订历史行（以 frontmatter 为准）；STY02/03 — 在第一个自然子标题处分割超过 300 词的章节，或标记为 manual_required。依据：${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

元素 ID 重新生成： BRD.{doc_id}.{section_id}.{hash}。此处不要 计算 SHA-256 — 调用生成器：python -m sdd_doc_lint.rehash --compute --doc-id NN --section-id SS --title T --description D （发生冲突时使用 --length 8）。保留现有 ID，除非其格式错误 — 重新生成有效 ID 会破坏所有下游引用。依据：framework/governance/ID_NAMING_STANDARDS.md。 文档级引用（SPEC-NN、ADR-NN、IPLAN-NN）保持连字符形式。

分级上游偏差（仅当 upstream_mode: "ref" 时）：变更 <5% → Tier 1 自动合并（补丁版本递增）；5–15% → Tier 2 自动合并 + 详细变更日志 （次版本递增）；>15% → Tier 3 归档当前版本 + 通过 autopilot 重新生成（主版本递增）。绝不删除上游已移除的内容 — 标记为 [DEPRECATED] 并保留以供追溯。在 .drift_cache.json 中记录结果。

置信度分类

为每项已应用的修复添加标签，并在报告中列出数量：

置信度	含义
auto-safe	确定性高、语义风险低（链接／路径、标题规范化、ID 转换）
auto-assisted	带有部分假设的模板插入（搭建表格／子章节框架）
manual-required	无法推断领域内容（未解决的 TODO/TBD、策略依据）

内容保留规则

• 不得删除现有业务内容；仅在某个章节缺失或低于最低结构要求时插入模板块。
• 在原位置规范化含义相同的标题，不要重复创建章节。
• 仅在同一章节文件内重新编号；如果可能导致交叉引用锚点失效，请标记。

修复报告格式

表格管道符转义（MD056）

生成的 Markdown 表格单元格中，如果包含带有 shell 管道符的代码片段（例如 `docker compose ps | grep 'Up'`），代码片段中未转义的 | 会被 markdownlint 解析为列分隔符，从而触发 MD056（列数不匹配）。有两种修复方法：

• 首选： 在代码片段中将管道符转义为 \| — 在 Markdown 查看器中仍会显示为 |，但不会破坏表格。 示例行：| OP-02 | ... | `docker compose ps \| grep 'Up'` | ... |
• 替代方法： 将代码片段移出表格单元格， 并在表格下方以脚注或段落引用。单元格中仅保留诸如“shell 就绪检查门（见下文）”这样的纯文本。

对表格单元格中包含 shell 管道符代码片段的每一行报告都应用此规则。触发 MD056 的级联输出是 SKILL 缺陷，并非 markdownlint 过于严格 — 应在此处修复，而不是忽略 lint 错误。

编写 BRD-NN.F_fix_report_vNNN.md，包含：摘要（问题总数／已修复／剩余；创建／修改的文件）· 已应用的修复（代码、问题、修复、文件、置信度）· 人工审核队列 · 修复后验证（修复前→修复后的评分／错误／警告）· 清理摘要（删除已被取代的修复报告）· 后续步骤（重新运行 doc-brd-audit）。循环执行，直到评分 ≥ 阈值或达到最大迭代次数。

适配

应用修复前，请阅读项目适配配置文件 （.aidoc/profile.yaml）。遵循 section_toggles：不要重新引入项目已关闭的可选章节。忽略任何未知或超出适用范围的键。 权威依据：${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

相关资源

• 审计（输入）：../doc-brd-audit/SKILL.md · 创建：../doc-brd/SKILL.md
• 编排：../doc-brd-autopilot/SKILL.md · ID：../doc-naming/SKILL.md
• 权威依据：${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md