doc-prd-fixer

doc-prd-fixer

用途

读取最新的审计报告并修复 PRD，在 ../doc-prd-audit/SKILL.md 与通过审计的 PRD 之间搭建桥梁，使审计↔修复循环能够收敛。

层级：2（PRD 质量改进）。 上游：PRD 文档 + .aidoc/audit/02_PRD-audit.md。 下游：修复后的 PRD + PRD-NN.F_fix_report_vNNN.md。

适用场景

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

输入约定

使用 .aidoc/audit/02_PRD-audit.md 报告。编辑前备份 PRD（tmp/backup/PRD-NN_<ts>/）；发生错误时恢复。元素 ID 标准来自 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md；结构规则来自 ${CLAUDE_PLUGIN_ROOT}/framework/layers/02_PRD/PRD-TEMPLATE.yaml 和 README.md。

修复模式

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

团队模式（参见 REVIEW_TEAM.md §Operations §Remediate）

1. 阅读审计报告 .aidoc/audit/02_PRD-audit.md，并且， 如果存在，还要阅读综合器的 verdict.json + 各角色槽位， 位于 .aidoc/review/02_PRD/<PRD-id>/（其中 <PRD-id> 是简短的 工件 ID，例如 PRD-01）。

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

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

   • 单视角问题（1 个角色）：分派该视角。
   • 多视角问题（2 个或更多角色，例如架构师与产品负责人的矛盾）：并行分派所有 列出的视角。每个视角各自写入一个 <persona>.fix_<N>.json 槽位。只有在所有被分派的视角均未返回新的 P0/P1 时，才接受修复（任何一个视角发现回归，都要回退补丁）。
   • 无角色／孤立问题（personas 为空或缺失）： 默认分派 PRD 团队的作者视角（依据 REVIEW_CREWS.yaml：BRD 对应 product_owner）作为责任审查者。回退到作者视角而非跳过，可确保每项阻塞问题至少经过一轮验证。 P2/P3 仅供参考——确定性地应用，无需视角验证。

   PRD 的视角 → Agent 映射：

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

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

