working-text

工作文本

本技能规范工作文本：同事为了在代码仓库、GitHub、CI 输出、Notion 或图表中完成工作而阅读的任何内容。包括 README、注释、描述或帮助文本、PR 或 issue、评审回复、提交说明、Agent 简报和 Mermaid 图表。本技能不适用于论文、文章或书籍，因为读者是研读它们，而不是快速浏览。

读者快速浏览就能理解的文本。每条事实都由最能快速呈现它的形式展示，段落只承载其他形式无法展示的内容。文中提及的每条路径、符号和检查都真实存在。探针能精确地完成两种机械化解读。

工作文本供人快速浏览并据此采取行动，而不是供人阅读学习。本技能规范工作文本的阅读方式、结构和事实，无论它出现在哪里。每种文档必须包含的内容由各自的技能负责：PR 正文或 issue 由 /pr-and-issue-discipline 技能负责，AGENTS.md 由 /code-standards 技能负责。

如果已安装 /unslop，则在剩余文案上最后运行。

范例

一份 CI 指南中的一个段落，摘自某个代码仓库关于其 merge-gate 检查的页面，共 73 个词，包含三条规则和两个例外：

The judgment, whole: every needed result must be `success`, or `skipped` for a job named in `allowed-skips`. Anything else (`failure`, `cancelled`, a skip the list does not name) fails the gate, and the step summary lists every job with its result. The default workflow names `checks` alone, so a scheduled run passes on `ci` and an all-skipped run cannot pass; the release workflow names nothing, since none of its gating jobs may skip.

用不同形式展示相同的事实：

The judgment, whole:

| Needed result | Gate |
| --- | --- |
| `success` | passes |
| `skipped`, for a job named in `allowed-skips` | passes |
| anything else: `failure`, `cancelled`, a skip the list does not name | fails; the step summary lists every job with its result |

- **Default workflow:** `allowed-skips` names `checks` alone, so a scheduled run passes on `ci` and an all-skipped run cannot pass.
- **Release workflow:** names nothing, since none of its gating jobs may skip.

一位读者打开该页面后，称它是「文字墙」。探针也认同，并指出了问题所在：

$ bun docs-probe.mts --shape-only docs/merge-gate.md
docs-probe: 19 finding(s)
  docs/merge-gate.md:10: paragraph of 73 words; the cap is 70. Split it, or turn its facts into bullets, a table, or numbered steps
  docs/merge-gate.md:28: list item of 173 words; the cap is 70. Split it, or turn its facts into bullets, a table, or numbered steps
  docs/merge-gate.md:99: list item of 218 words; the cap is 70. Split it, or turn its facts into bullets, a table, or numbered steps

根据内容选择呈现方式

没有规定必须使用哪种呈现方式。先了解读者必须看到什么，再选择能让他们一眼看清的方式。

以下呈现方式都曾很好地承载实际页面内容，并列出了各自适用的内容。需要其他方式的页面，就使用其他方式。

读者必须看到什么	能清楚呈现它的方式	这种方式胜出的原因
哪个值胜出，以及继承在哪里停止	每个叶节点都标明胜出值的 ASCII 树	表格无法呈现分支
命令的作用	命令实际捕获的输出，然后用尽可能少的文字说明	输出就是事实；关于输出的文字只是重复
如何处理某种症状	三行：你看到了什么、这意味着什么、该怎么做	症状需要引用错误信息并说明因果关系，而表格单元格会截断内容
版本之间的差异	表格列出旧形式、新形式，以及旧形式现在会产生什么结果	第四列展示的是可观察到的症状，而不是规则
两种并列状态	状态矩阵，再用一句说明左侧和右侧分别代表什么的文字收尾	矩阵承载状态，句子说明如何解读
代码的组织方式	Mermaid 图，方框中标出实际文件和导出项，并以指向演示该结构的测试的链接收尾	检查器可以验证的方框不会过时
一个流程	箭头流程图，或编号步骤，每一步都配一个能运行内容的围栏代码块	顺序就是内容
一项变更的效果	一个变更前代码块和一个变更后代码块	对比本身就是可视化
简单事实	项目符号列表，每项都以点明事实的粗体引导语开头	读者扫一眼引导语，就能停在相关内容处

只有当新的呈现方式能比它取代的方式更快地展现内容时，才更换方式；否则就保留原方式。只有当读者需要沿列比较两个或更多字段时，表格才有用。把每项占一行的列表改成名称和说明表格毫无收益，应当改回列表。

单调乏味本身就是一道墙：页面上表格接表格，或项目符号接项目符号，读起来就像电子表格。将其视为重新分组或合并内容的信号，但任何呈现方式的更换仍须通过上述收益测试。只要项目符号在每个小节中仍是最快的呈现方式，就继续使用。

无论采用哪种呈现方式，都要遵守以下四条规则：

