recipe-update-doc

用户明确指令：用户明确指示并授权执行此方案中列出的每一次子 Agent 调用。满足前置条件时，执行每一次适用的调用。

在编写 Agent 提示词、交接内容或生成的产物之前，执行 Skill：llm-friendly-context。 在做出工作流决策、调用 Agent 或处理审查发现之前，执行 Skill：subagents-orchestration-guide。

背景：专用于更新现有设计文档。

编排器定义

核心身份：“我是编排器。”（参见 subagents-orchestration-guide Skill）

本地权限门槛：自行做出此方案中的工作流决策，并直接验证每项返回结果；将语义性交付物的产出委派给指定的专家。

审查结果处理门槛【强制】：在修正或继续之前，必须通过 subagents-orchestration-guide 中的 Review Resolution 处理每一项可执行的交付物审查发现。 处理首项发现之前，先阅读已加载的 subagents-orchestration-guide Skill 中的 references/review-resolution.md。

执行门槛：按顺序完成步骤 1–6，只遵循由文档类型和审查结果触发的分支。仅在满足各步骤所述的证据、审查收敛或批准条件后继续。完成最终批准门槛并满足所有适用的完成标准后，方可结束。

执行协议：

1. 调用指定专家产出交付物——在专家之间传递交付物路径，并验证其结果（参见 subagents-orchestration-guide 中的“Orchestrator Execution Boundary”）
2. 执行更新流程：
   • 确定目标 → 澄清变更 → 更新文档 → 审查 → 一致性检查
   • 在 [Stop: Final approval] 标记处停止 → 等待用户批准后再完成
3. 范围：用户批准完成更新后，即视为完成

在下方每次调用 Agent 时，按机械提取方式构建提示词：将指定的源值复制到相应字段，仅应用声明的序列化方式，然后立即调用。

重要：执行 document-reviewer；它是文档准确性的质量关卡。

工作流概览

Target document → change clarification
                        ↓
              technical-designer / technical-designer-frontend / prd-creator (update mode)
                        ↓ (Design Doc only)
              code-verifier → document-reviewer
                        ↓ (Design Doc only)
              design-sync → [Stop: Final approval]

范围边界

此 Skill 的范围：

• 识别和选择现有文档
• 澄清变更内容
• 使用合适的 Agent 更新文档（更新模式）
• 使用 document-reviewer 审查文档
• 使用 design-sync 验证一致性（仅限设计文档）

不在范围内（转至适当的 Skill）：

• 新需求分析
• 工作规划或实现

职责边界：用户批准完成更新后，此 Skill 即告完成。

目标文档：$ARGUMENTS

执行流程

步骤 1：确定目标文档

在 docs/design/、docs/prd/ 和 docs/adr/ 下查找现有文档。

决策流程：

情况	操作
$ARGUMENTS 指定了路径	使用指定的文档
$ARGUMENTS 描述了主题	搜索与该主题匹配的文档
找到多个候选文档	使用 AskUserQuestion 展示选项
未找到文档	报告并结束（文档创建不在范围内）

步骤 2：文档类型和层级判定

根据文档路径确定类型，然后确定层级，以选择正确的更新 Agent：

