用途
create-runbook 用于在用户要求记录某个操作流程、编写 runbook、创建运维指南，或记录如何处理特定场景时，生成一份运维手册（runbook）。手册面向在压力下执行操作、且可能不熟悉该系统的值班工程师，因此每一步都必须明确，每条命令都必须可运行，每个决策点都必须有清晰的判断标准。
主要能力
生成的手册包含：分步操作流程、可直接复制粘贴的命令、故障排查决策树，以及清晰的升级路径。手册结构包括目的、前置条件、操作流程、故障排查、升级、验证与回滚等部分。
工作流程
-
读取架构上下文：扫描 .chalk/docs/engineering/ 目录，查找架构文档（服务名、端点、基础设施组件）、既有 runbook（匹配格式并避免重复）、事故报告与事后复盘（识别应当存在但缺失的流程）、监控与告警文档（仪表盘链接、告警名称）；同时检查 .chalk/docs/ 根目录下的配置或基础设施文档。
-
解析手册范围：从 $ARGUMENTS 中识别手册覆盖的服务或流程、所针对的场景（部署、回滚、扩缩容、故障转移、数据恢复等），以及这是常规流程还是应急流程。若范围过宽（如“为所有内容写 runbook”），会要求用户缩小到具体服务或场景。
-
收集运维细节：使用 Bash 检查代码库中的服务配置文件、部署脚本与基础设施即代码、环境变量与配置引用、健康检查端点、监控集成、数据库连接细节（不暴露凭据），以确保命令引用真实的服务名与端点，而非通用占位符。
-
以编号步骤编写流程：每一步需描述该步骤做什么及为什么、包含可复制粘贴的命令（如适用）、展示预期输出以便操作者验证成功、说明该步骤失败时该怎么做（转故障排查、重试或升级）。
-
构建故障排查决策树：针对常见故障模式，从操作者观察到的症状开始，根据可观察条件（日志消息、状态码、指标）分支，每个分支导向具体操作或升级，不允许死胡同——每个分支必须以修复或升级结束。
-
定义升级标准：说明何时升级（时间阈值、严重程度条件）、升级给谁（团队、角色或值班渠道，而非个人姓名）、升级时应包含哪些信息。
-
编写验证步骤：每个流程后包含确认成功的步骤，如健康检查命令、预期指标值、确认正常运行的日志模式，以及视为流程完成前需监控多长时间。
-
编写回滚流程：对每个改变状态的流程，包含如何撤销更改、回滚可能影响哪些数据或状态、回滚专属的验证步骤。
-
校验命令：审查手册中所有命令，确保没有未定义的通用占位符（如 <your-service-name> 或 $SERVICE），环境特定值在顶部作为前置条件清晰记录，命令使用代码库中真实的服务名、端点与路径。
-
确定下一个文件编号：列出 .chalk/docs/engineering/ 中的文件，找到最大编号并加 1。
-
写入文件：保存到 .chalk/docs/engineering/<n>runbook<service_or_process>.md。
-
确认：呈现手册，并总结覆盖的流程、前置条件，以及需要团队补充的缺口。
手册结构
手册以 # Runbook: <Service/Process Name> 开头，包含最后更新日期、负责人（团队或角色）、审查周期（每季度/每次事故后）。正文包括：目的（何时使用、针对什么场景）、前置条件（访问权限、CLI 工具及版本、需设置的环境变量、需熟悉的系统）、操作流程（每个流程含何时使用、预计时长、风险等级、原因、可复制命令、预期输出、失败处理）、故障排查（以症状为起点的决策树）、升级（条件、升级对象、渠道、需包含信息）、验证（健康检查、指标检查、日志检查、监控周期）、回滚（回滚命令、验证回滚、回滚风险）。
输出
- 文件：
.chalk/docs/engineering/<n>_runbook_<service_or_process>.md - 格式：纯 markdown，无 YAML frontmatter
- 首行：
# Runbook: <Service/Process Name>
反模式
该技能明确避免以下问题：用散文代替步骤、命令不可复制（含占位符）、缺少升级路径、没有验证步骤、命令过时、缺少回滚、假设操作者具备专业知识。
适用场景
适用于需要为特定服务或流程编写运维手册、记录操作流程、创建运维指南，或记录如何处理特定场景（如部署、回滚、扩缩容、故障转移、数据恢复等）的情况。
限制
手册范围过宽时需用户缩小到具体服务或场景。命令需基于代码库真实信息，环境特定值需在前置条件中定义。资料中未提供关于收费、价格、平台支持范围等更多信息。