• 每种呈现方式都是一种选择。 使用表格、项目符号列表、链接或图表，是因为它比文字叙述更快地呈现了内容，而不是因为上一节用了这种方式。判断标准是略读效果（见下文的两个层次）。
• 每个要点只用一种呈现方式。 图表后面又用一段文字重新解释，说明图表没有发挥作用，因此应改进图表或删掉这段文字。绝不要用表格呈现一次，再用文字或图表重复呈现同一内容。图表的无障碍文本替代内容（替代文本，或为屏幕阅读器准备的一句等效说明）不算第二种呈现方式。
• 项目符号用于列举。 项目符号用来呈现列表项或检查清单。推理过程应保持为文字叙述。把每句话都改成项目符号，会让人看不出哪些内容属于同一类。
• 如果不遵循惯例能让内容更易读，就打破惯例。 去掉表格、改用三行格式的故障排除页面，读起来比原来的表格更好。在评审中说明原因，不要写在页面里。

为快速浏览的读者写作

读者都会先浏览这些页面，再仔细阅读其中一个部分。同一套规则能满足这两类读者的需求，也让页面在不面面俱到的情况下保留足够的实用细节。

两层结构。 顶层（标题、图示、图表、截取的区块、表格的形状、首句、强调文本）本身就承载页面的全部要点。细节层（段落正文、表格单元格）则供读者进一步查阅。上述每种表达方式都服务于顶层。

结构：

• 每个部分都以最重要的要点开头。 读者即使只读完第一句，也能记住正确的信息。
• 标题本身就能讲清内容（“什么会限制什么”“版本何时变化”），而不是说明读者的水平（“简易版”）。按顺序读完标题，就能了解页面的大纲。页面超过约 500 个词时，才使用标题。
• **每段只讲一个要点，**1 到 3 句，不超过 70 个词。**句子要短，**每句只表达一个要点，约 20 个词。
• 嵌套最多一层。 列表中再嵌套列表，说明内容需要换一种表达方式：表格、树状结构、小节，或其他合适的形式。
• 页面应从头到尾顺畅阅读。 各部分按读者接触主题的顺序排列。先介绍事实，再使用该事实。

用词：

• 平实、直接、主动。 写“构建流程写入锁文件”，不要写“锁文件由构建流程写入”。同一事物始终使用同一个术语。在首次提及的地方，用通俗语言解释读者不熟悉的名称，再介绍机制名称（先说“限制每次合并的检查”，再说它的任务名称 merge-gate）。
• 先举例，再说明规则。 用代码块或表格行展示示例，再在后一句解释其含义。
• 展示产物。 日志行、错误文本和树状输出都应原样引用，不要改述。
• 使用程序员语体。 使用准确的名词、仓库自身的名称，不用营销语言。在已安装 /unslop 的地方，它可以去除残留的 AI 写作痕迹。

事实：

