working-text

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Working Text

工作文本

This skill governs working text: anything a colleague reads to get work done in a repository, on GitHub, in CI output, in Notion, or in a diagram. A README, a comment, a description or help text, a PR or issue, a review reply, a commit body, an agent brief, a Mermaid chart. It does not govern a paper, an essay, or a book, which a reader studies rather than scans.

Text the reader scans and gets. Every fact is shown by the device that shows it fastest, and a paragraph carries only what no device shows. Every path, symbol, and check it names is real. A probe makes the two mechanical readings exact.

Working text is scanned to act on, not read to learn. This skill owns how it reads, its shape and its facts, wherever it appears. What each artifact must contain stays with its own skill: a PR body or issue with the

/pr-and-issue-discipline

skill, AGENTS.md with the

/code-standards

skill.

Where

/unslop

is installed, it runs last over the prose that remains.

本 skill 规定工作文本：同事会在仓库、GitHub、CI 输出、Notion 或图示中扫读并据此完成工作的任何内容。README、注释、描述或帮助文本、PR 或 issue、评审回复、commit 正文、Agent brief、Mermaid 图都属于这一类。它不规定论文、随笔或书籍；这些是供读者研读而非扫读的文本。

供读者扫读并据以行动的文字。每项事实都应由展示速度最快的载体呈现，而段落只承载任何载体都无法展示的内容。其中提到的每条 path、每个 symbol 和每项 check 都真实存在。probe 让这两种机械化阅读的判定变得精确。

工作文本是为了让人扫读后采取行动，而不是供人通读学习。本 skill 负责它如何被阅读、采用什么结构以及包含哪些事实，无论它出现在哪里。每类工件必须包含什么，仍由各自的 skill 负责：PR 正文或 issue 归

/pr-and-issue-discipline

skill，AGENTS.md 归

/code-standards

skill。

在已安装

/unslop

的地方，它会最后处理剩余的文字。

The specimen

样本

One paragraph of a CI guide, an example from one repository's page on its

merge-gate

check, 73 words carrying three rules and two exceptions:

markdown

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 same facts, shown:

markdown

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.

A reader opened that page and called it a wall of text. The probe agrees and says where:

text

$ 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

CI 指南中的一个段落，以某个仓库介绍其

merge-gate

check 的页面为例；73 个词承载三条规则和两个例外：

markdown

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.

同样的事实，以结构化方式呈现：

markdown

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.

一位读者打开该页面，称它是一堵文字墙。probe 也认同，并指出了具体位置：

text

$ 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

Pick the device from the content

根据内容选择载体

There is no mandated carrier. Ask what the reader must see, then use the device that shows it in one glance.

These are devices that carried real pages well, with the content each fits. A page that needs a different one uses it.

The reader must see	A device that showed it	Why it won
which value wins, and where inheritance stops	an ASCII tree with the winner on each leaf	a table cannot show the branch
what a command does	its real captured output, then the fewest words	the output is the fact; prose about it is a copy
what to do about a symptom	three lines: what you see, what it means, what to do	a symptom needs the quoted error and a causal chain, which a table cell truncates
a break between versions	a table with an old form, a new form, and a column for what the old form does now	the fourth column is the observable symptom, not the rule
two states side by side	a status matrix, resolved by one prose line saying what left means and what right means	the matrix holds the states, the sentence holds the reading
how code is arranged	a mermaid diagram whose boxes name real files and exports, closed by a link to the test that demonstrates it	a box a checker can verify does not rot
a sequence	an arrow flow, or numbered steps with one fenced block per step that runs something	the order is the content
how a change reads	a before block and an after block	the comparison is the visualization
plain facts	bullets, each opened by a bold lead-in that names the fact	the reader scans the lead-ins and stops where it matters

A change of device must show the content faster than the device it replaces, or the device stays. A table earns its place only when the items share two or more fields a reader compares down a column. A one-line-per-item list turned into a name-and-description table gained nothing and goes back.

Monotony is a wall of its own: table after table, or bullet after bullet, down a page reads like a spreadsheet. Treat it as a signal to regroup or merge the content, with any device change still subject to the gain test above. Bullets that stay the fastest carrier for every section stay.

Four rules hold across every device:

Every device is a choice. A table, a bullet list, a link, or a diagram appears because it shows this content faster than prose would. It never appears because the previous section had one. The test is the skim (the two layers, below).
One carrier per point. A diagram followed by a paragraph re-explaining it means the diagram failed, so fix the diagram or drop the paragraph. Never carry the same content as a table and again as prose or a diagram. A diagram's accessible text alternative (alt text, or a one-sentence equivalent for screen readers) is not a second carrier.
A bullet is for a list. Bullets carry items that are a list or a checklist. A line of reasoning stays prose. Turning every sentence into a bullet hides which ones are the same kind of thing.
Break a convention when the content reads better without it. Troubleshooting pages that dropped their tables for the three-line triple read better than the tables did. Say why in the review, not in the page.

