fix-issuelisted

# fix-issue 把這個 repo 的一個 issue，從「在 `main` 上重現」一路做到「PR 的 CI 綠了」。步驟裡用到的都是這個 repo 自己的腳本，所以這份 skill 只在這裡用。`CLAUDE.md` 已經寫過的規則（validate、pytest、codex 的產生與 release），這裡不再重抄，只放執行順序和踩過的坑。 ## 輸入與輸出 - 輸入：issue 編號或 URL。一次要處理好幾個 issue 時，一個一個來，照 issue 裡的順序表走，例如 #138 的「Task order」。 - 輸出： - `fix/<N>-<slug>` branch 上的修正和測試； - 一個帶 `Closes #N` 的 PR； - 那個 PR 的 CI 結果。 - commit、push、合併，每一步都要先問過。 ## 步驟 1. **讀 issue。** 跑 `gh issue view <N>`，讀出驗收條件、`Decision needed` 和順序。遇到待決點時： - 如果便宜又可逆，就採用 issue 的建議，並在回報裡說明； - 否則先問一個問題，得到答案再動手。 2. **開 branch。** 確認工作區乾淨，接著 `git switch main && git pull --ff-only`，再 `git switch -c fix/<N>-<slug>`。這個 issue 如果已經有 branch，先問哪一個才算數。 3. **先在 `main` 上重現。** - scratch 腳本放在 scratchpad，不要放進 repo。 - 隔離方式和 `tests/conftest.py` 一樣：拿掉 `CLAUDE_CODE_SESSION_ID`，並把 `CAI_USAGE_LEDGER` 指到 scratch 路徑。 - CLI 要照 skill 實際的跑法去跑，例如 `track_state.py status` 要從專案根目錄執行。 - 重現不出來，就停下來回報。 4. **先寫會失敗的測試。** - 每個驗收條件寫一個測試，放在 issue 點名的測試檔裡，沿用那個檔案的 helper。 - 先跑一次，讀失敗訊息：它必須是因為 issue 描述的原因而失敗，不能是 import error。 - 修之前就會通過的守門測試可以保留，但回報裡要點名是哪幾個。 5. **修。** - 做讓測試轉綠的最小改動。註解寫「為什麼」，並附上 issue 編號。 - 再用懷疑的眼光檢查一次：找出可能打破新規則的輸入，例如模板占位字、legacy 文件、CRLF、相對路徑和絕對路徑。真的找到就補一個測試。 6. **bump 版本、release codex。** - 改到 `plugins/cai/`，就 bump `plugins/cai/.claude-plugin/plugin.json`；修 bug 只升 patch 版本。 - 改到會被產生進 `plugins/cai-codex/` 的檔案，就跑 `python scripts/gen-codex.py`。全部改完之後再跑 `--release <main 上的版本升一個 patch>`。 - 同一個 branch 上可以重跑同一個版本號，因為它只和 `main` 上的版本比較。 - `usage_report.py` 這類不會被產生