04 · 文字规范与推理泄漏
完整命题与推理泄漏
.agents/skills/dsh-prose-standard/.agents/skills/dsh-trim-cot-leakage/scripts/verify-concrete-terms.tsscripts/verify-export-jsdoc.ts保留完整命题
dsh-prose-standard 的核心要求是：先把契约写全，再删推理转录、重复和装饰。修改一段文字之前，先列出它包含的每个命题，并保留每个相关的：
- 行为主体与动作；
- 条件、时机与顺序；
- 情态：must、may、never；
- 否定性保证与例外；
- 所有权、副作用、失败方式与后果。
只有每个事实性子句都保留下来、结果更清楚时，才删形容词和叙述。原文的说法是 "A smaller word count alone is not an improvement"：字数少了本身不算改进。
这条 skill 也规定了"必须写什么"。例如公共 JSDoc 要写清调用方可见的返回值区别、抛出与拒绝、副作用、所有权、时机、取消和持久性；测试注释只解释非显然的设计，删掉逐步讲解。verify-export-jsdoc 强制每个导出都有 JSDoc，函数类导出要有 @param 和非 void 的 @returns。
用词：先找更精确的词
contract、boundary、shape、surface、seam、gate、vocabulary 是"用前先检查"的词，不是禁用词。写 response fields、JSON validation、ESM exports，不写 response shape、validation boundary、module shape。
真正被禁的词由脚本强制执行。verify-concrete-terms 拒绝所有维护中的文件里出现 "prove" 加 "nance" 拼成的那个词，路径名也算。原因记在 2026-08-26-ban-ambiguous-origin-label 这条 Note 里：这个词在仓库里积累了七八种不相干的含义，读者无法从词本身判断记录的是什么事实。
推理泄漏：AI 特有的一类 slop
模型写注释和文档时，常把自己的推理过程留在文字里：引用只有那次会话才看得见的"决策 7"，叙述"这次改了什么"，或者向已经离开的评审者辩护。dsh-trim-cot-leakage 把这种文字定义为"视角停留在写作会话而不在仓库"，并分成八类：
| # | 类别 | 例子 | 修法 |
|---|---|---|---|
| 1 | 失效的会话引用 | (decision 7)、(audit C2)、design §4.7、阶段代号 T4 | 有已提交的归属就写名称和路径；没有就删掉引用，把它的事实子句独立写出 |
| 2 | PR 或 stack 视角 | "a later PR in this stack"、"this PR adds" | 写已发布的机制或扩展点；遗留工作转成 TODO 或 issue |
| 3 | 变更叙述与版本戳 | "used to"、"no longer"、"this cut"、"now" | 写现在的行为；修复的回归写成反事实："没有 X 时会发生 Y" |
| 4 | 评审过程 | "Rejected in review:"、"the reviewer confirmed" | 保留决定和理由，删掉谁在什么时候说的 |
| 5 | 向评审者辩护 | "the cast is safe — it simply…" | 写出让代码安全的不变量，或者直接删除 |
| 6 | 复述与推导 | "first we X, then we Y"、测试讲解 | 删除，只留非显然的契约 |
| 7 | 含糊与计划残留 | "probably fine for now"、"should be enough" | 改成 TODO/FIXME，或写出实际的上限 |
| 8 | 写作语言混杂 | 英文文档里夹着"设计稿"、"端" | 翻译或删除 |
修改前后对照
以下例子取自 dsh-trim-cot-leakage/references/examples.md：
The registry rejects duplicate names
(decision 7: names are flat, no namespacing).The registry rejects duplicate names;
names are flat, with no namespacing.没有任何已提交的文件拥有 "decision 7"，所以删掉引用，但它的事实子句"名称是扁平的"被独立写了出来。
Colors used to come from `--widget-*` tokens,
which nothing defined, so it always rendered
the fallbacks; the alias tokens fixed that
(PR #88).Colors come from the alias tokens; an
undefined token renders the fallbacks.两条仍然成立的事实（当前机制、未定义 token 的失败行为）用现在时保留。这个 bug 的经过归 PR 和 Agent Note 记录。
不算泄漏的内容
过度修正同样有害。以下内容要保留：issue 引用（#1470、TODO(name):）；Agent Note 和复盘里的 PR 引用；lint 抑制、覆盖率忽略、空 catch 的理由说明；"without X, Y happens" 这类反事实；带 "measured" 的实测数据；运行时的新旧状态（"旧连接排空后新连接才接受请求"）；外部标准的章节号（RFC 9110 §10.1.5）。
可以借鉴
- 把"推理泄漏"列为独立缺陷类型，给模型一个可操作的测试：HEAD 上的读者能否验证。
- 修改文字前先列命题，防止删短时丢掉义务、例外和失败行为。
- 把出现多种含义的词直接禁掉，并用脚本执行。