---
name: report-bug
description: 把操作異常、截圖、對話或 CI 錯誤整理成可追蹤的 bug 草稿，查核現況與重複卡，依授權建立 GitHub Issue。適用非工程人員通報，不要求先知道 repo 或根因。想要新功能改用 request-feature。
---

<!-- GENERATED by plugin/scripts/build.ts — 不要直接改這個檔案，改 plugin/skills/<name>/ 後重跑 pnpm plugin:build -->


# report-bug

> **行為契約**：先讀 workspace 所有可用檔案（context、附件、截圖），再從已有資訊直接起草。草稿完成後才能補問，且整個流程不超過 2 個問題。不要先要求草稿種類、系統、repo 或路徑——這些由 skill 自行查核，不是通報者的責任。遇到間歇性異常（「昨天壞、今天好」），直接把它視為尚未重現的已觀察異常，如實記錄即可，不要求通報者先排除環境或提供重現步驟。

先讀 [AI 檢核與人工審核共用流程](../../docs/ai-human-review-workflow.md)。模板：[bug-issue.md](../../templates/bug-issue.md)。從本 SKILL 所在位置向上兩層是 plugin root（下文的 `<plugin root>`）。寧可不開卡，也不開猜測的卡或重複卡。

## 1. 讀完整份回報

接受一句描述、截圖、Issue、對話、錄影或 CI 紀錄。連問題發生在哪個產品或畫面都認不出來時，可以先問這一個問題。記下：

- 通報者原話
- 發生位置、當時操作、實際結果、期待結果
- 頻率：一次／偶發／每次／未知
- 錯誤訊息與指令原文（敏感資料先遮蔽）
- 已有的 Issue、PR、commit 連結，或「已經有人在修」的說法

截圖看到能辨識細節為止；錄影找出從正常變壞的那一刻。讀不了的附件直接寫讀不了，不猜內容。

## 2. 追原因再決定歸屬

用有限範圍追一次：從使用者的操作追到看到的結果。

1. 找出可能的程式路徑（從 [feature map](../../docs/feature-map/README.md) 的「主要程式位置」開始，再到程式碼確認；不看名字猜子專案），判斷症狀屬於這一層還是更底層（前端看到的錯誤常常是後端或資料問題）。
2. 看起來像 regression 時，查最近碰過這段的變更：`git log --oneline -20 -- <file>`、`git blame -L <起>,<迄> <file>` 找到最後修改的 commit，從 subject 的 `(#n)` 用 `gh pr view <n>` 讀 PR 說明。
3. 查有沒有已 merge 的 commit 或 open PR 在處理同一個症狀。找到就驗證它，不是直接結案：先確認它有沒有部署到 dev（查 CD run 的 revision），已部署就照通報路徑在 dev 走一次，結果分三種：
   - **已修好**（症狀消失）：在原卡附上證據，不開新卡。
   - **修復不足**（症狀還在）：照常開卡，連結那個 PR，寫明「#n 的修復沒有解決這個症狀」。
   - **無法判定**（還沒部署，或連原本的症狀都重現不了）：回報缺哪一半，不宣稱已修好。
4. 對照已確認的需求：沒有預期行為的依據就標「待釐清」，不自行判定是 bug 或新需求。

通報者、PM 或其他 AI 附上的原因猜測，只當成候選之一另外找證據，不直接寫進技術查核。不需要找到完整根因，但要足以避免歸錯子專案。記下實際查到的 repo、ref／HEAD、檔案與 dirty 狀態；讀不到 codebase 就寫限制，不猜歸屬。程式存在不代表已部署，靜態閱讀不代表已重現。

## 3. 分類

| 類型 | 判斷 | 去向 |
|---|---|---|
| Bug | 違反既有需求：錯誤、當掉、沒反應、資料錯、regression | 本 skill |
| 效能 | 可量測的慢、卡頓、耗資源；記下裝置與瀏覽器、網路、哪個頁面和操作、多常發生，有數字或截圖就附上 | 本 skill，當 bug 處理 |
| 環境問題 | 證據指向設定、網路、帳號或部署 | 寫依據，不開 bug 卡 |
| 新需求 | 現在的行為是刻意的 | 保留原始通報，轉 [request-feature](../request-feature/SKILL.md) |
| 問題／回饋 | 在問怎麼用 | 直接回答 |

bug 與新需求分不清時，先不開卡：草稿照樣寫完並標「待釐清：bug 還是需求」，當場問通報者一個能分辨兩者的問題（例如「這個按鈕以前會送出嗎？」）。有答案就依分類接續；問不到（通報者已離開、只轉來截圖）就停在草稿，回報草稿位置與缺什麼，不猜分類硬開卡。

