dsh-doc-standards
文档的层级与详略、教程与参考的分离、doc slop 的裁法、verify-doc-budgets 变红时怎么办。
这是 .agents/skills/dsh-doc-standards/SKILL.md 的中文精读。dsh-prose-standard 管「一段话写得好不好」，这个 skill 管「文档放在哪、详略怎么分、冗余怎么裁」。
什么时候触发
写、移动、review 或审计仓库文档时使用——选择层级与详略、分离教程与参考、检查教程的递进、裁剪 doc slop、应对 verify-doc-budgets 失败，以及「改进一下文档」「审计文档」「这个该写在哪」「这篇文档太长了」这类请求。规则本体在 docs/AGENTS.md，本 skill 是覆盖放置、语料审计、预算和验证的工作流。它是引导，不是脚本；永远不要把「长」本身当缺陷。
事实来源（去读原文，不要复述）
- docs/AGENTS.md——层级、教程/参考两种形态、分类法、预算、slop 清单；
- .agents/notes/README.md——什么时候一个决策够格写一篇 Agent Note、怎么归档、里面放什么（头部块、各生命周期骨架、必须有的 Alternatives-considered，由
verify-agent-note-format把关）；docs/postmortem/README.md——什么时候一次事故够格写 postmortem； - docs/i18n/README.md——双语配对规则：改任一侧都有义务在同一次改动里更新对侧；
- 根 AGENTS.md——本 skill 守护的预算纪律的出处；
- 归档 Agent Note——冻结的历史快照，排除在编辑维护和演进中的文档门禁之外。
先审结构，再审散文
对范围内每篇面向人的文档套用标准里的写作顺序（Agent Note 不做这一步；postmortem 按「单事故范围的参考」处理，保留其必需的时间线证据）。
- 把文档放进仓库树和导航树里：说出它自己的主题，列出它的直接子节点。
- 设定允许的详略级别：本主题保留全部细节；直接子节点按目的、职责、高层行为概括；更深的解释移到各自的属主后代并加链接。测试基础设施默认归后代所有，除非它就是本文档的主题。
- 按预期用途（而不是路径或标题）给文档分类：教程必须带着读者走完有序的步骤、到达可观察的结果；参考必须支持在明确范围内的查阅，不要求顺序阅读。
- 教程要私下评估起点读者和概念属于初/中/高级，把每个概念追到它的前置知识，重排超前的材料，把可选的高级细节移到后面的教程或参考里。
- 篇幅可观的混合形态要拆开；小比例的次要形态放在标注清楚的小节里。
然后检查让「放置」变得昂贵或错误的约束：
- 配对文档（
pnpm run verify-translation-pairing --list）每次编辑都要付一次中文版更新加--write重录——会频繁 churn 的内容优先选非配对的家； - 生成的目录绝不手改；事实属于那里就改生成器的源头；
- 改名或移动任何文档之前先 grep 入站引用：
verify-md-links会查 Markdown 链接目标和指向 Markdown 文件的#fragment锚点，verify-doc-refs查 TypeScript 注释里的docs/*.md引用；输出从不进入门禁扫描的 Markdown 的 TypeScript 字符串锚点仍需人工 grep； - 移动是原子的：从旧家删、加入新家、修好每个入站链接，在同一次改动里完成。
审计语料
结构 pass 之后，按「探针从便宜到贵」的顺序猎杀标准里的 slop 清单。先核实并拉取 PR 的 live base，用 pnpm --silent run change-scope --base <verified-base-ref> 圈出已提交和脏路径，再做语义判断；retarget 或合 base 后重跑。
- 量：
pnpm run verify-doc-budgets --list，再git ls-files '*.md' ':(exclude)vendor/**' | xargs wc -w | sort -rn | head -30找没有预算的离群者。 - 猎推理记录泄漏——叙述的历史、死掉的设计会话引用、review 编排、控制流叙述、测试走读——用 dsh-trim-cot-leakage 的分类法、召回电池与保留/删除规则。只有非显而易见的契约或耐久理由可以留；同一理由在兄弟方法旁重复出现的，只留一个家。
- 猎重复：grep 有辨识度的短语，留一个家，其余副本换成链接。
- 把手写目录、测试/状态清单、JSDoc 复述，换成权威树、脚本或生成的参考。
implemented/的 Agent Note 里删掉迁移计划、验收任务清单、将来时的 spec 语言；保留简洁的验证契约——钉住已落地决策的行为与层级，以及具名的覆盖空洞。- 如果删散文会改变被承诺的行为（而不是它的解释），先走 proposed Agent Note（按 dsh-find-simplifications）。
每条承重的规则都留下，最好是一到三行加一条指向理由的链接。砍掉的是：故事、重复、状态汇报、以及推导出这条规则的过程。不要为了给一次性的推理搬家而制造新的解释。
verify-doc-budgets 变红时
按 docs/AGENTS.md 里有序的「迁移 → 压缩 → 提额」政策执行；本 skill 只提供上面的工作流探针。
验证与 PR 卫生
至少跑 pnpm run doc-sync、pnpm run lint、git diff --check；JSDoc 改动可能触发目录重新生成。改了配对文档就走轻量例行路径并跑 pnpm run verify-translation-pairing --write <pair>。PR 正文要给出字数增减、解释任何刻意超长的例外、列出跑过的检查。