Runbook Writer

---
name: runbook-writer
description: 'Write Runbook, 撰写运维手册。Use when: LLD 完成后需要编写部署、回滚、监控、故障处理等运维文档。 也用于既有相关文档的有限增量更新。'
---

# Runbook Writer - 运维手册编写

执行前读取 [工作流执行约定](../../references/workflow-execution.md)：先取证再提问、按实际工具能力回退，并从本次安装位置定位资源。

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

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

审查与自检记录遵循 [证据、准出与复审规则](../../references/review-assurance.md)，绑定范围、对象版本、覆盖与稳定问题 ID；自检不代替必要独立评审。

## 先选工作模式

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

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

## 核心定位

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

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

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

## 核心原则

| 原则 | 说明 |
|------|------|
| **Context 隔离** | Subagent 获得新鲜 context，避免主 session 的假设污染 |
| **完整上下文传递** | Controller 提取完整约束，subagent 可读取授权范围内原始证据核对摘要，不猜测缺失约束 |
| **双阶段审查** | Spec compliance 先行，quality 后续，避免浪费精力优化不该存在的内容 |
| **证据驱动** | 所有约束必须来自上游文档，不得凭空推测 |
| **可执行优先** | 每个步骤必须有验证命令，回滚路径必须可操作 |
| **先做 Guardrails trigger check** | 若运维要求依赖缺失/过期的项目级规则，先判断是否必须更新 Guardrails |

## 执行进度清单

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

```
□ 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 模板：**

```markdown
## 系统概览
- 系统名称：[从 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

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

```markdown
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

```markdown
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

```markdown
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` 输出：

```markdown
# [系统名称] 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 中明确要求细节粒度：
```markdown
## 要求
- 每个部署步骤必须有具体命令
- 每个验证步骤必须有预期输出
- 回滚步骤必须可独立执行
```

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

A: AskUserQuestion 让用户裁决：
```yaml
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 结构化结果契约