• 每个事实只归一处负责。 一个事实只放在一个页面。其他页面在需要该事实的句子中链接到它（这个限制由[重试页面](retries.md#the-limit)说明），绝不重复陈述。只有索引页面才应单独设立链接或导航部分。
• 所有内部链接都必须有效。 链接目标必须存在，锚点必须对应目标页面上的标题。检查程序会验证目标，并读取锚点。
• 标明事实的性质。 已确认的事实直接陈述。假设、他人提供的说法、风险、建议或任何未经独立核实的内容，都应在出现的地方注明（“猜测，用来省去一轮往返”或“用户报告，尚未复现”）。
• 只删去读者不需要的内容。 删除实现细节、重复内容和填充语，保留定义、推理、限制和后续步骤。删减属于内容变更，必须在 PR 中说明；重组（见下文）则应移动所有事实，不得删减任何事实。
• **开头用一句话说明页面讲什么、不讲什么，**然后提供读者最先需要的信息。不要先写背景。

产物中的正文

代码产物中供人阅读的描述或帮助文本，也属于正式文本，必须遵守上述段落、表达方式和标题规则。产物包括：

• GitHub 操作或工作流的 description
• 软件包清单中的描述
• CLI 帮助文本
• issue 和 PR 模板

技能的 frontmatter 描述不在此列：它是触发条件，由 /craft-skills-and-memories 技能负责。

产物专属事实：

• 操作描述必须是字面块（|）。
• 输入和输出描述各用一句话。
• 操作或工作流描述中绝不出现 ${{。 GitHub 在加载文件时会对其求值，意外出现的 ${{ 会导致操作一加载就失败。

探测器

探测器会报告审阅者原本需要用肉眼判断的两项读数。scripts/docs-probe.mts 随此技能提供，用于读取页面的文本单元，即段落和列表项。

Front matter、标题、代码围栏、表格、注释和生成区域都不属于正文。探测器会报告：

• 超出上限（--max-words，默认为 70）的单元，以及该单元的起始行
• 正文提及但不存在的仓库路径：反引号括起的 <dir>/<file>.<ext>、./<file>、../<file> 或 <dir>/，或相对链接目标

将尖括号占位符替换为仓库自己的路径。

bun "<skill-dir>/scripts/docs-probe.mts" README.md docs/*.md               # exit 0: docs-probe: 4 page(s) clean (cap 70 words)
bun "<skill-dir>/scripts/docs-probe.mts" --shape-only <skill pages>          # a recipe page names files of the repository it describes
bun "<skill-dir>/scripts/docs-probe.mts" --base <template-dir> docs/*.md     # pages that name files a template or generator writes into other repositories

usage: docs-probe.mts [--root <dir>] [--base <dir>]... [--max-words <n>] [--shape-only] <page.md>...
  --root        the repository root paths resolve against (default: cwd)
  --base        a directory under the root that paths also resolve against (repeatable)
  --max-words   the cap on a paragraph or list item (default: 70)
  --shape-only  word counts only; skip the check that named paths exist
exits: 0 every page is clean; 1 findings, one per line as page:line: message; 2 usage or an unreadable page

路径检查会有意忽略以下内容：占位符（<skill-dir>/x）、glob、owner/repo slug、绝对路径和不带路径的文件名（package.json）。如果某个路径的首段在页面与根目录之间的任何位置都不存在，也不在 --base 之下，检查同样会忽略它（页面描述的是另一种目录布局）。

路径会相对于根目录、页面所在目录、两者之间的每个目录，以及每个 --base 进行解析。因此，技能的参考页面可以提及其自身 scripts/ 文件夹中的脚本；描述模板的页面也可以使用文件在由该模板生成的仓库中将采用的路径来提及文件。

当仓库的检查命令强制执行上限时，上限就会成为一道门槛，而非一种偏好：可以通过已发布的软件包执行（同一上限也以 Vale 规则的形式包含在 vale/ 下，适用于已运行 Vale 的仓库），也可以通过仓库自己的探测器执行。技能的脚本始终是在技能目录中运行的工具，不会复制到仓库中。

重构现有页面

重塑正文会移动事实。更改必须移动所有事实，且只能移动这些事实。

1. 事前清点：标题和锚点（grep -n '^#' <page>），以及探测器的发现项数量。
2. 重塑。旧段落中的每项事实都必须出现在新页面的某处。旧页面未陈述的事实不得出现。
3. 事后清点：相同的标题和锚点（其他页面可能会链接到其中某个锚点），并确保探测器检查通过。
4. 如已安装，请使用 /rubber-duck-review 技能审阅新旧页面，并提出以下固定问题：列出旧页面中未出现在新页面的每项事实，以及新页面中未出现在旧页面的每项事实。两份列表都为空才算通过。

PR 正文会像上面的示例一样展示一个段落的前后版本，并附上两份清点结果。

架构页面

最容易腐化的页面类型有自己的编写步骤，见 references/architecture-page.md。该步骤包括一项分层声明、一个双向都会失败的 lint、根据声明生成的模块映射，以及页面测试。页面测试会检查每个图示框是否都注明了一个实际存在的文件和该文件导出的符号。

审查标准

• 段落或列表项超过 70 个单词（运行 docs-probe.mts，不要凭目测计数），或段落超过三个句子。
• 描述读者一眼就能从设备上看到的内容时，未明确写出：有命令却没有输出、读者必须从段落中自行归纳的规则，或未说明可观察症状的中断。
• 设备变更没有带来收益（把单行列表改成名称与描述组成的表格）、设备形式单调，导致重新分组或合并内容会更易读（表格接表格、项目符号接项目符号），或内容重复呈现（段落重新解释图示、项目符号复述箭头；但图示的替代文本或一句话的屏幕阅读器等效文本不算）。
• 在第二个页面重述事实，而添加指向事实归属页面的链接就足够。
• 内部链接的目标或锚点无法解析。
• 非索引页面上出现链接或导航部分。
• 标题描述读者的水平，而非内容。
• 按顺序阅读时无法通过标题理清页面脉络，或页面字数不足约 500 字却使用了标题。
• 小节的关键点放在铺垫之后，或列表中嵌套列表。
• 项目符号承载了本应写成散文的推理过程。
• 页面最上层的内容（标题、图示、图表、捕获块、表格结构、首句、强调文本）本身无法传达整体内容。
• 将假设、给定的主张、风险、建议或未经核实的解读写成已确认的事实。
• 精简页面时删掉了读者需要的定义、原因、限制或后续步骤。
• 页面提及的路径、链接、符号或检查项不存在（路径和链接使用探测工具检查；图示方框使用 scripts/architecture/check-page.mts 检查）。
• 重塑页面后丢失或新增了事实，或删除了其他页面链接到的标题锚点。
• 架构页面的模块图标示了代码中不存在的依赖关系。
• 方框中列出了其文件并未导出的符号，或概念图没有 Demonstrated by: 行。
• 代码制品中的散文违反了本技能“制品中的散文”小节所规定的页面规则。操作说明不是字面块，或输入或输出的说明超过一个句子。操作或工作流说明中包含 ${{。
• 人工浏览时会遇到大段难以阅读的散文：文档、报告、PR 文本（PR 正文内容由 /pr-and-issue-discipline 技能负责）。