doc-ears-fixer

doc-ears-fixer

用途

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

层级：3（EARS 质量改进）。 上游：EARS 文档 + .aidoc/audit/03_EARS-audit.md。 下游：修复后的 EARS + EARS-NN.F_fix_report_vNNN.md。

适用场景

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

输入约定

使用 .aidoc/audit/03_EARS-audit.md 报告。编辑前备份 EARS （tmp/backup/EARS-NN_<ts>/）；出错时恢复。元素 ID 标准见 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md；结构和语法 规则见 ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-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/03_EARS-audit.md，并在存在时阅读 .aidoc/review/03_EARS/<EARS-id>/ 下按角色划分的槽位（其中 <EARS-id> 是简短的产物 ID，例如 EARS-01）。

   • 对于结构化发现（稳定 ID、优先级、位置、建议），优先使用按角色划分的槽位。
   • 槽位为可选项——若不存在（例如，single_pass 运行未生成综合器输出），则直接解析审计报告中的 Findings 章节。

2. 为每项发现确定负责的视角。 每项阻塞性发现（P0 + P1）在综合器的精简格式中都包含 personas 数组，或者可根据各视角槽位的归属推断。分派规则：

   • 单视角发现（1 个角色）：分派该视角。
   • 多视角发现（2 个或以上角色）：并行分派所有列出的视角。每个视角分别写入自己的 <persona>.fix_<N>.json 槽位。只有在所有已分派视角均未发现新的 P0/P1 时，修复才会被接受（任一视角发现回归都会导致撤销补丁）。
   • 无角色／孤立发现（personas 为空或缺失）：默认分派 EARS 团队的作者视角（根据 REVIEW_CREWS.yaml，EARS 的默认视角为 requirements_specialist）。

   EARS 的视角 → Agent 映射：

   视角	Agent
   requirements_specialist	aidoc-flow:requirements-analyst
   tech_lead	aidoc-flow:solutions-architect
   qa_lead	aidoc-flow:test-architect
   chaos_engineer	aidoc-flow:chaos-engineer
   security_engineer	aidoc-flow:security-engineer

   EARS 团队权重：{requirements_specialist: 35, tech_lead: 25, qa_lead: 20, chaos_engineer: 12, security_engineer: 8}。

   P2/P3 为建议项——无需视角验证，直接确定性地应用。

3. 针对每项阻塞性发现提出并应用补丁。 下文的修复阶段 0–7 描述了补丁形式；两种模式使用相同的目录。先按照现有 Input Contract 进行备份。

