PR Template

---
doc_type: "pr-template"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["git-diff", "commit-messages"]
  optional: ["linked-issue"]
---

# PR: <one-liner-title>

**Status:** Draft · **Author:** <name> · **Last updated:** YYYY-MM-DD

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 6 段（編號 1, 2, 3, 5, 9, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每結論行內加 `（依據：diff path:line / commit §X / issue §Y）`；每量化欄位 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造；**「沒有效能影響」若無 benchmark 必須標 [L]**；security / observability / breaking-change 三項必須涵蓋。

---

## 1. Summary

<!-- ai-fill: 一句話 + type tag。type: feat / fix / refactor / perf / docs / chore / breaking -->

**One-liner:** <50 字內描述>
**Type:** `feat` / `fix` / `refactor` / `perf` / `docs` / `chore` / `breaking`

---

## 2. Why

<!-- ai-rule: 必含 problem + link_to_issue。缺 issue link 標 _TODO_ -->

- **Problem:** <要解決什麼>
- **Link to issue:** <URL or _TODO: 缺 issue_>
- **Source:** commit §XX / issue §YY

---

## 3. Changes

<!-- ai-rule: 每個 high-risk 檔案必列；low-risk 可彙總 -->

| File | Summary | Risk |
|---|---|---|
| `<path>` | <做了什麼> | low / mid / high |

---

## 5. Test Plan & Risk

<!-- ai-rule: test_plan 必含 evidence 或 _TODO_；risk 必含 blast radius + detection signals -->

### Test plan

- **Unit:** <test names>
- **Integration:** <scenarios>
- **Manual:** <steps>
- **Evidence:** <screenshot / log / _TODO: 缺證據_>

### Risk

- **Blast radius:** <哪些 user / endpoint / dataset>
- **Detection signals:** <metric / log query>
- **Known unknowns:** <unknown 1>, <unknown 2>
- **Confidence:** **[H/M/L]**

---

## 9. Reviewer Checklist

<!-- ai-rule: 6-7 項 checkbox，作者預先勾選自評，reviewer 二次驗證 -->

- [ ] **Correctness** — 邏輯與 spec 一致
- [ ] **Error handling** — 例外捕捉、訊息有上下文
- [ ] **Tests added** — 新邏輯有測試
- [ ] **Observability** — log / metric / trace
- [ ] **Security** — auth / input validation / secret
- [ ] **Backward compatibility** — 無 breaking
- [ ] **Rollback strategy** — revert / feature flag / data migration down

---

## 12. Confidence & TODO

- **整份 PR 最低 confidence 欄位：** <列出所有 [L] 與 [M]>
- **Fabricated assumptions:** <推測但 input 未明說>
- **Highest-value next input:** <e.g. perf benchmark>

### TODO（缺資料）

- _TODO: 需要 perf benchmark 校準 risk_

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 6 段 H2 章節齊全（編號 1, 2, 3, 5, 9, 12，刻意不連號）
> - [ ] One-liner ≤ 50 字 + type tag
> - [ ] Why 含 problem + link_to_issue（缺則 _TODO_）
> - [ ] Risk 含 blast radius + detection signals + confidence badge
> - [ ] Reviewer Checklist 6-7 項齊
> - [ ] 「沒有效能影響」若無 benchmark 標 [L]
> - [ ] 無 YAML / JSON schema 輸出（PR description 是給人讀的 markdown）