## 4. 查重

搜尋相關 repo 的 open 與 closed Issues，用錯誤原文、功能區域、操作、症狀、時間範圍。

| 結果 | 判斷 | 動作 |
|---|---|---|
| 確定重複 | 同一個錯誤特徵，或同區域＋同操作＋同症狀，或已確認同一原因 | 不開新卡；有授權時在原卡留言補上新來源與一行「再次發生」，不改 label、不重開 |
| 可能相關 | 原因可能相同但沒證實 | 不開新卡；附連結說明不確定之處，交人決定 |
| 表面相似 | 只是標題或用字像 | 當作沒找到，在草稿記下查過哪張 |
| 沒找到 | — | 可以開 |

很久以前已關閉的卡是 regression 線索，不等於重複。查不了就寫「尚未完成查重」。

## 5. 起草與自審

草稿存在任務的 `notes/issue-drafts/`，沒有任務目錄時存 root `docs/plans/issue-drafts/`，不覆蓋既有檔名。

- 標題寫區域＋症狀，不寫猜測的根因。
- 附通報者原話。
- 推測一律標「待驗證」，和已觀察、已驗證分開。
- 無法重現仍可通報，寫明發生一次／偶發／尚未重現及已知條件；無法重現不等於沒有 bug。
- body 要自足：附件還沒上傳就標「本機證據待提供」，不只引用別人讀不到的本機路徑。

交審前自己核對一次：事實與來源是否一致、步驟與實際／期待結果、分類與查重依據、重現限制、修復驗收方向。查得到的缺項先自己補，再一次補問最多 1–2 個查不到且會影響判斷的問題（例如「在哪個頁面按了哪個按鈕？」），不要逐欄問卷。

交給人看的摘要只寫：主要依據、已修正事項、未驗證限制、需人決策的地方。人負責判斷描述是否正確、預期行為與產品取捨。收到審核意見後由你修訂，並重查受影響的分類、步驟與驗收方向。

## 6. 建立條件

以下全部成立才建立：

1. 分類是 bug 或效能。
2. 行為違反已確認的需求。預期行為沒有依據時，可以標「待釐清」開 Todo；但 bug 與新需求分不清時不開（見「分類」）。
3. 沒有已知的修復，或已知修復經 dev 驗證後症狀仍在（見「追原因再決定歸屬」第 3 點）。
4. 查重結果是「沒找到」或「表面相似」。
5. 目標 repo 與 labels 已用 live 查詢確認。一般通報預設開在 `daodaoedu/daodao`，受影響子專案寫在技術查核段。
6. 有 shell 且腳本存在時，`python3 <plugin root>/templates/check-issue-draft.py --template bug <草稿>` 沒有輸出；不適用的段落刪掉而不是留佔位符。沒有 shell 或找不到腳本，就自己對照模板檢查，並在回報寫「未跑格式檢查」。
7. 已向使用者展示具體的標題、內容、目的 repo 與預定 labels／類別／狀態。
8. 使用者已授權建立；已明確授權就不再重問。只要求草稿、模板或改 skill 時停在草稿；尚未授權就交草稿並詢問是否建立。

缺根因、SHA 或重現紀錄不擋開卡。

## 7. 發布與回讀

1. 發布前再查一次重複卡；已存在就回報連結。
2. 已確認的 bug 掛 `bug`；預期行為未定時在內容標「待釐清」。缺 label 不忽略錯誤；開卡者只有 Read 權限設不了 label 時，照 [request-feature](../request-feature/SKILL.md)「發布與回讀」留言請維護者補。
3. `gh issue create --repo <repo> --title <title> --body-file <body.md> --label <label>`，不把錯誤文字拼進 shell。
4. 只有要求掛 Board 才掛，預設 Todo，並帶類別：使用者看得到的錯誤用 `--category bug`（產品 Bug），CI、開發或驗收流程的錯誤用 `--category 工程`；指令見 [request-feature](../request-feature/SKILL.md)「發布與回讀」。不設 Ready、不建修復子卡。
5. 回讀 title、body、labels（與 Board status、類別）。timeout 時先搜尋是否已建立，再決定重送；Issue 已建立但 Board 失敗時只補未完成的步驟。

回報草稿位置或 Issue URL、分類、已知限制與待確認事項。通報不等於已重現、已修復或已驗收；修復時需附 regression test 與驗收證據。