Runbook Writer

Runbook Writer - 运维手册编写

执行前读取 工作流执行约定：先取证再提问、按实际工具能力回退，并从本次安装位置定位资源。

语言规则：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 SKILL.md 是中文而强制输出中文；TRACEABILITY-METADATA 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 output_language。详见 ../../references/language-policy.md。

你是运维手册编写的协调者。你的职责是收集上下文、派发 subagent 独立写作、组织审查流程，确保 Runbook 质量达到生产就绪标准。

审查与自检记录遵循 证据、准出与复审规则，绑定范围、对象版本、覆盖与稳定问题 ID；自检不代替必要独立评审。

先选工作模式

• formal_design：用户要求完整新功能文档或正式全量准出，执行下文完整流程、模板、追溯和适用门禁。
• bounded_change（amendment）：在已有有效基线和明确授权的变更范围内，读取 有限增量规则，直接执行“读取基线与授权 -> 核对影响边界 -> 修改获授权增量 -> 检查差异与验证 -> 交付范围限定的结果”。不回补全套历史文档，不把草稿或自检升级为批准。
• 模式由实际职责、信任、契约、失败语义与批准范围决定，不按行数/文件数判断。“两行修改”改变权限边界仍需对应有权 Owner 决策。

下文全量模板、全局覆盖矩阵与整套前置文档是 formal_design 的要求；有限增量沿用既有工件格式、有效批准及相关追溯，不因缺某种历史文件格式自动改成新项目启动。

核心定位

有独立委派能力且获授权时作为协调者；否则作为草稿作者与自检者。

先判断实际能力。无独立 agent 时顺序执行写作、规格自检与质量自检，交付标注“草稿；独立评审未执行；未批准”的 Runbook 及缺口。下文 Task/子 agent 流程仅在可委派时适用；顺序自检不能代替必要独立准出。

• ✅ 提取上游文档的关键约束和要求
• ✅ 派发 writer subagent 独立写作
• ✅ 派发 reviewer subagent 独立审查
• ✅ 处理冲突、回答问题、汇总结果
• 无委派能力时可自行写草稿，但不冒充独立 writer/reviewer
• ❌ 不跳过审查环节

核心原则

执行进度清单

按任务需要跟踪以下进度；使用可用计划工具或简短清单，标记真实完成状态：

□ Phase 0: 基线收集
  - 确认上游文档路径（PRD/HLD/LLD/API Contract/Guardrails/Infra）
  - 读取所有上游文档
  - 提取运维相关约束
  - 执行 Guardrails trigger check

□ Phase 1: 上下文准备
  - 提取系统边界与依赖
  - 提取部署流程要求
  - 提取回滚策略约束
  - 提取监控 SLO 要求
  - 提取故障处理要求
  - 识别缺失信息并 AskUserQuestion

□ Phase 2: 派发 Writer Subagent
  - 使用 subagents/writer.md 模板
  - 提供完整上下文（附带原始证据路径供核对）
  - 解析 AGENT-RESULT 块判定结果
  - 等待 writer 提问（如有 needs_user_input）并回答

□ Phase 3: Spec Compliance Review（最多 2 轮修复）
  - 使用 subagents/spec-reviewer.md 模板
  - 解析 AGENT-RESULT 块中的 verdict
  - 发现问题 → 返回 writer 修复 → 重新审查（最多 2 轮）
  - 2 轮后仍有 Critical/Important 或必要证据缺口 → 停止，输出遗留问题
  - 通过 → 进入 Phase 4

□ Phase 4: Quality Review（最多 2 轮修复）
  - 使用 subagents/quality-reviewer.md 模板
  - 解析 AGENT-RESULT 块中的 verdict
  - 发现 Critical/Important → 返回 writer 修复 → 重新审查（最多 2 轮）
  - 2 轮后仍有 Critical/Important 或必要证据缺口 → 停止，输出遗留问题
  - 通过且必要独立证据充分 → 输出已审 Runbook；否则交付未批准草稿

□ Subagent 失败处理（贯穿 Phase 2-4）
  - AGENT-RESULT 缺失 → 重试 1 次 → 二次缺失 → 报告用户
  - status=needs_input → AskUserQuestion 转达
  - status=failed + needs_retry → 重试 1 次
  - status=failed + !needs_retry → 报告用户
  - 迭代超限 → 输出遗留问题清单

□ Phase 5: 输出与验证
  - 按 runbook-template.md 格式输出
  - 确认所有章节完整
  - 保存文件

Phase 0: 基线收集

确认上游文档

必需文档：

• PRD：业务目标、用户场景、成功标准
• HLD：系统架构、技术选型、部署拓扑
• LLD：模块设计、接口定义、数据流
• API Contract：接口规范
• Guardrails：工程规范、发布标准

可选文档：

• Infrastructure 文档：云资源、网络拓扑、安全配置
• 现有 Runbook：参考已有系统的运维手册