载体并无统一规定。先问读者必须看到什么，再选择能让人一眼看懂的载体。

以下是一些曾成功承载真实页面的载体，以及各自适合的内容。页面需要其他载体时，就使用其他载体。

读者必须看到什么	有效展示它的载体	它胜出的原因
哪个值胜出，以及继承在哪里停止	每个叶节点都标出胜出值的 ASCII 树	表格无法呈现分支
命令会做什么	命令的真实捕获输出，再加上最少的文字	输出就是事实；关于它的文字只是复制
遇到症状时该做什么	三行：你看到什么、它意味着什么、该怎么做	症状需要原样错误和因果链，表格单元格会将其截断
版本之间的差异	一张表，包含旧形式、新形式，以及一列说明旧形式现在的作用	第四列呈现可观察到的症状，而不是规则
两种状态并列	状态矩阵，再用一句文字说明左右两栏的含义	矩阵承载状态，句子承载解读
代码如何组织	Mermaid 图，方框中标出真实文件及其 export，并由指向证明它们的测试的链接收尾	checker 可验证的方框不会过时
一个顺序	箭头流程，或编号步骤，每一步配一个执行某项内容的 fenced block	顺序就是内容本身
变更前后如何变化	变更前代码块和变更后代码块	对比本身就是可视化
简单事实	项目符号列表，每项以加粗的引导语开头，点明事实	读者扫读引导语，并在重要之处停下

更换载体后，内容的呈现速度必须快于原载体，否则就保留原载体。只有当各条目共享两个或更多、读者会按列比较的字段时，表格才真正有存在价值。把“每个条目一行”的列表改成“名称—描述”表并没有带来任何收益，应恢复原样。

单调本身也会筑成一堵墙：整页表格接表格，或项目符号接项目符号，读起来就像电子表格。应把它视为需要重新分组或合并内容的信号，而任何载体变更仍须通过上述收益检验。如果项目符号始终是每个小节中最快的载体，就保留它们。

以下四条规则适用于所有载体：

每个载体都是一项选择。 表格、项目符号列表、链接或图示之所以出现，是因为它们比散文更快呈现内容，绝不能因为上一节用了某种载体就沿用。检验方法是扫读测试（见下文的两层结构）。
一个要点只使用一个载体。 图示后接一段再次解释它的文字，说明图示失败；应修好图示或删掉文字。绝不能先用表格承载同一内容，再用散文或图示重复承载。图示的 accessible text（alt text，或供屏幕阅读器使用的一句话等价文本）不是第二个载体。
项目符号用于列表。 它承载本身就是列表或清单的条目。推理过程应保留为散文。把每个句子都变成项目符号，会掩盖哪些句子属于同一类事物。
内容读起来更好时，可以打破惯例。 去掉表格、改用三行式结构的故障排查页面，比表格更好读。在评审中说明原因，而不是写进页面。

Write for the reader who skims

为扫读的读者而写

Every reader of these pages skims, then reads one section closely. Both readers are served by the same rules, and the page holds enough detail to be useful without becoming exhaustive.

Two layers. The top layer (headings, figures, diagrams, captured blocks, the shape of tables, first sentences, emphasized text) carries the whole sense of the page on its own. The detail layer (paragraph bodies, table cells) is what a reader opens for more. Every device choice above serves the top layer.

Shape:

The most important point opens each section. A reader who stops after the first sentence leaves with the right fact.
Headings tell the story on their own ("What gates what", "When the version changes"), never the reader's level ("Simple version"). Read in sequence, the headings are the page's outline. They appear only on a page above about 500 words.
One idea per paragraph, 1 to 3 sentences, under 70 words. Short sentences, one idea each, about 20 words.
No nesting past one level. A list inside a list is content asking for a different device: a table, a tree, a subsection, whichever shows it.
The page reads from beginning to end. Sections follow the order a reader meets the subject. A fact is introduced before it is used.

Words:

Plain, direct, active. "The build writes the lockfile" rather than "the lockfile is written by the build". One term per thing, kept for the whole page. A name the reader has not met is defined where it first appears, in plain words before the mechanism name ("the check that gates every merge" comes before its job name,
```
merge-gate
```
).
Example first, then the rule. The block or the row shows it. The sentence after says what it means.
Show the artifact. Log lines, error text, and tree output are quoted verbatim, never paraphrased.
Programmer register. Precise nouns, the repository's own names, no marketing.
```
/unslop
```
, where installed, removes the AI tells that survive.

