القائمة
本專案 (MV3 Chrome extension) 的除錯紀律與 playbook：先重現再修、證據優先於模式匹配、單變因修改、跨 context 時序問題、service worker 終止、storage 問題、flaky E2E 分流。當使用者提到「除錯、debug、壞掉、不會動、修不好、查原因、root cause、flaky、時好時壞」時觸發。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
建立本專案的 Pull Request：雙語描述 (zh-TW/en)、gh CLI、.agent/skills/pull-request/scripts/check-pr.sh 預驗證、references/pr_template.md 與 checklist.md。當使用者提到「開 PR、建 PR、create PR、pull request、提交變更、發 PR、新建 PR」時觸發。
維護本專案 AI agent harness（AGENTS.md / CLAUDE.md / GEMINI.md / .agent/{rules,skills,workflows} / docs/wiki）的 SOP：單一事實來源對照表、drift 稽核步驟、新增/刪除 skill 的判準、wiki 同步機制。當使用者提到「更新 harness、同步 AGENTS、文件過時、drift、稽核設定檔、整理 skills、維護 wiki」時觸發。
交付前驗證紀律：依變更類型選擇最小充分驗證組合（unit / 目標 E2E / happy-path CI / make build）、Makefile 打包檢查、i18n 連動、GEMINI.md key_files 同步、誠實回報。當使用者提到「驗證、收尾、完成了嗎、可以交付嗎、送 PR 前、檢查一下」或任何實作即將收尾時觸發。
清理已合併進 main 的本地與遠端 git 分支。本專案採 squash merge，PR 合併後特性分支可直接刪除。當使用者提到「清理分支、cleanup branches、刪除舊分支、清掉已合併分支、整理 branch」時觸發。
本專案 (Manifest V3 Chrome extension) 的 commit 規範與範例：subject 使用英文 Conventional Commits、body 使用繁中說明背景與原因。當使用者提到「commit、提交訊息、commit message、寫 commit、commit 規範」時觸發。
撰寫本專案的 PRD (產品需求文件)，位置為 /docs/specs/{type}/{ID-PREFIX}_{desc}/PRD_spec.md。當使用者提到「PRD、產品需求、需求文件、寫規格、新功能規劃、acceptance criteria」時觸發。分級 SDD 之 T2（完整流程）的 Phase 1，產出物提供給 sa skill 銜接；T1 輕量案件不需獨立 PRD。
| name | debugging |
| description | 本專案 (MV3 Chrome extension) 的除錯紀律與 playbook：先重現再修、證據優先於模式匹配、單變因修改、跨 context 時序問題、service worker 終止、storage 問題、flaky E2E 分流。當使用者提到「除錯、debug、壞掉、不會動、修不好、查原因、root cause、flaky、時好時壞」時觸發。 |
修 bug 的品質差異不在「會不會寫 code」，而在下修改之前的判斷。本 skill 把判斷步驟固定下來，任何模型照走都能避開最常見的失敗模式。
chrome://extensions 的「錯誤」按鈕 / CI 的完整 log，不要只讀最後一行。git log --oneline -- <file> 看最近誰動過；行為是「本來好的」就用 git bisect（npm run test:ci 或單一測試檔當判準）。console.log（帶 context 前綴，如 [SW] / [panel]），修完必須移除。| 症狀 | 高機率根因 | 驗證方式 |
|---|---|---|
| 功能第一次好、閒置後壞 | MV3 service worker 被終止，in-memory 狀態消失 | SW console 看是否重啟；狀態是否該落 chrome.storage |
| options 頁改設定、sidepanel 沒反應 | settingsBridge 未映射該 storage key | 檢查 modules/ui/settingsBridge.js 的 resolveSettingChangeActions |
| Spotlight 動作沒在正確視窗執行 | panelBridge 旗標定址/TTL 守門擋掉 | 看 classifyPendingAction 判定與 windowId |
| 兩個 context 互相覆寫資料 | storage 全表寫入蓋掉別人的 delta（見 workspace mutateWindowMap 教訓） | 找出所有寫同一 key 的 context，確認是否 read→merge→write |
chrome.storage.sync 寫入無效 | 超過 8KB/key 或總量 quota | setStorageStrict（apiManager）回報 lastError |
| E2E 本機過、CI 掛 | race condition：固定 setTimeout 等待、事件委派未就緒 | 對照 review-pr.md CI 穩定性方針 8 條逐項檢查 |
| UI 事件沒觸發 | 事件委派容器還沒渲染就 dispatch / listener 延遲註冊 | 先 waitForSelector 容器再操作 |
| release 版壞、dev 版好 | 檔案沒進 Makefile 打包清單，或 esbuild bundle 差異 | 解開 zip 比對；make release 後檢查產物 |
# E2E 單檔快速迭代（最便宜的重現環境）
npx jest usecase_tests/puppeteer_tests/<file>.test.js
chrome://extensions → 該擴充功能 → 「服務工作處理程序」inspect。worker.evaluate）：
chrome.storage.local.get(null, console.log)、chrome.storage.sync.get(null, console.log)。.agent/workflows/puppeteer-test.md §4。sdd skill 判級：根因明顯的單點小修 = T0；需要調查、影響多模組 = T1（SPEC.md 寫根因分析）。