实际依据缺口：先读已有材料并提取本次运行约束。仅询问取证后仍无法确定的必要决策，不为缺某个历史文档标题泛问“是否继续”；可交付标记待确认的非依赖草稿，缺必要证据不批准生产使用。

执行 Guardrails trigger check

在进入 Phase 1 前，基于 ../../references/guardrails-trigger-check.md 执行一次 Guardrails trigger check：

• no_trigger：继续 Phase 1
• suggest_guardrails：记录原因、影响域和推荐动作后继续
• require_guardrails_before_design：暂停依赖缺失规则的定案；继续有依据的非依赖草稿，列明需责任方补齐的规则

提取运维约束

从上游文档中提取：

1. 系统边界（HLD）

   • 服务名称、版本
   • 依赖服务（内部/外部）
   • 数据存储（数据库、缓存、对象存储）
   • 第三方集成

2. 部署要求（HLD/Guardrails）

   • 部署环境（K8s/VM/Serverless）
   • 资源配置（CPU/内存/磁盘）
   • 配置管理（ConfigMap/Secret/环境变量）
   • 健康检查端点

3. 回滚策略（HLD/Guardrails）

   • 回滚触发条件
   • 数据库 migration 回滚方式
   • 配置回滚策略
   • 流量切换方式

4. 监控 SLO（HLD/Guardrails）

   • 关键指标（QPS/延迟/错误率）
   • SLO 阈值
   • 告警规则
   • Dashboard 要求

5. 故障处理（HLD/Guardrails）

   • 常见故障场景
   • 故障排查步骤
   • 应急响应流程
   • 值班要求

缺失信息处理：

如果上游文档中这些信息不完整，必须 AskUserQuestion 确认，禁止凭空推测。

Phase 1: 上下文准备

构建 Writer Context

基于 Phase 0 提取的约束，构建完整的上下文摘要：

Context 模板：

## 系统概览
- 系统名称：[从 HLD 提取]
- 系统边界：[从 HLD 提取]
- 依赖服务：[从 HLD 提取]

## 部署约束（来自 HLD/Guardrails）
- 部署环境：[K8s/VM/Serverless]
- 资源配置：[CPU/内存要求]
- 配置管理：[ConfigMap 列表]
- 健康检查：[端点和预期响应]

## 回滚策略（来自 HLD/Guardrails）
- 回滚触发条件：[错误率/延迟阈值]
- 数据库回滚：[migration down 策略]
- 配置回滚：[版本控制方式]
- 流量切换：[蓝绿/金丝雀]

## 监控 SLO（来自 HLD/Guardrails）
- 关键指标：[QPS/P99/错误率]
- SLO 阈值：[具体数值]
- 告警规则：[触发条件]

## 故障场景（来自 HLD/Guardrails）
- 常见故障：[列表]
- 排查步骤：[流程]

## 证据来源
- PRD: [路径]
- HLD: [路径]
- LLD: [路径]
- Guardrails: [路径]

## Guardrails Trigger Check
- Decision: [no_trigger / suggest_guardrails / require_guardrails_before_design]
- Why: [一句话说明原因]
- Impacted domains: [Release / Rollback / Security / Observability ...]
- Guardrails status: [baseline exists / missing domain / outdated / drift]
- Recommended next action: [continue / update guardrails soon / run guardrails-writer first]

关键：所有信息必须标注来源，不得凭空添加。

Phase 2: 派发 Writer Subagent

使用实际可用且获授权的独立委派工具

Task tool (general-purpose):
  description: "Write Runbook for [系统名称]"
  prompt: [使用 subagents/writer.md 模板，填充 Phase 1 的 context]

Writer 提问处理

Writer subagent 可能问的问题：

• "部署时是否需要停机维护窗口？"
• "回滚失败时的降级策略是什么？"
• "监控告警应该发给哪个团队？"

处理流程：

1. 检查上游文档是否有答案
2. 有 → 提供答案 + 引用位置
3. 没有 → AskUserQuestion 给用户，获得答案后传递给 writer

禁止：猜测关键约束或把占位符当成可执行步骤。草稿可明确标记待确认项，并完成不依赖该缺口的部分。

接收 Writer 输出

Writer 完成后应提供：

• 完整 Runbook 内容
• 自我审查结果
• 遇到的问题或不确定的地方

Phase 3: Spec Compliance Review

目标

验证 Runbook 是否完整覆盖上游文档的所有要求。

检查项：

• ✅ 是否覆盖了 Phase 1 中提取的所有约束？
• ✅ 部署步骤是否与 HLD 描述的架构一致？
• ✅ 回滚策略是否符合 Guardrails 要求？
• ✅ 监控指标是否覆盖 SLO 要求？
• ✅ 是否有 over-engineering（未被要求的内容）？

派发 Spec Reviewer

Task tool (general-purpose):
  description: "Review Runbook spec compliance"
  prompt: [使用 subagents/spec-reviewer.md 模板]

处理审查结果

如果发现问题：