Facts:

One owner per fact. A fact lives on one page. Other pages link to it in the sentence that needs it (
```
the [retry page](retries.md#the-limit) owns this limit
```
) and never restate it. A separate links or navigation section exists only when the page is an index.
Every internal link works. The target exists and the anchor names a heading on it. The probe checks the targets, and the anchors are read.
Mark what kind of fact it is. A confirmed fact stands bare. An assumption, a claim supplied by someone else, a risk, a recommendation, or anything not independently verified is labeled as such where it appears ("a guess, to save a round trip" or "reported by the user, not reproduced").
Cut only what the reader does not need. Implementation detail, repetition, and filler go, while definitions, reasoning, limitations, and next steps stay. A cut is a content change the PR names, and a restructure (below) moves every fact and cuts none.
Open with one orienting sentence saying what the page is and what it is not, then whatever the reader needs first. Never background.

这些页面的每位读者都会先扫读，再仔细阅读其中一个小节。同一套规则要同时服务这两种读者；页面应包含足够的细节以保持实用，又不应穷尽一切。

两层结构。 上层（标题、插图、图示、捕获的代码块、表格结构、首句和强调文本）仅凭自身就能传达整页的完整含义。细节层（段落正文、表格单元格）则是读者需要时深入查看的内容。上文每一种载体选择都为上层服务。

结构：

每个小节以最重要的要点开头。 读者即使读完第一句就停下，也应掌握正确事实。
标题独立讲出完整故事（“什么控制什么”、“版本何时变化”），而不是描述读者水平（“简单版”）。按顺序阅读时，标题就是页面的大纲；仅在约 500 词以上的页面中使用标题。
每个段落只讲一个观点， 1 至 3 句，不超过 70 词。句子要短， 每句一个观点，约 20 词。
不得嵌套超过一层。 列表中嵌套列表，表明内容需要换一种载体：表格、树状结构、小节 whichever 能更清楚地展示它。
页面从头到尾都能顺畅阅读。 各小节按照读者接触主题的顺序排列。事实在被使用之前先作介绍。

措辞：

平实、直接、主动。 “构建会写入 lockfile”，而不是“lockfile 由构建写入”。同一事物全页只使用一个术语。读者尚未见过的名称，在首次出现处先用平实语言定义，再给出机制名称（“控制每次 merge 的 check”出现在 job 名称
```
merge-gate
```
之前）。
先给示例，再讲规则。 代码块或表格行先展示内容，后面的句子再解释其含义。
展示工件。 日志行、错误文本和树状输出均原样引用，绝不转述。
程序员式表达。 使用精确名词和仓库自身的名称，不使用营销语言。已安装
```
/unslop
```
时，它会移除仍然存在的 AI 写作痕迹。

事实：

每项事实只有一个归属页面。 其他页面在需要它的句子中链接过去（
```
the [retry page](retries.md#the-limit) owns this limit
```
），绝不重复陈述。只有当页面是索引时，才可以设置单独的链接或导航小节。
每个内部链接都能正常工作。 目标必须存在，且锚点对应目标页面中的某个标题。probe 会检查目标，并读取锚点。
标明事实的类型。 已确认事实无需标签，直接陈述。假设、他人给出的主张、风险、建议，或任何未经独立验证的内容，都应在出现处标明（“一种猜测，可省去一次往返沟通”或“用户报告，未复现”）。
只删减读者不需要的内容。 实现细节、重复和填充内容应删去，而定义、推理、限制和后续步骤应保留。删减属于内容变更，必须在 PR 中说明；重排（见下文）则会移动每一项事实，不删除任何事实。
用一句定位句开头， 说明页面是什么以及不是什么，随后给出读者最先需要的内容。不要铺垫背景。

Prose inside artifacts

工件内部的文本

Description or help text a human reads inside a code artifact is working text like any other, under the paragraph, device, and heading rules above. The artifacts:

a GitHub action or workflow
```
description
```
a package manifest's description
CLI help text
issue and PR templates

A skill's frontmatter description is excluded: it is a trigger, owned by the

/craft-skills-and-memories

skill.

The artifact-specific facts:

