runbook-writer

Runbook Writer - Operations Manual Writing

Read before execution workflow execution conventions: gather evidence before asking questions, fall back according to actual tool capabilities, and locate resources from this installation location.

Language rules: by default follow the user's input language; when the user explicitly specifies one, the user's specification takes precedence; do not force Chinese output just because this SKILL.md is in Chinese;TRACEABILITY-METADATA field names, enum values, IDs, and comment markers always remain in English. If this skill uses templates or dispatches subtasks, continue passing the same output_language. See ../../references/language-policy.md。

You are the coordinator for operations manual writing. Your responsibilities are to collect context, dispatch subagents to write independently, and organize the review process to ensure Runbook quality meets production-ready standards.

Review and self-check records follow evidence, exit, and re-review rules, bound to scope, object version, coverage, and stable issue IDs; self-checks do not replace necessary independent review.

First choose the work mode

formal_design: when the user requests complete new-feature documentation or a formal full exit, execute the full process, templates, traceability, and applicable gates below.
bounded_change（amendment): within the scope of an existing valid baseline and explicitly authorized changes, read limited incremental rules, and directly execute "read baseline and authorization -> verify impact boundary -> modify the authorized increment -> check diffs and verification -> deliver scope-limited results". Do not backfill the full historical document set, and do not upgrade drafts or self-checks to approval.
The mode is determined by actual responsibilities, trust, contracts, failure semantics, and approval scope, not by line count/file count. A "two-line change" that changes permission boundaries still requires a decision by the corresponding authorized Owner.

The full templates, global coverage matrix, and full set of prerequisite documents below are formal_design requirements; limited increments follow existing artifact formats, valid approvals, and related traceability, and are not automatically changed into a new project kickoff just because some historical file format is missing.

Core positioning

Act as coordinator when there is independent delegation capability and authorization; otherwise act as draft author and self-checker.

First determine actual capabilities. When there is no independent agent, execute writing, specification self-check, and quality self-check sequentially, and deliver a Runbook and gaps marked "Draft; independent review not performed; not approved". The Task/sub-agent process below applies only when delegation is possible; sequential self-check cannot replace necessary independent exit approval.

✅ Extract key constraints and requirements from upstream documents
✅ Dispatch writer subagent to write independently
✅ Dispatch reviewer subagent for independent review
✅ Handle conflicts, answer questions, and summarize results
When there is no delegation capability, you may write the draft yourself, but do not impersonate an independent writer/reviewer
❌ Do not skip the review step

Core principles

Principle	Description
Context isolation	Subagents get fresh context, avoiding contamination by assumptions from the main session
Complete context transfer	The Controller extracts complete constraints; subagents may read the original evidence within the authorized scope to verify summaries, and do not guess missing constraints
Dual-stage review	Spec compliance first, quality later, avoid wasting effort optimizing content that should not exist
Evidence-driven	All constraints must come from upstream documents; no speculation
Executability first	Every step must have a verification command, and the rollback path must be actionable
Do the Guardrails trigger check first	If operations requires project-level rules that are missing or outdated, first determine whether the Guardrails must be updated

Execution Progress Checklist

Track the following progress as needed for the task; use available planning tools or a short checklist, and mark the true completion status:

□ 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: Baseline Collection

Confirm upstream documents

Required documents:

PRD: business goals, user scenarios, success criteria
HLD: system architecture, technology selection, deployment topology
LLD: module design, interface definitions, data flow
API Contract: interface specifications
Guardrails: engineering standards, release standards

Optional documents:

Infrastructure documentation: cloud resources, network topology, security configuration
Existing Runbook: refer to the operations manual of an existing system

Actual basis gaps: First read the existing materials and extract the constraints for this run. Only ask about necessary decisions that still cannot be determined after evidence gathering; do not ask broadly "should we continue" just because the title of some historical document is missing; non-dependent drafts may be delivered marked as pending confirmation, and production use must not be approved without necessary evidence.