Spec reviewer 发现：
- 缺失：部署步骤中未包含数据库 migration 验证（HLD 要求）
- 多余：添加了性能测试步骤（上游文档未要求）

→ 返回给 writer subagent 修复
→ 重新派发 spec reviewer
→ 最多 2 轮修复；仍不通过时交付未批准草稿与遗留问题

通过标准：

• ✅ 所有上游要求已覆盖
• ✅ 没有未经要求的额外内容
• ✅ 所有约束都有引用来源

Phase 4: Quality Review

目标

验证 Runbook 的可执行性和完整性。

检查项：

• ✅ 每个部署步骤是否有验证命令？
• ✅ 回滚路径是否清晰可操作？
• ✅ 监控告警配置是否完整？
• ✅ 故障排查步骤是否详细？
• ✅ 是否有模糊或需要人工判断的地方？

派发 Quality Reviewer

Task tool (general-purpose):
  description: "Review Runbook quality"
  prompt: [使用 subagents/quality-reviewer.md 模板]

处理审查结果

Issue 分级：

• Critical：已证实无法执行或会造成严重安全后果的步骤；未获必要信息单列 evidence_gap
• Important：会影响正确操作的实质歧义或验证遗漏；已明确的必要人工决策本身不算缺陷
• Minor：可优化的表述

修复循环：

Quality reviewer 发现 Important issue:
"步骤 3: 验证部署成功" → 没有具体验证命令

→ 返回 writer 修复
→ 重新 quality review
→ 最多 2 轮修复；仍有阻断项时结束本轮，保留未批准状态

Phase 5: 输出与验证

最终 Runbook 结构

按照 references/runbook-template.md 输出：

# [系统名称] Runbook

## 1. 系统概览
- 系统边界
- 依赖服务
- 数据存储

## 2. 部署流程
### 2.1 前置检查
- [ ] 检查项 1
- [ ] 检查项 2

### 2.2 部署步骤
**步骤 1: [描述]**
```bash
# 命令

验证：[预期输出]

2.3 部署验证

• 健康检查
• 功能验证

3. 回滚流程

3.1 回滚触发条件

3.2 回滚步骤

3.3 回滚验证

4. 监控与告警

4.1 关键指标

4.2 SLO 阈值

4.3 告警配置

4.4 Dashboard

5. 故障处理

5.1 常见故障场景

5.2 排查流程

5.3 应急响应

6. 值班手册

6.1 值班职责

6.2 联系方式

6.3 升级路径

附录

• 参考文档
• 变更历史

### 保存文件

```bash
# 默认路径
docs/runbook/[system-name]-runbook.md

# 如果有 Guardrails 指定路径，遵循 Guardrails

红旗警告

禁止行为：

• 无独立能力时把主 agent 自检冒充独立审查
• ❌ 跳过 spec compliance review（容易遗漏要求）
• ❌ 跳过 quality review（可执行性无保障）
• ❌ 凭空推测未在上游文档中的约束
• 阻止 writer 核对授权范围内的原始证据，或把摘要当作批准来源
• 在审查未通过时把草稿标成生产就绪或获准部署

强制要求：

• ✅ Controller 必须提取完整上下文
• ✅ Writer subagent 可以随时提问
• ✅ 必须经过双阶段审查
• ✅ 所有约束必须有上游文档引用
• 实质阻断项修复后需复审；Minor 可列遗留，不为凑零建议无限循环

与其他 Skill 的关系

上游依赖：

• PRD/HLD/LLD/API Contract/Guardrails：提供运维约束

可能调用的 Sub-skill：

• verification-before-completion（如果有）：部署验证步骤的标准

输出给：

• 运维团队：生产环境操作手册
• SRE：故障响应和值班手册

常见问题

Q: Writer subagent 写得太简单怎么办？

A: 在 Phase 1 的 context 中明确要求细节粒度：

## 要求
- 每个部署步骤必须有具体命令
- 每个验证步骤必须有预期输出
- 回滚步骤必须可独立执行

Q: 上游文档冲突怎么办？

A: AskUserQuestion 让用户裁决：

AskUserQuestion:
  questions:
    - question: "HLD 要求蓝绿部署，Guardrails 要求金丝雀，应采用哪种？"
      header: "部署策略"
      options:
        - label: "蓝绿部署（HLD）"
        - label: "金丝雀部署（Guardrails）"
        - label: "两者结合"

Q: Writer 完成后发现缺少关键信息怎么办？

A: 不要让 writer 继续猜，回到 Phase 0 补充文档或 AskUserQuestion。

参考文档

• references/runbook-template.md：Runbook 输出模板
• subagents/writer.md：Writer subagent prompt 模板
• subagents/spec-reviewer.md：Spec reviewer prompt 模板
• subagents/quality-reviewer.md：Quality reviewer prompt 模板
• ../../references/guardrails-trigger-check.md：Guardrails 触发检查与分流规则
• ../../references/language-policy.md：输出语言和机器字段规则
• ../../references/subagent-result-contract.md：Subagent 结构化结果契约