写提案/RFC/设计文档时：用结论先行、Why &…

当你需要以书面形式论证一项变更、记录设计或征求读者意见（提案、RFC、设计文档、规格、迁移计划）时，用这套骨架和检查清单来组织内容。

适用场景

解决思路

1. 先读 `technical-writing` 技能（read-first、硬规则、真相规则、风格），作为必备背景。
2. 在写提案、RFC、设计文档、规格、迁移计划、"should we" 文档时调用本技能；不要用于记录已定决策（用 `recording-decisions`）、流程（用 `writing-runbooks`）或状态报告。
3. 时间紧迫时也要坚持：提案靠数字和已列明的成本说服人，语域规则不因截止日期而改变；"punchy" 不是豁免理由。
4. 当收到的事实没有来源时，标记 `**[source wanted: ...]**` 并继续写；绝不编造引用，也绝不悄悄丢掉该事实。
5. 按骨架组织文档：标题说明文档做什么；副标题一句话锁定范围；元信息表包含 Status（Draft / Request for comments）、Owner、Scope（含明确排除项）、Related、Audience。
6. 正文顺序：1. Summary 立即给出结论（不是场合、不是方法）；2. Context / what was analyzed；3. 按问题拆分分析；n. Open questions；n+1. Benefits and costs（两者都要，只写收益像推销）；n+2. Residual risks and what not to do（仅当设计把工作交给其他团队时）。
7. 结尾一行说明哪些部分是事实、哪些是提案，以及希望在哪里获得输入。
8. 给章节编号，并引用为 `ch. 7.1`。
9. 同时写 goals 和 non-goals；non-goals（或 "explicitly not changed"）章节说明什么保持不变。
10. 术语有歧义时先定义再谈行为：先钉死 "responded"、"eligible"、"stale" 等词再使用。
11. 设一个 grounding 章节钉住设计所依赖的事实：事实/来源表，对照指定 commit 核对；把已验证事实与将要构建的内容分开。
12. 附录用字母编号（Appendix A、B），放会淹没正文的内容：配置示例、术语表、清单。
13. 一个事实只存在一处；用链接引用，绝不重复，即使在同一仓库的不同文档之间也不重复。
14. 未完成部分用 `**[DRAFT - input wanted]**` 标记，而不是省略。
15. 开放问题要有负责人：姓名、角色，或明确的 "to be filled by"。
16. 当设计把工作交给他人时，用 residual risks 和 what NOT to do 收尾。
17. 不设行数预算，但删掉因重复或强调而来的长度；超过约 800 行就拆分，主文档链接到各部分。
18. 每个非平凡选择都配一个 Why & What 框：What（一句话，不辩解）、Why（理由，并说明该选择不解决什么）、Alternatives considered（每个替代方案给出其最强论点及为何仍落选）、Fallback（若失败什么仍存活）。
19. 被否定的替代方案必须给出其最强论点，否则是稻草人；点名那个论点。
20. 承认该选择不解决什么，会让文档更可信。
21. 没人会争议的选择不要放框，那是噪音。
22. 文档中别处没出现过的替代方案不要放进框里，读者根本不会考虑它；偶尔一个这样的否决可以接受，连续多个短否决说明框被注水了。
23. 保持提案语气：用 "we propose" 和 "whether that convinces is up to you"，而不是 "this becomes the way of working"；设定方向，把细节选择留开放。
24. 点名成本：收益章节以代价收尾——什么变难了、人们必须忘掉什么、哪项自由消失了。
25. 不用最高级、不用承诺式语言；用具体数字和可验证陈述。
26. 预期结果可能是负面的，要 upfront 说出来，例如 "the expected outcome is that the current queue beats the proposed rewrite; that is a useful result."。
27. 交给评审者或执行者前，检查五种含糊缺陷：1. 未解决的占位符（TBD、TODO、"fill in later" 或明显不完整句子；标记的 `**[DRAFT - input wanted]**` 块是有意为之，未标记的缺口是缺陷）；2. 缺少验收标准（需求没有具体、可独立测试的成功条件）；3. 未定义引用（提到但无处定义的类型、端点、组件或表）；4. 无可验证产出（任务不产出评审者可检查的东西：无文件路径、无命令、无可观察行为）；5. 只写 what 不写 how（结果没有可实施方向，如 "handle errors appropriately" 却未定义何为 appropriate）。
28. 对执行计划，每个任务补充：目标、确切文件、展示的变更、带具体场景的测试、验证命令。
29. 解释任何令人困惑的遗留物（奇怪的目录名、遗留别名），不要让它继续令人费解。

适用边界 · 注意事项

• 记录已定决策时（用 `recording-decisions`）。
• 写流程/操作手册时（用 `writing-runbooks`）。
• 写状态报告时。