Feature Flag · 功能旗標

---
doc_type: "feature-flag"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["git-diff", "flag-inventory"]
  optional: ["release-plan"]
---

# Feature Flag: <flag-name>

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

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 6 段（編號 1, 2, 4, 5, 9, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每結論行內加 `（依據：diff path:line / release-plan §X）`；每量化欄位帶 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造；**flag 必須有 expiry_date（≤ 90 天）+ cleanup owner + fallback**，缺一視為不合格。

---

## 1. Executive Summary

<!-- ai-fill: 3-5 行，Dev/SRE/PO 30 秒讀完。內容：flag 名、保護什麼變更、預計 rollout 期、kill switch 條件 -->

<3-5 行說明>

> **TL;DR:** <一句話：這個 flag 把哪個變更從「不能合」變成「合進去但預設關閉」>

---

## 2. Flag Identity

<!-- ai-rule: 命名必含模組 prefix（snake_case），對齊既有 inventory 規約 -->

| Field | Value | Confidence |
|---|---|---|
| **Name** | `<module>_<feature>` (e.g. `checkout_new_pricing`) | **[H]** |
| **Type** | release / experiment / ops / permission | **[H]** |
| **Scope** | rollout %: 0-100 / segment / region | **[H]** |
| **Expiry date** | YYYY-MM-DD (≤ 90 天) | **[H]** |

---

## 4. Owners & Lifecycle

<!-- ai-rule: DRI + cleanup owner 必填（可同人）；expiry 缺失視為不合格 -->

- **DRI:** <person or team>
- **Cleanup owner:** <負責退役>
- **Escalation:** <on-call rotation>
- **Cleanup trigger:** <e.g. rollout = 100% sustained 14 days OR expiry_date reached>

---

## 5. Telemetry & Kill Switch

<!-- ai-rule: 必有 exposure metric + SLO impact metric + kill switch alert 三件 -->

| Signal | Name | Threshold |
|---|---|---|
| **Exposure** | `flag.<name>.exposure` | track on/off ratio |
| **SLO impact** | <e.g. error_rate by flag> | < 1% |
| **Kill switch alert** | <e.g. error_rate > 1% sustained 5min> | auto-disable flag |

**Fallback on flag eval failure:** <e.g. default to off — 保守路徑>

---

## 9. Risks（top 3）

<!-- ai-rule: 每條格式：失效模式 + Mitigation + Owner 三件齊 -->

> **R1:** <風險描述> — **Mitigation:** <如何降低> — **Owner:** <誰負責>
>
> **R2:** ...
>
> **R3:** ...

---

## 12. Confidence & Sources & TODO

- **整份文件最低 confidence 欄位：** <列出所有 [L] 與 [M]>
- **Fabricated assumptions（推測但 input 未明說）：**
  - <假設 1>
- **Highest-value next input:** <下一份最該補的 SLO 定義 / incident postmortem>

### TODO（缺資料）

- _TODO: 需要 SLO 數值校準 kill switch threshold_

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 6 段 H2 章節齊全（編號 1, 2, 4, 5, 9, 12，刻意不連號）
> - [ ] Flag name 含模組 prefix + snake_case
> - [ ] Expiry date 存在且 ≤ 90 天
> - [ ] DRI + cleanup owner 兩者皆填
> - [ ] Telemetry 三件齊：exposure + SLO impact + kill switch alert
> - [ ] Fallback on eval failure 已寫
> - [ ] Risks 每條格式：失效模式 + Mitigation + Owner
> - [ ] 無 YAML / JSON schema 輸出（spec 是給人讀的 markdown）