G1en-114/rtfm-first-skill

RTFM-First

把使用者提供的手冊當作本任務的唯一權威來源。不要憑記憶或網上二手資料寫程式。

鐵律

1. 手冊存在時，先讀手冊再寫程式；API 名稱、參數、預設值、單位、行為都以手冊為準。
2. 編碼前必須核對手冊版本與當前環境版本（見「掃描環境並核對版本」），並向使用者報告結論。
3. 引用手冊中的關鍵事實時給出出處：.rtfm/<name>.txt:行號 或 PAGE n。
4. 手冊與程式或環境矛盾時，不要立刻「糾正」程式去匹配網上慣例；停下來說明差異，請使用者決定。
5. 沒有手冊時，先索要或確認手冊路徑，不要憑記憶開始實現。
6. 每次「糾錯」前必須能指出違反的是手冊哪一條；給不出出處，就不許改。

工作流

1. 定位並提取手冊

• 使用者沒給路徑時，在專案裡搜尋候選（*.pdf、*.md、docs/**、README 中提到的規格書）；有多個候選時列出並請使用者確認。
• 腳本位於本 SKILL.md 所在目錄的 scripts/ 下。
• 統一提取到專案根目錄的 .rtfm/（若是 git 倉庫，確保 .gitignore 包含 .rtfm/）：
  • PDF：執行本 skill 的 scripts/extract_manual.py <manual.pdf> .rtfm/<name>.txt
  • MD/TXT：同樣執行該腳本，會複製成文字。
• 有多本手冊（如 API 參考 + 協定規範 + SDK 文件）時，全部提取並各自建索引；引用時寫明是哪本手冊。
• 若 PDF 是掃描件（提取文字過短），報告需要 OCR，不要硬猜內容。
• 若腳本報「無 PDF 文字提取器」，按提示安裝 poppler-utils 或 pypdf（需要系統級安裝時先徵得使用者同意）後重試；不要跳過 PDF 直接憑印象寫。
• 先讀標題頁/前言/版本歷史，記錄：產品名、手冊版本、適用版本、日期、修訂說明。

2. 建立索引

• 執行本 skill 的 scripts/index_manual.py .rtfm/<name>.txt .rtfm/index.md。
• 查詢任何主題時先 rg -n 索引和正文；不要因為「沒印象」就認為手冊沒寫。

3. 掃描環境並核對版本

• 收集環境證據：清單/鎖檔案（package.json、pyproject.toml、Cargo.lock、go.mod、requirements*.txt 等）、--version/-V、pkg-config --modversion、執行時版本、SDK/工具鍊/硬體標識。
• 從手冊封面、版本歷史、頁腳、中繼資料中找手冊版本。
• 按 references/version-matching.md 判定 MATCH / COMPATIBLE / MISMATCH / UNKNOWN。
• 把結論寫進 .rtfm/version-report.md，並向使用者報告。
• MISMATCH 或 UNKNOWN 時停下來：請使用者提供匹配版本的手冊，或明確批准繼續；批准後要把風險記錄在 notes 裡。

4. 按手冊寫程式

• 每個元件/API 動手前完整讀相關章節；把關鍵簽名、常數、預設值、邊界情況摘錄到 .rtfm/notes.md 並附出處。
• .rtfm/notes.md 建議結構：手冊名與版本、版本核對結論（MATCH/COMPATIBLE/MISMATCH/UNKNOWN）、按主題摘錄（每條帶 manual.txt:L行 或 PAGE n）、修改歷史。
• 識別符、字串、數字從手冊原文複製，避免自己轉寫引入筆誤。
• 手冊沒覆蓋的點，標註 TODO + 出處（「手冊某節未說明」），不要靜默用網上資料補；確需補充時先徵求使用者同意。
• 手冊說了就算數：即使與網上「最佳實踐」不同，也不要反覆「修正」成網上版本，除非使用者要求，或建構/測試證據證明手冊頁與當前環境不符。

5. 驗證並收尾

• 完成後逐節對照手冊自檢：每個用到的 API/配置/行為都能在 notes 中找到出處。
• 跑建構/測試；失敗時先回手冊相關章節找依據，再檢查環境，禁止猜。
• 交付時簡要列出：手冊版本、環境版本、核對結論、主要出處，以及任何需要使用者確認的偏差。

防糾錯循環

本 skill 存在的直接原因：AI 不讀手冊 → 憑網上記憶「修正」程式 → 又錯 → 再修，反覆重寫。以下規則必須遵守：

• 修改前先證明：每次改程式/配置前，先指出「當前實現違反手冊哪一行」，並引用出處；給不出出處就不許改。
• 一次只改一個原因：不要把「看起來不順眼」和「手冊不一致」混在一次修改裡；無關的程式保持原樣。
• 同一現象被改過兩次仍出現：停止打補丁，回到手冊完整重讀相關章節，懷疑自己的理解，而不是繼續猜。
• 手冊行為與網上慣例衝突時：以手冊為準；不要把「能跑但不符合手冊」的程式改成網上版本，也不要反過來。
• 報錯先查手冊：查錯誤碼、約束、邊界條件章節；手冊沒有對應條目時，再查環境證據，禁止憑直覺改。
• 每次修改都追加一行到 .rtfm/notes.md 的修改歷史：目標、改了什麼、依據出處。改完兩輪還不對，先對照歷史找重複。