4. 验证无回归。 对于步骤 2 中确定的每个负责视角，以补丁验证模式分派一个 Task 子 Agent： subagent_type=<mapped agent>；任务说明 = 已修补区域 + 原始发现 + 补丁差异；形成其 lens_score 时，该视角不得读取、引用或加权任何作者自评得分（*_ready_score/*_score/readiness_score/audit_score）（REVIEW_TEAM.md GD-05）；输出 = 全新的角色输出记录（已修补区域的 lens_score 及任何新发现）。 将每个视角的输出保存为 .aidoc/review/03_EARS/<EARS-id>/<persona>.fix_<N>.json（<N> = 从 1 开始递增的修复迭代计数器）。多视角发现会针对同一个 <N>，为每个负责视角生成一个槽位文件。

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

6. 仅分派一次综合器 （subagent_type=aidoc-flow:synthesizer），在所有补丁完成验证后生成统一修复报告。保存为 EARS-NN.F_fix_report_vNNN.md，其中包含 Fixes Applied 表格以及 Validation Slots 索引。

single_pass 模式（回退方案）

直接单独应用阶段 0–7，不进行视角验证。保持原有行为——当配置文件要求如此、无法分派 Task 子 Agent，或不存在槽位时，必须使用此模式。

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

Saga 交互

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

进入时

进入时，写入修复器的开始时间戳：

Bash: mkdir -p .aidoc/review/03_EARS/<EARS-id>/ && date +%s > .aidoc/review/03_EARS/<EARS-id>/.skill-start.fixer

如果 .aidoc/review/03_EARS/<EARS-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 子 Agent 返回后：
   • 如果补丁通过验证（没有回归）：转换回 BRANCH_COMPLETED。使用验证结果更新 compensation_actions[] 中的最后一条记录。
   • 如果补丁导致回归（视角在已修补区域标记出新的 P0/P1）：转换为 BRANCH_FAILED。将 compensation_actions[] 中最后一条记录的 action 设为 "escalate"。 该问题将变为 manual_required。

分派综合器之前

根据 REVIEW_SAGA.md §“断路策略”——修复器的 检查点边界位于多视角验证分派之间（每项阻塞问题的逐视角验证构成一个边界）。 分派下一项验证之前：

Bash: echo $(( $(date +%s) - $(cat .aidoc/review/03_EARS/<EARS-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-ears-autopilot 的 §3.4 恢复逻辑继续执行。

综合器完成归并后

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

独立调用时（进入时不存在 saga.json）

如果 .aidoc/review/03_EARS/<EARS-id>/saga.json 不存在（用户 在自动化流程之外直接运行 /aidoc-flow:doc-ears-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 §“断路策略”，此技能会在一个检查点边界检查经过的墙上时钟时间：所有逐项发现的修补操作返回后、调用合成器之前。软截止时间为 1500s （ORCHESTRATOR_TIMEOUT=1800s 减去 300s 缓冲时间）。

如果已超过软截止时间，则按照上文 §“合成器调用前”中的规定，干净退出并将 saga status: "PARTIAL_TIMEOUT"。修复器的部分进度（已写入的 fix_N.json 槽位）是持久的；恢复后的调用会从断路触发的位置继续。

修复阶段

按顺序运行；后续阶段假定先前阶段已成功。

阶段	范围	代表性操作
0 — 结构	嵌套文件夹规则	将 EARS 移至 docs/03_EARS/EARS-NN_{slug}/；重命名文件夹以匹配 ID；移动后修复相对链接
1 — 缺失文件	引用但不存在的文件	根据模板创建术语表／参考占位文件
2 — 链接	失效／绝对路径	重新计算相对路径；将绝对路径转换为相对路径；修复上游 BRD/PRD 链接
3 — 元素 ID	旧版／无效 ID	重新推导 EARS.NN.SS.xxxx（章节编号 + 内容哈希）；移除旧版 EARS.NN.xxxx、数字类型代码（.25/.26）、Event-XXX/State-XXX/UB-XXX/REQ-XXX 前缀
4 — 内容	占位符、语法	填写模板日期；就地规范标题；标记缺少 SHALL 关键词、WHEN-THE-SHALL 结构有误、缺少触发条件、时间表述模糊、复合（非原子）陈述，以供人工审查；标记 [TODO]/[TBD]
5 — 引用	可追溯性	添加本层 required_tags 中缺少的标签（依据 LAYER_REGISTRY.yaml 的必要上游契约——EARS 要求 @prd）；修复 @threshold: 格式；将逗号分隔符转换为竖线；更新可追溯性矩阵
6 — 上游	元数据 + 漂移	修复 deliverable_type/document_type；当 upstream_mode: "ref" 时，应用分级漂移合并（如下）
7 — 风格	STY01 禁用短语、STY02/03 过长文本、FM01 前置元数据不匹配	替换填充内容；替换标记出的最高级表述；将段落（同一章节中含 ≥ 3 个禁用短语）压缩为项目符号；协调前置元数据 ↔ 文档控制行；STY02/03 — 在下一个需求边界处分割超过 300 个单词的章节，或标记为 manual_required。权威来源：${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

元素 ID 重新推导： EARS.{doc_id}.{section_id}.{hash} — 分配一个 稳定的 4 位十六进制标识符，在其章节内不重复（HASH01）；发生冲突时扩展至 8 位。此处不要计算 SHA-256：哈希形式是由确定性工具处理生成的规范化目标，且字节精确的字段提取仅针对 BRD §7 定义（EARS 从阶段 2+ 开始）。保留现有的有效 ID——重新推导会破坏所有下游引用。 权威来源：framework/governance/ID_NAMING_STANDARDS.md。章节表示元素类型（陈述还是质量属性）——绝不将旧版序号用作最终段。文档级引用（SPEC-NN、ADR-NN、IPLAN-NN）保持连字符形式。

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

置信度分类

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

置信度	含义
auto-safe	确定性高、语义风险低（链接/路径、标题规范化、ID 转换、逗号→竖线）
auto-assisted	带有部分假设的模板插入（脚手架表格/章节、阈值占位符）
manual-required	无法推断领域内容（缺少 SHALL、非原子拆分、模糊术语量化、未解决的 TODO/TBD）

内容保留规则

• 切勿删除现有需求内容；仅在章节缺失或结构低于最低要求时插入模板块。
• 在原位置规范化等效标题，而不是重复创建章节。
• 重新格式化时保留阈值；仅在同一章节文件内重新编号；如果交叉引用锚点可能失效，则标记出来。

修复报告格式

表格竖线转义（MD056）

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

• **首选：**在代码片段中将竖线转义为 \| — 在 Markdown 查看器中仍会渲染为 |，但不会破坏表格。 示例行：| OP-02 | ... | `docker compose ps \| grep 'Up'` | ... |
• **替代方案：**将代码片段移出表格单元格，并通过脚注或下方段落引用。单元格中则使用纯文本，例如“shell 就绪门槛（见下文）”。

对每个在表格单元格中输出带 shell 竖线代码片段的报告行应用此修复。触发 MD056 的级联输出属于 SKILL 缺陷，并非 markdownlint 过于严格——应在此处修复，而不是忽略 lint 检查。

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

适配

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

相关资源

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