An action description is a literal block (
```
|
```
).
Input and output descriptions are one sentence each.
Never
${{
inside an action or workflow description. GitHub evaluates it when the file loads, and a stray
```
${{
```
fails the action as soon as it loads.

人类会在代码工件中读到的描述或帮助文本，与其他文本一样都属于工作文本，同样遵循上文的段落、载体和标题规则。相关工件包括：

GitHub action 或 workflow 的
```
description
```
package manifest 的 description
CLI help text
issue 与 PR 模板

skill 的 frontmatter description 不在此范围内：它是一个触发器，由

/craft-skills-and-memories

skill 负责。

与具体工件有关的事实：

action 描述使用字面量块（
```
|
```
）。
输入和输出描述各写一个句子。
绝不要在 action 或 workflow 描述中使用
```
${{
```
。GitHub 会在加载文件时对其求值，而多余的
```
${{
```
会导致 action 在加载时立即失败。

The probe

Probe

The probe reports the two readings a reviewer otherwise takes by eye.

scripts/docs-probe.mts

ships with this skill and reads a page's prose units, the paragraphs and list items.

Front matter, headings, fences, tables, comments, and generated regions are not prose. The probe reports:

a unit over the cap (
```
--max-words
```
, default 70), with the line it starts on
a repository path the prose names that does not exist: a backticked
```
<dir>/<file>.<ext>
```
,
```
./<file>
```
,
```
../<file>
```
, or
```
<dir>/
```
, or a relative link target

Replace the angle-bracket placeholders with the repository's own paths.

bash

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

text

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

The path check leaves alone, on purpose: placeholders (

<skill-dir>/x

), globs,

owner/repo

slugs, absolute paths, and bare file names (

package.json

). It also leaves alone a path whose first segment exists nowhere between the page and the root, nor under a

--base

(a page describing another layout).

A path resolves against the root, the page's directory, every directory between, and each

--base

. So a skill's reference page may name a script under its own

scripts/

folder, and a page describing a template may name a file by the path it will have in the repositories generated from it.

The cap becomes a gate, not a taste, when the repository's check command enforces it: through a published package (the same cap ships as a Vale rule under

vale/

, for repositories that already run Vale) or through the repository's own probe. A skill's script stays an instrument run from the skill directory, never copied into a repository.

probe 会报告评审者原本只能凭肉眼完成的两种阅读结果。

scripts/docs-probe.mts

随本 skill 一同提供，用于读取页面中的散文单元，即段落和列表项。

Front matter、标题、代码围栏、表格、注释和生成区域不属于散文。probe 会报告：

超过上限的单元（
```
--max-words
```
，默认 70），并给出其起始行
散文提到的仓库路径不存在：带反引号的
```
<dir>/<file>.<ext>
```
、
```
./<file>
```
、
```
../<file>
```
或
```
<dir>/
```
，或相对链接目标

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

bash

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

text

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

进行解析。因此，skill 的参考页面可以提到其自身

scripts/

目录下的脚本，而描述模板的页面可以按照文件在由该模板生成的仓库中的路径来命名。

当仓库的检查命令强制执行该上限时，它就不再只是审美偏好，而会成为硬性关卡：既可以通过已发布的 package（同一上限也会作为 Vale rule 随

vale/

提供给已运行 Vale 的仓库），也可以通过仓库自己的 probe 来强制执行。skill 的 script 应始终作为工具从 skill 目录运行，绝不能复制进仓库。

Restructuring an existing page

重构现有页面

Reshaping prose moves facts. The change must move all of them and only them.

Census before: the headings and anchors (
```
grep -n '^#' <page>
```
), and the probe's finding count.
Reshape. Every fact of the old paragraph lands somewhere on the new page. A fact the old page did not state does not appear.
Census after: the same headings and anchors (another page may link to one), and the probe clean.
Review the pair with the
```
/rubber-duck-review
```
skill where installed, with this standing question. List every fact of the old page absent from the new, and every fact of the new page absent from the old. Both lists empty is the pass.

The PR body shows one paragraph before and after, as the specimen above does, and carries both censuses.

重塑文本会移动事实。变更必须移动全部事实，并且只移动这些事实。

变更前清点：标题和锚点（
```
grep -n '^#' <page>
```
），以及 probe 的 finding 数量。
重塑。旧段落中的每一项事实都必须落到新页面的某个位置。旧页面未陈述的事实不得出现。
变更后清点：标题和锚点保持相同（其他页面可能链接到其中之一），并确认 probe 检查通过。
在已安装
```
/rubber-duck-review
```
skill 的情况下，用以下固定问题评审前后版本。列出旧页面中所有未出现在新页面的事实，以及新页面中所有未出现在旧页面的事实。两份清单均为空即为通过。

PR 正文应像上文样本一样展示变更前后的一个段落，并附上两次清点结果。

The architecture page

架构页面

The page kind with the most to rot has its own recipe in

references/architecture-page.md

. The recipe is one layering declaration, a lint that fails in both directions, a module map rendered from the declaration, and a page test. The page test checks that every diagram box names a file that exists and a symbol it exports.

最容易过时的一类页面在

references/architecture-page.md

中有专属 recipe。该 recipe 包含一份分层声明、一项能从两个方向报错的 lint、由该声明渲染的 module map，以及一个页面测试。页面测试会检查每个图示方框是否都标出真实存在的文件，以及该文件 export 的 symbol。

Review Criteria

评审标准

A paragraph or list item over 70 words (run
```
docs-probe.mts
```
rather than counting by eye), or a paragraph over three sentences.
Prose that describes what a device would show in one glance: a command without its output, a rule the reader must reconstruct from a paragraph, a break whose observable symptom is not stated.
A device change with no gain (a one-line list turned into a name-and-description table), device monotony where regrouping or merging the content would have read faster (table after table, bullet after bullet), or content carried twice (a paragraph re-explaining a diagram, a bullet restating an arrow, but not a diagram's alt text or one-sentence screen-reader equivalent).
A fact restated on a second page where a link to its owner would do.
An internal link whose target or anchor does not resolve.
A links or navigation section on a page that is not an index.
A heading naming the reader's level instead of the content.
Headings that do not outline the page when read in sequence, or headings on a page under about 500 words.
A section whose key point sits after the setup, or a list nested inside a list.
Bullets carrying a line of reasoning that should be prose.
A page whose top layer (headings, figures, diagrams, captured blocks, the shape of tables, first sentences, emphasized text) does not carry the story on its own.
An assumption, a supplied claim, a risk, a recommendation, or an unverified reading presented as a confirmed fact.
A shortened page that dropped a definition, a reason, a limitation, or a next step the reader needed.
A path, link, symbol, or check the page names that does not exist (the probe for paths and links,
```
scripts/architecture/check-page.mts
```
for diagram boxes).
A reshaped page that lost a fact, added one, or dropped a heading anchor another page links to.
An architecture page whose module map shows an edge the code does not draw.
A box naming a symbol its file does not export, or a concept diagram with no
```
Demonstrated by:
```
line.
Prose inside a code artifact, per this skill's "Prose inside artifacts" subsection, that breaks the page rules. An action description that is not a literal block, or that gives an input or output more than one sentence.
```
${{
```
inside an action or workflow description.
Wall-of-text prose anywhere a human skims: docs, reports, PR text (the
```
/pr-and-issue-discipline
```
skill owns the PR body's content).

超过 70 词的段落或列表项（运行
```
docs-probe.mts
```
，不要靠肉眼计数），或超过三句的段落。
用散文描述本可由载体一眼展示的内容：只有命令却没有输出；需要读者从段落中自行还原的规则；未说明可观察症状的版本差异。
没有收益的载体变更（把每个条目一行的列表改成“名称—描述”表）、若重新分组或合并内容本可读得更快却仍然单调的载体（表格接表格、项目符号接项目符号），或内容被重复承载（用段落重新解释图示、用项目符号复述箭头；但图示的 alt text 或一句话的屏幕阅读器等价文本不算重复）。
某个事实在第二个页面上被重复陈述，而链接到其归属页面即可。
无法解析目标的内部链接。
非索引页面上设置了链接或导航小节。
标题描述读者水平，而不是内容。
按顺序阅读时，标题无法勾勒页面脉络；或约 500 词以下的页面设置了标题。
某个小节把关键要点放在背景设置之后，或列表中嵌套列表。
项目符号承载了本应写成散文的推理过程。
页面的上层（标题、插图、图示、捕获的代码块、表格结构、首句和强调文本）无法独立讲出完整故事。
将假设、他人给出的主张、风险、建议或未经核实的解读表述为已确认事实。
精简后的页面删掉了读者需要的定义、原因、限制或后续步骤。
页面提到的 path、link、symbol 或 check 不存在（path 和 link 使用 probe，图示方框使用
```
scripts/architecture/check-page.mts
```
）。
重塑后的页面丢失了事实、添加了事实，或删除了其他页面链接的标题锚点。
architecture 页面中的 module map 画出了代码中不存在的 edge。
方框提到其文件未 export 的 symbol，或概念图缺少
```
Demonstrated by:
```
行。
代码工件内部的文本违反本 skill 的“工件内部的文本”小节规则。action 描述未使用字面量块，输入或输出描述超过一个句子，或 action 或 workflow 描述中包含
```
${{
```
。
任何供人扫读之处出现大段文字：文档、报告、PR 文本（PR 正文的内容由
```
/pr-and-issue-discipline
```
skill 负责）。