4. 验证无回归。 对于步骤 2 中确定的每个责任视角，以补丁验证模式分派一个 Task 子 Agent： subagent_type=<mapped agent>（使用上面的映射）；任务说明 = 修补后的区域 + 原始问题 + 补丁差异；视角不得读取、引用或将任何作者自评评分纳入权重（*_ready_score/*_score/readiness_score/audit_score），以此形成其 lens_score （REVIEW_TEAM.md GD-05）；输出 = 一条新的角色输出记录（修补区域的 lens_score + 任何新问题）。 将每个视角的输出保存为 .aidoc/review/02_PRD/<PRD-id>/<persona>.fix_<N>.json（<N> = 按顺序递增的修复迭代计数器，从 1 开始）。多视角问题针对同一个 <N>，每个责任视角各生成一个槽位文件。

5. 回退回归。 如果任何视角在补丁上发现新的 P0/P1，则回退该补丁，并将原始问题标记为 manual_required。绝不能悄悄保留导致回归的修复。

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

single_pass 模式（回退模式）

直接独立执行 Phase 0–7，不进行视角验证。保持原有行为不变——当配置文件如此指定、Task 子代理调度不可用，或不存在插槽时，必须使用此模式。

两种模式下，P2/P3 建议性问题都会直接应用，不进行视角验证；仅阻塞性问题（P0/P1）会在团队模式下进入补丁验证循环。

Saga 交互

由 doc-prd-autopilot 调用（或直接调用）时，此技能会根据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md 读取并更新 saga 日志 .aidoc/review/02_PRD/<PRD-id>/saga.json。修复器作为 saga 的修复阶段：补丁验证期间将分支转换为 BRANCH_COMPENSATING，之后再转换为 BRANCH_COMPLETED（验证通过）或 BRANCH_FAILED（检测到回归）。

进入时

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

Bash: mkdir -p .aidoc/review/02_PRD/<PRD-id>/ && date +%s > .aidoc/review/02_PRD/<PRD-id>/.skill-start.fixer

如果 .aidoc/review/02_PRD/<PRD-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/02_PRD/<PRD-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-prd-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/02_PRD/<PRD-id>/saga.json 不存在（用户在 autopilot 循环之外直接运行 /aidoc-flow:doc-prd-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 — 结构	嵌套文件夹规则	将 PRD 移至 docs/02_PRD/PRD-NN_{slug}/；重命名文件夹以匹配 ID；移动后修复 ../01_BRD/ → ../../01_BRD/ 相对链接
1 — 缺失文件	有引用但不存在	根据模板创建术语表 / 附录 / 参考资料占位文件
2 — 链接	失效 / 绝对路径	重新计算相对路径；将绝对路径转换为相对路径
3 — 元素 ID	旧版 / 无效 ID	重新生成 PRD.NN.SS.xxxx（章节编号 + 内容哈希）；移除旧版 PRD.NN.xxxx、FR-XXX/US-XXX/AC-XXX/F-XXX 前缀；修复 SS 与所在章节不匹配的问题
4 — 内容	占位内容、缺失的子章节	填写模板日期；原位搭建 §10 / §14 / §8 结构；将 [TODO]/[TBD] 标记为需人工完成
5 — 参考	可追溯性	添加缺失的 @brd:/@prd: 标签；修复跨 PRD 路径；更新可追溯性矩阵和父级 BRD 下游条目
6 — 上游	元数据 + 偏移	修复 deliverable_type/document_type；应用分级 BRD 偏移合并策略（见下文）
7 — 风格	STY01 禁用短语、STY02/03 过长文案、FM01 frontmatter 不匹配	替换填充语（in order to → to；删除 the fact that、it should be noted、please note）；替换标记出的最高级表达；将包含 ≥ 3 个禁用短语的段落压缩为项目符号；协调 frontmatter 与 Document Control 行；STY02/03 — 在第一个自然子标题处自动拆分 > 300 个单词的章节，否则标记为 manual_required。权威依据：${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

元素 ID 重新生成： PRD.{doc_id}.{section_id}.{hash} — 分配一个 稳定的 4 位十六进制字符标识符，在其所在章节内保持唯一（HASH01）；发生冲突时扩展至 8 位。此处不要计算 SHA-256：哈希格式是由确定性工具流程生成的规范化目标，字节级精确字段提取仅对 BRD §7 有定义（PRD 从阶段 2 起）。保留现有有效 ID — 重新生成会破坏所有下游引用。 权威依据：framework/governance/ID_NAMING_STANDARDS.md。section_id = 元素所在的章节。文档级引用 （SPEC-NN、ADR-NN、IPLAN-NN）保持连字符格式。

分级上游偏移（BRD 来源）：变更 <5% → 第 1 级自动合并（补丁版本升级）；5–15% → 第 2 级自动合并 + 详细变更日志（次版本升级）；>15% → 第 3 级归档当前版本 + 通过 autopilot 重新生成（主版本升级）。切勿删除上游已移除的内容 — 标记为 [DEPRECATED] 并保留以供追溯。 将结果记录在 .drift_cache.json 中。

置信度分类

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

置信度	含义
auto-safe	确定性操作，语义风险低（链接 / 路径、标题规范化、ID 转换）
auto-assisted	带有部分假设的模板插入（搭建表格 / 子章节）
manual-required	无法推断领域内容（未解决的 TODO/TBD、§10 消息内容、用户画像详情）

内容保留规则

• 切勿删除现有产品内容；仅在缺少章节或结构未达到最低要求时插入模板块。
• 就地规范等效标题，不要重复创建章节。
• 仅在同一章节文件内重新编号；如果交叉引用锚点可能失效，请标记。
• 对于图示契约问题，仅编辑图示声明和 Mermaid 块，绝不更改需求内容。

修复报告格式

表格竖线转义（MD056）

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

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

对所有在表格单元格中生成带有 shell 管道符代码片段的报告行应用此规则。导致 MD056 的级联输出属于 SKILL 缺陷，而不是 markdownlint 过于严格——应在此处修复，而非通过忽略 lint 来规避。

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

适配

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

相关资源

• 审计（输入）：../doc-prd-audit/SKILL.md · 创建：../doc-prd/SKILL.md
• 编排：../doc-prd-autopilot/SKILL.md · ID：../doc-naming/SKILL.md
• 权威文件：${CLAUDE_PLUGIN_ROOT}/framework/layers/02_PRD/PRD-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md