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

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


# Bug 通報

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

讓通報者描述遇到的問題，由 skill 整理資訊、查核 codebase 並起草。使用同一 plugin 內的 [bug 模板](../../templates/bug-issue.md)。不要求通報者自行填 repo、負責人、技術根因或除錯紀錄。

## 1. 先整理草稿

接受一句描述、截圖、Issue、對話、操作錄影或 CI 紀錄；從已有資訊整理出問題發生的位置、當時操作、實際結果、期待結果與證據。保留錯誤訊息與指令原文，敏感資料先遮蔽。尚不知道的資訊明確標記，不能補寫成事實。

先整理內部草稿，完成以下查核與自審修訂後交人審閱，再一次補問最多 1–2 個無法從可用來源查明、會影響判斷的問題，例如「在哪個頁面按了哪個按鈕？」或「你預期送出後看到什麼？」；不要逐欄問卷。若連問題對象都無法辨識，可先問一個必要問題。無法重現仍可通報，寫出發生一次／偶發／尚未重現及已知條件，不將無法重現判為無 bug。

## 2. 由 skill 查核現況

- 根據畫面、路由、錯誤與專案分工定位相關子專案，讀取相鄰實作、既有測試和需求；限定在本問題需要的範圍。
- 記錄實際查到的 repo、ref／HEAD、相關檔案及 dirty 狀態；未取得 codebase 或環境時註明限制。程式存在不代表已部署，靜態閱讀不代表成功重現。
- 對照已確認需求與通報者期待。既有程式行為不能自行推翻需求；沒有預期行為依據時標記「待釐清」，不要武斷認定是 bug 或新增需求。
- 區分已觀察現象、已驗證原因與待驗證推測。若證據指向環境問題就列出依據；若確認為新需求，保留原始通報並銜接 [prd-generation](../prd-generation/SKILL.md)，不自動改成開發任務。
- 搜尋相關 repo 的既有 Issues，包含 open／closed；記錄查詢範圍與可能重複卡。相似標題不等於同一問題，已關閉問題也可能復發。未能搜尋時明講「尚未完成重複查核」。

一般產品通報預設開在 `daodaoedu/daodao`；使用者已指定目標則沿用。依程式查核結果把受影響子專案寫入技術附錄，不要求通報者選修復 repo。目標仍有實質歧義時，用產品或畫面名稱釐清；不要將 repo 路由工作交回通報者。

將草稿存至任務的 `notes/issue-drafts/`；沒有任務目錄時使用 root `docs/plans/issue-drafts/`，使用不覆蓋既有檔案的名稱。發布用 body 必須自足，不能只引用其他人無法存取的本機路徑。附件未上傳時標記「本機證據待提供」，不假裝已有公開連結。

## 3. AI 自審修訂 → 人審核

交審前由 AI 核對：通報事實與來源、操作步驟、實際／期待結果、現況與規格差異、分類與重複卡依據、重現限制、修復驗收方向。能由可用來源查明的缺項先自行查核，修正矛盾、遺漏及把推測寫成事實的內容；不要求人先除錯或按 PM／設計師／RD 分工檢查。

交付修訂後草稿及精簡摘要：已檢核與主要依據、已修正事項、未驗證限制、需人決策。無法查明或重現的部分標未知，不假稱檢核通過；仍完成其他可做的檢查。人審核問題是否描述正確、預期行為及產品取捨；AI 可提建議，不自行核准。

收到審核意見後由 AI 修訂，重新檢核受影響的分類、步驟與驗收方向。草稿中的人為決策確認與遠端發布授權分開，沿用已確認內容與授權，不重複要求審核。

## 4. 確認與發布

先展示具體標題、內容、目的 repo 與預定 labels／狀態。沿用對話中已明確授權的建立或更新範圍，不重複詢問；只要求草稿、模板或 skill 調整時，停在本機草稿。尚未授權發布時，完成可審閱草稿後才詢問是否建立。未決資訊可以保留在 Todo 通報卡，不因缺少根因、SHA 或重現紀錄拒絕開卡。

發布操作只在已授權範圍內：

1. 唯讀確認目的 repo 存取權與現有 labels，再查一次相關 Issues，避免草稿期間已有同卡。若已存在，回報連結；只有明確授權更新時才修改或留言，不再建立副本。
2. 已確認 bug 使用 `bug` label；分類未定時在內容標記待釐清，不捏造已確認缺陷。缺 label 不吞錯誤，依開卡授權與權限處理，無法補建則回報具體限制。
3. 使用 structured tool 或 `gh issue create --repo <repo> --title <title> --body-file <body.md> --label <label>`。參數正確引用，檔案保留真實換行，不將需求或錯誤文字拼成 shell 程式。
4. 只有要求掛 Board 時才操作該 Board；使用 live project／field／option IDs，預設 Todo。單純開 bug 不設定 Ready for Dev、不啟動 dispatch、不建立修復子卡。需要 Board 的具體指令時僅參考 [gh-card](../gh-card/SKILL.md) 的「唯讀 preflight 與授權」及「發布與回讀」段落，不重跑其入口分流。
5. 保存成功建立的 URL／number；回讀 title、body、labels，若有 Board 則核對實際 status。建立請求 timeout 時先搜尋是否已建立，結果仍不明就保存待查狀態，不盲目重送。Issue 已成功但 Board 失敗時只處理未完成步驟，持續失敗就回報部分完成。

最後回報草稿位置或實際 Issue URL、分類、已知限制與待確認事項。通報不等於已重現、已修復或已驗收；修復流程需再提供 regression test 與驗收證據。