写或审阅文档、RFC、README、PR 描述、提交信息时…

适用于撰写或评审技术文档、RFC、README、PR 描述和提交信息，通过分层规则消除歧义、精简表达并保持可读性。

适用场景

解决思路

1. 先确定文档模式（Diátaxis）：一个文档只用一种模式。用两个问题判断——内容是指导行动（doing）还是理解（thinking），是服务于学习还是工作。行动+学习=tutorial；行动+工作=how-to；理解+工作=reference；理解+学习=explanation。
2. tutorial（边做边学）：你是老师，学习者的成功是你的责任。开头说明学习者将构建什么，而不是将『学到』什么。每一步都产生可见结果，尽早且频繁。告诉他们应该看到什么：预期输出、提示符变化、日志行。解释压缩到一个从句加一个链接。教学停顿会打断课程。保持具体。用『我们』、用命令式写：『First, do x. Now, do y.』
3. how-to（达成目标的步骤）：解决人的问题，而不是机器能执行的操作。假设读者有能力。跳过教学。只写行动：不跑题、不写背景、不为完整性而完整，改为链接。允许分支和判断：『If you want x, do y.』按任务命名指南：『How to calibrate the radar array』，而不是『Radar array calibration』。
4. reference（查阅用事实）：只描述。不指导、不说服、不发表意见。干燥、完整、确定。陈述事实、选项、限制和错误，不模棱两可。镜像被描述对象的结构，使代码和文档可对照导航。把材料放在读者期望的位置。尽可能从代码生成，以保持真实。
5. explanation（理解与为什么）：一个有限主题，可脱离产品单独阅读。每个标题应能容忍前面加一个隐含的『About...』。锚定一个真实的 why 问题。给出上下文：设计决策、历史、约束、替代方案。只有这里允许发表意见。
6. 不要混用模式：tutorial 里不放 reference 表格，reference 里不放 tutorial 式手把手，how-to 里不争论。拆开并链接。
7. 以『you』、现在时对读者说话。『Will』只用于确实以后发生的事。
8. 说清谁做什么：『the compiler checks』，而不是『is checked』。仅当执行者未知或无关紧要时才用被动。
9. 把指令写成命令：『Click Submit.』平实陈述事实。绝不用『should be done』。
10. 把条件放在指令之前：『To delete the document, click Delete.』读者会跳过不适用部分。
11. 常见情况放前面，例外放后面。
12. 像一位懂行的朋友那样说话。不用流行词、不用比喻、指令中不用『please』，流程中绝不用『simply』『easy』『quickly』。如果简单，读者就不会来这里。
13. 不要预告（『we will soon support...』），不要连续句子以相同短语开头。
14. 用能说明链接去向的词做链接：页面标题或简短描述。绝不用『click here』。优先在页面上写一句上下文，而不是链出去。
15. 标题承载要点，而不只是主题（『Pick the mode first』，而不是『Modes』）。用句子式大小写。任务标题是裸动词短语（『Create an instance』）。概念标题是名词短语。每页一个 h1，不跳级。
16. 有序列表用于序列，无序列表用于其他。用完整句子引出列表。保持列表项平行。
17. 代码用代码字体。UI 元素用粗体。使用序列逗号。去掉『etc.』，并在一开始说明列表不完整。
18. 每条指令一句。其他地方也一句一个想法。
19. 拆分超过约 20 词的指令和超过约 25 词的其他句子。
20. 把警告或条件放在它所保护的步骤之前：『If hot oil touches your skin, injuries can occur.』
21. 保留『the』和『a』：『Remove backup file』有两种读法。『Remove the backup file』只有一种。
22. 给每个词一个含义和一个职责，然后保持不变。如果『check』表示检查，就不要再用它表示约束。
23. 每个动作只选一个词并坚持：用『start』，不要这里用『start』那里用『initiate』。
24. 把流程写成直接命令，绝不写成叙述，也绝不用被动：『Install the component』，而不是『the component must be installed』。
25. 尽量避免『-ing』词。它们承担太多语法职责，容易滋生误读。
26. 把『only』『not』这类词放在它们修饰的词旁边：『only fails on growth』和『fails only on growth』含义不同。
27. 拆开长名词串：『the proto import budget check script』改为『the script that checks the proto-import budget』。
28. 让每个『it』『they』『this』都指向一个明确对象。有疑问时重复名词。绝不用『this』或『which』指代整个从句。
29. 不要省略动词：『Phase 1 moves the converters and Phase 2 the runtime』让 Phase 2 缺了动词。给它补上。
30. 保留显示结构的小词。『Ensure that the switch is off』保留『that』，因为它让句子只有一种解析方式。绝不用词数换清晰度。
31. 当能防止误读时，在并列结构中重复冠词：当它们是两个东西时，用『the client and the host』，而不是『the client and host』。
32. 当句子可以有两种分组方式时，说明『and』或『or』连接哪些部分。『Both...and』『either...or』『if...then』是免费消歧器。
33. 用句号，不用分号。把破折号换成新句子。
34. 让括号中的文本成为完整语法单位或独立句子。绝不用『(s)』构成复数。
35. 不用斜杠：写『a, b, or both』，而不是『a/b』或『and/or』。
36. 每个东西在所有地方只用一个名称。一个文档若对同一事物说『the gate』『the ratchet』『the budget check』，等于教了三样东西。编辑之间改写未变化的句子代价相同。不要改动没变的内容。
37. 跳过习语、口语、拉丁缩写和比喻。非母语读者、翻译和 agent 都最能解析平实结构。
38. 对本技能触及的每个文档应用 unslop 技能。该技能负责 slop 模式目录：AI 词汇、填充词、模糊措辞、格式痕迹。
39. PR 描述和提交信息也是写作。除 Diátaxis 外的每一层都适用于它们。PR 正文是审阅者能在一分钟内读完的简报。不要粘贴 swarm 日志、SHA 列表或指标表。链接它们。
40. 产品 UI 字符串不是文档。那些使用你产品的文案指南。
41. 代码片段用制表符缩进。写真实路径和真实符号。让每个计数或树形声明在落地提交处为真，并包含可重新生成它的命令。
42. 删掉每个不起作用的词。如果句子去掉某个词仍成立，这个词就删。『In order to』就是『to』。『It is important to note that』什么也不是。
43. 使用简短、日常的词。用『Use』，不用『utilize』。用『Help』，不用『facilitate』。用『Do』，不用『perform』。长词必须用精确性来抵偿其长度。
44. 当规则让句子更糟时，换一种方式修句子或不动它。规则服务于读者。一个遵守所有规则却听起来像机器写的句子已经失败。
45. 代码库就是词表。写真实的符号、文件、标志或命令名，而不是同义词或对它的描述。
46. 不要发明术语。使用开发者会大声说出的词：『move』『delete』『a budget that only decreases』，而不是『evacuate』『ratchet』『endgame』。当文档第一次说明其含义时，命名模式是可以的。在回复中提出新的违规词及其替换词，作为对 unslop 抽象隐喻规则的补充，并附上 diff。不要编辑那个技能。
47. 有意混合句子长度。短句落定一个要点。较长的句子从容承载一个事实及其条件或后果。
48. 一句一个想法不等于一种长度。拆开承载两个想法的句子。保留承载一个想法的长句。
49. 在模式允许处要有观点。Explanation 权衡取舍，所以说出你的看法，而不是罗列利弊。Reference 保持干燥。
50. 具体胜过空洞。不是『schema changes can cause issues』，而是『a column rename fails the build』。

适用边界 · 注意事项

• 产品 UI 字符串不适用本技能，应使用产品自己的文案指南。
• 不要混用 Diátaxis 模式：tutorial 里不放 reference 表格，reference 里不放 tutorial 式手把手，how-to 里不争论。
• 不要编辑 unslop 技能；只提出新增违规词及替换词和 diff。