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 的修改历史：目标、改了什么、依据出处。改完两轮还不对，先对照历史找重复。