cheat-debug

name	cheat-debug
description	AI Coding 的 debug 輔助 skill。用戶說出 bug 症狀時自動建立快照 + 迭代記錄，每次嘗試後判斷好壞，連續 3 次更差強制建議回滾。debug 結束後輸出結構化摘要供 cheat-retro 和 cheat-predict 校準使用。觸發詞："我遇到 bug"/"debug 這個"/"有個錯誤"/"程式跑不起來"/"回滾"/"越改越糟"。
allowed-tools	Bash(*), Read, Write, Edit, Glob

/cheat-debug — Debug 輔助 + 防劣化機制

快照 → 迭代記錄 → 好壞判斷 → 必要時回滾 → 輸出摘要給 retro 用。

Overview

[用戶說出 bug 症狀]
  ↓
[Phase 0: 讀狀態，找 in_progress_session]
  ↓
[Phase 1: 建快照 + debug-log.md]
  ↓
[Phase 2: 迭代 debug 循環]
  每次嘗試 → 記錄 → 判斷好/差 → 連續 3 次差 → 強制建議回滾
  ↓
[Phase 3: 結束（修好 or 放棄）]
  ↓
[Phase 4: 寫 summary，供 cheat-retro 讀取]

---

Phase 0: 讀狀態

讀 .cheat-state.json：

• 不存在 → 停止：「請先跑 /cheat-init。」
• 存在 → 取 in_progress_session（若有，連結到對應 predictions/ 文件）

---

Phase 1: 建快照

1. 確定要快照的文件

從用戶描述的 bug 和當前目錄判斷哪些是相關源碼文件（.py / .js / .ts 等）。不要快照整個目錄——只快照用戶正在改的文件。

2. 建立 session 目錄

sessions/debug-YYYY-MM-DD-HHMM_<short>/
├── snapshot/         ← 快照（出 bug 時的原始版本）
└── debug-log.md      ← 迭代記錄

short = bug 描述的 2-3 個字 slug（例如 pdf-parse-crash）

3. 複製快照

cp <相關文件> sessions/debug-YYYY-MM-DD-HHMM_<short>/snapshot/

4. 建立 debug-log.md

# Debug: <bug 描述>

**開始時間**: YYYY-MM-DD HH:MM
**關聯預測**: predictions/<id>.md（若有）
**症狀**: <用戶描述的錯誤現象>
**快照文件**: <被快照的文件列表>

---

## 迭代記錄

（每次嘗試後追加）

---

## 最終摘要

（完成後填寫）

告訴用戶：「快照已建立。開始 debug，每次修改後告訴我結果。」

---

Phase 1.5: 歷史相似 bug 查詢

快照建立後，立即用 bug 症狀關鍵字搜尋過去的 debug log：

grep -rl "<關鍵字>" sessions/debug-*/debug-log.md 2>/dev/null

提取 2-3 個關鍵字（錯誤類型、涉及的模組名稱、症狀描述）分別搜尋。

找到相似 log → 讀完整 debug-log.md（不是只讀摘要）

讀完整 log 的目的：讓 AI 完整理解「當時試了什麼、為什麼失敗、最後怎麼解決」，而不只是知道一個失敗標籤。有了完整脈絡，AI 才能真正避免重蹈覆轍。

輸出格式：

📂 發現 N 個相似歷史 bug，已讀入完整記錄：

• sessions/debug-2026-05-20-1430_pdf-parse-crash/debug-log.md
  症狀：[摘要一句話]
  已排除方向：改 encoding / 換 pdfplumber 版本（原因：...）
  最終解法：改用 pymupdf

根據歷史記錄，本次 debug 從以下方向開始，跳過已知無效路徑：
→ [AI 的第一個假設]

沒有找到相似 log → 直接進 Phase 2，不輸出任何提示。

---

Phase 2: 迭代 Debug 循環

每次嘗試的流程

a. AI 提出假設並修改代碼

先說出假設：「我認為問題在 X，嘗試 Y 方向。」再動手改。

b. 請用戶確認結果

改完後問：「結果怎樣？（好轉 / 更差 / 沒變化）」

c. 記錄這次嘗試（append 到 debug-log.md 的迭代記錄段）

### 嘗試 N — HH:MM
**假設**: [AI 認為問題在哪]
**修改**: [改了什麼]
**結果**: 好轉 / 更差 / 沒變化
**觀察**: [用戶回饋或錯誤訊息變化]

d. 判斷是否觸發防劣化警告

在 context 中維護一個輕量計數器（不寫入文件）：

consecutive_worse = 0

• 結果「好轉」或「沒變化」→ consecutive_worse = 0
• 結果「更差」→ consecutive_worse += 1

當 consecutive_worse >= 3：

⚠️ 連續 3 次更差。強烈建議回滾到快照版本。

回滾指令：說「回滾」，我會把快照文件還原。
繼續嘗試：說「繼續」，但風險自負。

回滾操作

用戶說「回滾」時：

cp sessions/debug-YYYY-MM-DD-HHMM_<short>/snapshot/<file> <原始路徑>

對每個快照文件執行。回滾後在 debug-log.md 記錄：

### 回滾 — HH:MM
回滾到快照版本。原因：連續 N 次更差。

注意：快照建立後新增的文件不會被自動刪除，需用戶手動處理。告知用戶。

---

Phase 3: 結束

修好了：用戶說「修好了」/ 「bug 解決了」

放棄：用戶說「放棄」/ 「先不管這個 bug」

---

Phase 4: 寫最終摘要

在 debug-log.md 的「最終摘要」段填寫：

## 最終摘要

**結束時間**: YYYY-MM-DD HH:MM
**結果**: 修復成功 / 放棄
**總嘗試次數**: N
**回滾次數**: N
**耗時**: X 分鐘
**最終解法**: <一句話描述修好的方法，或放棄原因>
**失敗方向**: <列出嘗試過但無效的方向，供未來避免>

然後輸出給用戶：

✅ Debug 完成（或放棄）

快照保留在：sessions/debug-YYYY-MM-DD-HHMM_<short>/
（確認沒問題後可刪除）

下一步：說「這個 bug 修好了，復盤一下」→ cheat-retro 會讀入這份記錄。

---

cheat-retro 整合

cheat-retro 執行時，若當前 predictions/ 文件有關聯的 debug session：

• 自動讀取 debug-log.md 的最終摘要段（不讀全文，節省 token）
• 在復盤結果中加入：
  • debug_iterations: 嘗試次數
  • rollbacks: 回滾次數
  • debug_minutes: debug 耗時
  • failed_directions: 失敗方向列表

這些數字寫入 .cheat-state.json 的 session 記錄，供 cheat-bump 校準「你在這類任務平均踩幾次 bug」。

---

Token 策略

資料	放哪	進 context？
歷史相似 debug log	sessions/debug-*/debug-log.md	全文讀入——完整脈絡才能真正避免重蹈覆轍
當次迭代追蹤	context 輕量計數器	是，僅 consecutive_worse 數字
retro 讀取	只讀最終摘要段	是，~10 行
預測校準	4 個數字	極小

歷史 log 全文讀入是刻意設計：token 的代價換來不重蹈覆轍，值得。

---

Key Rules

1. 快照只存相關文件：不要 cp 整個目錄，只快照用戶正在修改的源碼
2. 不替用戶判斷好壞：每次改完後必須問用戶結果，不要自己假設
3. 3 次連輸強制提醒：不能因為用戶沒問就跳過警告
4. 摘要優先於全文：retro 讀摘要段，不讀完整迭代記錄
5. 快照不自動刪：debug 完成後告知用戶快照位置，讓用戶決定何時清理