w5851/doc-implementation

Skill: doc-implementation (主线对齐)

Hard Rules

1. 必须先定位 docs/dev/active/ 中与用户意图最匹配的活动文档，再按该文档主线推进。
2. 默认连续执行，不因小的不确定性中途频繁打断；只有真实阻塞、严重跑偏、或需要用户关键决策时才暂停。
3. 每完成一个任务项都要做主线自省，确认实现仍与活动文档、仓库结构和治理规则一致。
4. 每步完成后都要做与改动类型匹配的验证；没有自动验证手段时必须明确记录“未自动验证”及原因。
5. 任务单状态、实现结果、最终汇报必须一致，不能把未验证内容写成已完成。

触发与启动

用户指令触发

当用户指令的核心意图与以下示例匹配时（不要求完全一致），本 Skill 自动激活：

• 按文档/计划推进：“按文档推进”“按计划文档执行”“根据任务单落地”
• 执行下一步：“执行文档下一步”“继续推进”“做下一个任务”
• 明确引用 Skill：“启动 doc-implementation”“使用主线对齐 Skill”
• 原有触发词：“按文档自动落地，做完汇报”“不要中间打断，除非卡住或跑偏”

启动确认

Skill 激活后，应立即向用户反馈，例如：

“收到指令，已启动 doc-implementation 主线对齐模式。我将根据开发文档自动推进，并在完成后一次性汇总报告。当前活动文档为 docs/dev/active/[文档名称].md。现在开始执行。” 执行期间用户介入：若用户在执行过程中主动发送新指令，Agent 应立即暂停当前任务，评估新指令是否影响主线，并根据用户要求重新规划或继续。任何暂停和重新规划需在最终报告中注明。

需求澄清（如需）

若指令信息不足（例如未指定具体文档），Agent 应先在 docs/dev/active/ 中查找最近且名称最匹配的活动开发文档；若仍无法唯一定位，再主动提问以明确范围：

“在开始前，请确认本次要执行的是哪个活动开发文档？当前默认查找范围为 docs/dev/active/。”

核心指令

1. 定位活动文档：执行前优先读取 docs/dev/active/ 下与用户意图最匹配的活动开发文档，作为当前任务主线；若用户已明确指定文档，则以用户指定为准。
2. 自动推进：按活动文档中的任务顺序连续执行，默认不中途请示；只有在全部完成、出现真实阻塞、或文档与仓库现状明显冲突时才与用户交互。
3. 主线自省：每完成一个任务项（或每 3 步）后，内部检查：
   • 当前实现是否仍与活动文档目标、仓库结构、现有 CI/治理规则一致？
   • 若轻微偏离，自动修正并记录；若严重偏离，立即标记为阻塞并暂停。
   • 自省频率可随任务复杂度动态调整，但至少在每个任务项完成后必须执行一次。
4. 验证与更新：每步完成后执行与改动类型匹配的验证，并同步更新任务单状态（完成/阻塞）及备注。
   • 代码改动：优先运行最小必要范围的测试、构建或静态检查。
   • 文档或治理改动：优先运行与文档治理、链接检查、格式约束相关的现有脚本或 CI 对应检查。
   • 若仓库中不存在对应自动验证手段，必须在记录中明确写出“未自动验证”及原因，不能伪造验证结论。
5. 最终汇总：全部任务结束后，输出包含以下内容的报告：
   • 完成项清单及文件路径
   • 验证结果
   • 与活动开发文档的对齐总览（完全/轻微偏离/严重偏离及处理）
   • 未完成/阻塞项及原因
   • 下一步建议（基于当前活动文档）

阻塞处理

• 允许中断提问的场景：
  • 无法唯一定位 docs/dev/active/ 下的目标文档，且自动判断风险较高
  • 活动文档与当前代码、目录结构、CI 规则或已有实现发生严重冲突，且无法自动修正
  • 需要用户决策方案（提供≤3个选项，并推荐一个）
  • 缺少关键依赖/权限
• 提问格式：说明阻塞点、影响范围（含活动文档影响）、已尝试的自动修正、可选方案，用户决策后继续推进。

质量门禁

• 任务单状态与代码一致
• 关键路径有验证证据
• 不扩 scope，不引入无关改动
• 活动文档一致性：所有实现必须与当前活动开发文档及仓库既有治理规则无冲突，否则需用户确认
• 仓库治理一致性：涉及活动文档时，应遵守 docs/dev/active/ 的现有命名和时效约束，避免引入绕过治理流程的做法

Boundary

• 本 skill 负责“按现有活动文档落地执行”，不负责从零设计任务单；若任务文档缺失或尚未成型，先转 doc-design-from-zero。
• 若只是追加执行事实到台账而非推进任务主线，优先转 doc-exec-log-append。
• 若任务已经完成且用户要做归档，转 doc-archive。