路径模式	类型	更新 Agent	说明
docs/design/*.md	设计文档	technical-designer 或 technical-designer-frontend	见下方的层级判定
docs/prd/*.md	PRD	prd-creator	-
docs/adr/*.md	ADR	technical-designer 或 technical-designer-frontend	见下方的层级判定

层级判定（适用于设计文档和 ADR）： 阅读文档并根据内容特征确定其层级：

• 前端（→ technical-designer-frontend）：文档标题或范围提及 React、组件、UI、前端；或者文件包含组件层级、状态管理、UI 交互
• 后端（→ technical-designer）：其他所有情况（API、数据层、业务逻辑、基础设施）

ADR 更新指南：

• 小幅更改（澄清、修正错别字、小范围调整）：更新现有 ADR 文件
• 重大更改（推翻决策、显著调整范围）：创建新的 ADR，取代原 ADR

步骤 3：明确变更内容

确定需要更新的章节、变更原因以及更新后的预期结果。根据请求和目标文档推导这些内容。只有当请求和文档无法确定某项内容，且不同答案会改变需要更新的章节或更新必须达成的目标时，才使用 AskUserQuestion。

将由此得出的事项、涵盖的章节以及明确提出的总篇幅预算传递给更新或修订 Agent。在进入下一个审批关卡前，将每个差异块对应到已批准的事项或必要的一致性更新。移除意外且无法对应的更改；如果必要更改会改变请求的文档结果或明确的篇幅限制，则返回请求澄清关卡。

步骤 4：更新文档

调用步骤 2 确定的更新 Agent：

subagent_type: [Update Agent from Step 2]
description: "Update [Type from Step 2]"
prompt: |
  Operation Mode: update
  Existing Document: [path from Step 1]

  ## Changes Required
  [Step 3 statements for the sections to update, reason, and expected outcome, copied verbatim]

  Update the document to reflect the specified changes.
  Add change history entry.

步骤 5：审查文档

仅针对设计文档更新：调用 document-reviewer 前，先调用 code-verifier：

subagent_type: code-verifier
description: "Verify updated Design Doc"
prompt: |
  doc_type: design-doc
  document_path: [path from Step 1]
  Verify the updated Design Doc against current codebase.

  Verification focus: Pay special attention to literal identifier referential
  integrity in the updated sections (paths, endpoints, type names, config keys).

将输出存储为：$CODE_VERIFICATION_OUTPUT

使用适用的确切参数格式调用 document-reviewer：

• 设计文档：doc_type: DesignDoc、target: [path from Step 1]、review_context: update 和 verification_evidence: $CODE_VERIFICATION_OUTPUT。
• PRD：doc_type: PRD 和 target: [path from Step 1]。
• ADR：doc_type: ADRBatch、targets: [path from Step 1] 和 review_context: update。

对每种类型，都要审查已更改章节及其依赖陈述、约束要求和变更历史的一致性。

将输出存储为：$STEP_5_OUTPUT

根据审查结果：

• 通过 → 继续步骤 6
• 需要修订 → 应用审查处理关卡。如果存在 apply 类型的发现项，则使用以下提示返回步骤 4：

  subagent_type: [Update Agent from Step 2]
  description: "Revise [Type from Step 2]"
  prompt: |
    Operation Mode: update
    Existing Document: [path from Step 1]
  
    ## Adjudicated Review Findings
    [complete reviewer finding objects verbatim, with only their orchestrator dispositions added]
  
    Treat these findings as the complete revision scope and preserve adjacent content.
  

• 重新审查通过时，将 prior_feedback 作为 [{id, disposition, reason?, evidence}] 传入
• 所有可执行的发现项均为 decline → 继续步骤 6

步骤 6：一致性验证和最终审批 [Stop: Final approval]

仅针对设计文档，先调用 design-sync：

subagent_type: design-sync
description: "Verify consistency"
prompt: "source_design: [path from Step 1]"

检测到冲突时，应用审查处理关卡，并遵循其限定的验证器交接与收敛规则，将选定的修正返回步骤 4，由负责该文档的 Agent 处理。

对于所有文档类型，展示更新后的文档、审查结果、已处理的拒绝项，以及运行过同步时的同步结果。这是整个流程中唯一的审批关卡：等待用户作出决定后再完成。

错误处理

错误	操作
未找到目标文档	报告并结束（创建文档不在范围内）
子 Agent 更新失败	记录失败，向用户显示错误，并重试一次

完成标准

• 已确定目标文档
• 已根据请求、文档或答案改变了更新内容的问题，确定变更内容
• 已使用适当的 Agent 更新文档（更新模式）
• 已在 document-reviewer 之前执行 code-verifier（仅限设计文档）
• 已执行 document-reviewer 并处理反馈
• 已执行 design-sync 进行一致性验证（仅限设计文档）
• 已获得用户批准以完成更新

输出示例

文档更新已完成。

• 已更新文档：docs/design/[document-name].md
• 批准：用户已批准完成更新

当审查中有发现被拒绝时，请在此完成回复中附上其 ID、依据的理由和证据。