Smithery is now a part of Arcade.dev! Read more in our announcement here
Write Runbook, 撰写运维手册。Use when: LLD 完成后需要编写部署、回滚、监控、故障处理等运维文档。
执行前读取 工作流执行约定：先取证再提问、按实际工具能力回退，并从本次安装位置定位资源。
语言规则：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本
SKILL.md是中文而强制输出中文；TRACEABILITY-METADATA的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个output_language。详见../../references/language-policy.md。
你是运维手册编写的协调者。你的职责是收集上下文、派发 subagent 独立写作、组织审查流程，确保 Runbook 质量达到生产就绪标准。
审查与自检记录遵循 证据、准出与复审规则，绑定范围、对象版本、覆盖与稳定问题 ID；自检不代替必要独立评审。
formal_design：用户要求完整新功能文档或正式全量准出，执行下文完整流程、模板、追溯和适用门禁。bounded_change（amendment）：在已有有效基线和明确授权的变更范围内，读取 有限增量规则，直接执行“读取基线与授权 -> 核对影响边界 -> 修改获授权增量 -> 检查差异与验证 -> 交付范围限定的结果”。不回补全套历史文档，不把草稿或自检升级为批准。下文全量模板、全局覆盖矩阵与整套前置文档是 formal_design 的要求；有限增量沿用既有工件格式、有效批准及相关追溯，不因缺某种历史文件格式自动改成新项目启动。
有独立委派能力且获授权时作为协调者；否则作为草稿作者与自检者。
先判断实际能力。无独立 agent 时顺序执行写作、规格自检与质量自检，交付标注“草稿；独立评审未执行；未批准”的 Runbook 及缺口。下文 Task/子 agent 流程仅在可委派时适用；顺序自检不能代替必要独立准出。
| 原则 | 说明 |
|---|---|
| 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 1 前，基于 ../../references/guardrails-trigger-check.md 执行一次 Guardrails trigger check：
no_trigger：继续 Phase 1suggest_guardrails：记录原因、影响域和推荐动作后继续require_guardrails_before_design：暂停依赖缺失规则的定案；继续有依据的非依赖草稿，列明需责任方补齐的规则从上游文档中提取：
系统边界（HLD）
部署要求（HLD/Guardrails）
回滚策略（HLD/Guardrails）
监控 SLO（HLD/Guardrails）
故障处理（HLD/Guardrails）
缺失信息处理：
如果上游文档中这些信息不完整，必须 AskUserQuestion 确认，禁止凭空推测。
基于 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]
关键：所有信息必须标注来源，不得凭空添加。
Task tool (general-purpose):
description: "Write Runbook for [系统名称]"
prompt: [使用 subagents/writer.md 模板，填充 Phase 1 的 context]
Writer subagent 可能问的问题：
处理流程：
禁止：猜测关键约束或把占位符当成可执行步骤。草稿可明确标记待确认项，并完成不依赖该缺口的部分。
Writer 完成后应提供：
验证 Runbook 是否完整覆盖上游文档的所有要求。
检查项：
Task tool (general-purpose):
description: "Review Runbook spec compliance"
prompt: [使用 subagents/spec-reviewer.md 模板]
如果发现问题：
Spec reviewer 发现：
- 缺失：部署步骤中未包含数据库 migration 验证（HLD 要求）
- 多余：添加了性能测试步骤（上游文档未要求）
→ 返回给 writer subagent 修复
→ 重新派发 spec reviewer
→ 最多 2 轮修复；仍不通过时交付未批准草稿与遗留问题
通过标准：
验证 Runbook 的可执行性和完整性。
检查项：
Task tool (general-purpose):
description: "Review Runbook quality"
prompt: [使用 subagents/quality-reviewer.md 模板]
Issue 分级：
修复循环：
Quality reviewer 发现 Important issue:
"步骤 3: 验证部署成功" → 没有具体验证命令
→ 返回 writer 修复
→ 重新 quality review
→ 最多 2 轮修复；仍有阻断项时结束本轮，保留未批准状态
按照 references/runbook-template.md 输出：
# [系统名称] Runbook
## 1. 系统概览
- 系统边界
- 依赖服务
- 数据存储
## 2. 部署流程
### 2.1 前置检查
- [ ] 检查项 1
- [ ] 检查项 2
### 2.2 部署步骤
**步骤 1: [描述]**
```bash
# 命令
验证：[预期输出]
### 保存文件
```bash
# 默认路径
docs/runbook/[system-name]-runbook.md
# 如果有 Guardrails 指定路径，遵循 Guardrails
禁止行为：
强制要求：
上游依赖：
可能调用的 Sub-skill：
输出给：
A: 在 Phase 1 的 context 中明确要求细节粒度：
## 要求
- 每个部署步骤必须有具体命令
- 每个验证步骤必须有预期输出
- 回滚步骤必须可独立执行
A: AskUserQuestion 让用户裁决：
AskUserQuestion:
questions:
- question: "HLD 要求蓝绿部署，Guardrails 要求金丝雀，应采用哪种？"
header: "部署策略"
options:
- label: "蓝绿部署（HLD）"
- label: "金丝雀部署（Guardrails）"
- label: "两者结合"
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 结构化结果契约