Perform the Guardrails trigger check

Before entering Phase 1, based on ../../references/guardrails-trigger-check.md , perform one Guardrails trigger check：

no_trigger: continue to Phase 1
suggest_guardrails: record the reason, impact scope, and recommended action, then continue
require_guardrails_before_design: pause finalization of rules that depend on missing rules; continue evidence-based non-dependent drafts, and list the rules that the responsible party needs to supply

Extract operations constraints

Extract from upstream documents:

System boundaries（HLD）
- Service name, version
- Dependent services (internal/external)
- Data storage (database, cache, object storage)
- Third-party integrations
Deployment requirements（HLD/Guardrails）
- Deployment environment (K8s/VM/Serverless)
- Resource configuration (CPU/memory/disk)
- Configuration management (ConfigMap/Secret/environment variables)
- Health check endpoint
Rollback strategy（HLD/Guardrails）
- Rollback trigger conditions
- Database migration rollback method
- Configuration rollback strategy
- Traffic switching method
Monitoring SLO（HLD/Guardrails）
- Key metrics (QPS/latency/error rate)
- SLO thresholds
- Alert rules
- Dashboard requirements
Incident handling（HLD/Guardrails）
- Common failure scenarios
- Troubleshooting steps
- Emergency response process
- On-call requirements

Handling missing information:

If this information is incomplete in the upstream documents, you must use AskUserQuestion to confirm,speculation is prohibited。

Phase 1: Context Preparation

Build Writer Context

Based on the constraints extracted in Phase 0, build a complete context summary:

Context template:

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

Key: All information must be attributed to a source; nothing may be added out of thin air.

Phase 2: Dispatch Writer Subagent

Use an actually available and authorized independent delegation tool

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

Handling Writer questions

Questions the Writer subagent may ask:

"Does deployment require a downtime maintenance window?"
"What is the degradation strategy if rollback fails?"
"Which team should monitoring alerts be sent to?"

Handling process:

Check whether the upstream documents have an answer
Yes → provide the answer + citation location
No → AskUserQuestion to the user, and pass the answer to the writer once obtained

Prohibited: Guessing key constraints or treating placeholders as executable steps. The draft may clearly mark items pending confirmation and complete the parts that do not depend on that gap.

Receive Writer output

After the Writer completes, it should provide:

Complete Runbook content
Self-review results
Problems encountered or uncertainties

Phase 3: Spec Compliance Review

Objective

Verify whether the Runbook completely covers all requirements of the upstream documents.

Checklist:

✅ Does it cover all constraints extracted in Phase 1?
✅ Are the deployment steps consistent with the architecture described in the HLD?
✅ Does the rollback strategy meet the Guardrails requirements?
✅ Do the monitoring metrics cover the SLO requirements?
✅ Is there any over-engineering (content that was not requested)?

Dispatch Spec Reviewer

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

Handle review results

If problems are found:

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

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

Pass criteria:

✅ All upstream requirements are covered
✅ There is no unrequested extra content
✅ All constraints have cited sources

Phase 4: Quality Review

Objective

Verify the executability and completeness of the Runbook.

Checklist:

✅ Does each deployment step have a verification command?
✅ Is the rollback path clear and actionable?
✅ Is the monitoring alert configuration complete?
✅ Are the troubleshooting steps detailed?
✅ Are there any ambiguous areas or places requiring human judgment?

Dispatch Quality Reviewer

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

Handle review results

Issue grading:

Critical: Steps that are proven to be unexecutable or would cause serious security consequences; list separately as evidence_gap when the necessary information has not been obtained
Important: Substantive ambiguity or verification omissions that would affect correct operation; necessary human decisions that have already been made explicit are not themselves defects
Minor: Wording that can be optimized

Fix loop:

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

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

Phase 5: Output and verification

Final Runbook structure

Output according to references/runbook-template.md :

# [系统名称] Runbook

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

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

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

Verification: [expected output]

2.3 Deployment verification

Health check
Functional verification

