Runbook · 維運手冊

---
doc_type: "runbook"
variant: "light"
status: "draft"
owner: "<service-owner>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["alert-rule"]
  optional: ["past-postmortem", "dashboard"]
---

# Runbook: <alert-name>

**Status:** Draft v0.X · **Owner:** <service owner> · **Last updated:** YYYY-MM-DD

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 6 段（編號 1, 2, 3, 4, 10, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每結論行內加 `（依據：alert-rule §XXX / postmortem-NNN）`；每量化欄位 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造；**每個 remediation step 必須附 rollback 指令**（不能只有「執行 X」沒有「如果 X 失敗執行 Y」）；診斷指令缺則寫 TODO，不要瞎猜命令語法。

---

## 1. Symptom

<!-- ai-fill: 描述 user-visible 與 internal-signal 兩面 — 凌晨三點被 page 的人要靠這段判斷是不是真的 -->

| Aspect | Description |
|---|---|
| **User-visible** | <使用者會看到什麼：頁面 500 / 結帳失敗 / 載入慢> |
| **Internal signal** | <metric / log pattern：e.g. `http_5xx_rate > 1%` for 5m> |
| **Source** | alert-rule §XXX |
| **Confidence** | **[H]** |

---

## 2. Diagnosis Steps

<!-- ai-rule: 輕量版 2-4 步診斷；每步含 command + expected_output + if_anomalous 三件 -->

### Step D1: <description>

```bash
<exact command or query>
```

- **Expected output:** <what good looks like>
- **If anomalous:** → 跳到 D2 / Remediation R1
- **Source:** dashboard §XX

### Step D2: ...

---

## 3. Remediation Steps

<!-- ai-rule: 每個 remediation 必填 action + command + rollback + slo_impact 四件，缺 rollback 一律不合格 -->

### R1: <action description>

```bash
# Action
<exact command>

# Rollback (required)
<exact rollback command>
```

- **SLO impact:** protect / burn / neutral
- **Time estimate:** <e.g. 2-5 min>
- **Permissions:** <required role / IAM>
- **Confidence:** **[H]**

### R2: ...

---

## 4. Escalation Criteria

<!-- ai-rule: 至少 1 條升級條件，含 condition + escalate_to + expected_ack -->

| Condition | Escalate to | Expected ack |
|---|---|---|
| R1+R2 仍紅燈 > 10 min | <secondary on-call / manager> | <e.g. 5 min> |

---

## 10. Decision Log（key 1-2 條）

<!-- ai-rule: 每條必含 chosen + 至少 1 個 rejected + 拒絕原因 -->

| Date | Decision | Options | Chosen | Rejected why | Confidence |
|---|---|---|---|---|---|
| YYYY-MM-DD | Mitigation 選擇 | restart / failover / scale_out | failover | restart (丟 in-flight X%)、scale_out (lead time 太長) | **[H]** |

---

## 12. Confidence & Sources & TODO

- **整份文件最低 confidence 欄位：** <列出所有 [L] 與 [M]>
- **Last tested:** <ISO date or `_TODO: 需要排 game day_`>
- **Highest-value next input:** <下一份最該補的：最近 3 次同告警 chat log / 權限矩陣>

### TODO（缺資料）

- _TODO: 需要排一次 game day 驗證 R1 rollback 真的能回_

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 6 段 H2 章節齊全（編號 1, 2, 3, 4, 10, 12，刻意不連號）
> - [ ] Symptom 段含 user-visible + internal-signal 雙面
> - [ ] Diagnosis 每步含 command + expected_output + if_anomalous
> - [ ] **每個 Remediation 必有 rollback 指令**（缺即不合格）
> - [ ] 每個 Remediation 標 slo_impact（protect / burn / neutral）
> - [ ] Escalation 段含 condition + escalate_to + expected_ack
> - [ ] Decision Log ≥ 1 條，每條有 rejected reason
> - [ ] 無 YAML / JSON schema 輸出（runbook 是給凌晨三點的人讀的 markdown）