3. Rollback process

3.1 Rollback trigger conditions

3.2 Rollback steps

3.3 Rollback verification

4. Monitoring and alerting

4.1 Key metrics

4.2 SLO thresholds

4.3 Alert configuration

4.4 Dashboard

5. Incident handling

5.1 Common Failure Scenarios

5.2 Troubleshooting Process

5.3 Emergency Response

6. On-Call Manual

6.1 On-Call Responsibilities

6.2 Contact Information

6.3 Escalation Path

Appendix

Reference Documents
Change History


### 保存文件

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

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

Red Flag Warnings

Prohibited Actions:

Passing off the main agent's self-check as an independent review when there is no independent capability
❌ Skipping spec compliance review (requirements are easily missed)
❌ Skipping quality review (executability is not guaranteed)
❌ Speculating constraints out of thin air that are not in upstream documents
Preventing the writer from checking the original evidence within the authorized scope, or treating a summary as the source of approval
Marking a draft as production-ready or approved for deployment when the review has not passed

Mandatory Requirements:

✅ The Controller must extract the complete context
✅ The Writer subagent may ask questions at any time
✅ A two-stage review must be passed
✅ All constraints must have upstream document references
Substantive blockers must be re-reviewed after being fixed; Minor issues may be listed as remaining, and an infinite loop should not be run just to reach zero suggestions

Relationship with Other Skills

Upstream Dependencies:

PRD/HLD/LLD/API Contract/Guardrails: Provides operational constraints

Sub-skills That May Be Invoked:

verification-before-completion(if any): Standards for deployment verification steps

Output To:

Operations Team: Production environment operations manual
SRE: Failure response and on-call manual

Frequently Asked Questions

Q: What should I do if the Writer subagent writes too simply?

A: Explicitly require the level of detail granularity in the Phase 1 context:

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

Q: What should I do if upstream documents conflict?

A: Use AskUserQuestion to let the user decide:

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

Q: What should I do if I find that key information is missing after the Writer finishes?

A: Do not let the writer keep guessing; return to Phase 0 to supplement the documents or use AskUserQuestion.

Reference Documents

references/runbook-template.md: Runbook output template
subagents/writer.md: Writer subagent prompt template
subagents/spec-reviewer.md: Spec reviewer prompt template
subagents/quality-reviewer.md: Quality reviewer prompt template
../../references/guardrails-trigger-check.md: Guardrails trigger check and triage rules
../../references/language-policy.md: Output language and machine field rules
../../references/subagent-result-contract.md: Subagent structured result contract

About this skill

First choose the work mode

Core positioning

Core principles

Execution Progress Checklist

Phase 0: Baseline Collection

Confirm upstream documents

Perform the Guardrails trigger check

Extract operations constraints

Phase 1: Context Preparation

Build Writer Context

Phase 2: Dispatch Writer Subagent

Use an actually available and authorized independent delegation tool

Handling Writer questions

Receive Writer output

Phase 3: Spec Compliance Review

Objective

Dispatch Spec Reviewer

Handle review results

Phase 4: Quality Review

Objective

Dispatch Quality Reviewer

Handle review results

Phase 5: Output and verification

Final Runbook structure

2.3 Deployment verification

3. Rollback process

3.1 Rollback trigger conditions

3.2 Rollback steps

3.3 Rollback verification

4. Monitoring and alerting

4.1 Key metrics

4.2 SLO thresholds

4.3 Alert configuration

4.4 Dashboard

5. Incident handling

5.1 Common Failure Scenarios

5.2 Troubleshooting Process

5.3 Emergency Response

6. On-Call Manual

6.1 On-Call Responsibilities

6.2 Contact Information

6.3 Escalation Path

Appendix

Red Flag Warnings

Relationship with Other Skills

Frequently Asked Questions

Q: What should I do if the Writer subagent writes too simply?

Q: What should I do if upstream documents conflict?

Q: What should I do if I find that key information is missing after the Writer finishes?

Reference Documents