document-what-shipped

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Document what shipped

记录已上线的内容

A decided design is not a shipped one. That sentence is the whole skill, and it is in the name because it is the thing a session forgets at exactly the wrong moment - when a decision record, a plan or an ADR describes the behaviour so clearly that reading the running system feels like a formality.

It is not a formality. The draft this method replaced said the reject link "asks for a reason from a short list and closes the quote as lost". True in the decision record. Untrue in the product: the link opened a page saying an Agent would be in touch, and closed nothing. Two more claims in the same draft were false the same way, and one claim written by the agent doing the measuring was false too - "nothing notifies the Agent", written after reading the C# only, while a CRM workflow had been sending that email all along, 16 seconds after the press.

So the deliverable is not a document. It is one page whose every sentence a person can check, plus the record that says how each sentence was checked.

  ONE RUN = ONE PAGE
  ─────────────────────────────────────────────────────────────
  ⓪ FOUR ANSWERS      type · reader · system+environment · destination
  │                   any one missing → ask, do not assume
  ▼
  ① SHOT LIST         numbered pictures the page needs
  │                   gate opens ONLY on files, or a plain "no images"
  ▼
  ② FACT LEDGER       every fact × three places · live journey first
  │                   no place answers it → it is NOT BUILT, not a sentence
  ▼
  ③ DRAFT             one page, one spine, holes visible
  ▼
  ④ SNAPSHOT          live page + version token, before any write
  ▼
  ⑤ HAND OVER         and STOP. Only the owner says publish
  ▼
  ⑥ PUBLISH           If-Match / fast-forward · read back · probe
  ▼
  ⑦ PROVE IT          resolve EVERY link · publish record · one ticket comment

已敲定的设计不等于已上线的功能。这句话是本skill的核心，也是命名的由来——因为团队总会在最不该疏忽的时刻忘记这一点：当决策记录、计划或ADR（架构决策记录）把功能描述得足够清晰时，去查看运行中的系统就成了一种形式主义。

但这绝不是形式主义。之前的一份草稿提到，拒绝链接“会要求用户从短列表中选择原因，并将报价标记为流失”。这在决策记录里是正确的，但在实际产品中却并非如此：点击该链接会打开一个页面，提示Agent将联系用户，且不会关闭任何内容。同一份草稿里还有两处类似的错误描述，就连负责验证的人员也写错了一点——“没有通知Agent”，这是仅查看C#代码后得出的结论，但实际上CRM工作流一直在点击按钮16秒后发送通知邮件。

因此，交付物不是一份普通文档，而是每一句话都可被验证的单页文档，再加上记录每句话验证方式的台账。

  ONE RUN = ONE PAGE
  ─────────────────────────────────────────────────────────────
  ⓪ FOUR ANSWERS      type · reader · system+environment · destination
  │                   any one missing → ask, do not assume
  ▼
  ① SHOT LIST         numbered pictures the page needs
  │                   gate opens ONLY on files, or a plain "no images"
  ▼
  ② FACT LEDGER       every fact × three places · live journey first
  │                   no place answers it → it is NOT BUILT, not a sentence
  ▼
  ③ DRAFT             one page, one spine, holes visible
  ▼
  ④ SNAPSHOT          live page + version token, before any write
  ▼
  ⑤ HAND OVER         and STOP. Only the owner says publish
  ▼
  ⑥ PUBLISH           If-Match / fast-forward · read back · probe
  ▼
  ⑦ PROVE IT          resolve EVERY link · publish record · one ticket comment

⓪ Four answers before anything is read

⓪ 先明确四个问题，再开展任何阅读工作

Ask all four at the start, in one message, and wait. Each one changes what gets measured, so guessing any of them means measuring twice - and the second pass happens after a draft exists, which is when measurement gets skipped.

answer needed	how to ask it	if it is missing
Which type of page?	offer the five spines by the reader's question, plus other	ask. Never infer from the request wording
Who reads it?	propose from the type and destination: "Reader: management, on the GlassHull wiki. Correct?"	ask
Which system, which environment?	name the product and the environment you will measure	stop. See ① below
Where does it get published?	name the destination and the parent page	ask

Read

references/page-spines.md

for the five spines and their sections, and

references/register.md

once the reader is named.

An unnamed environment stops the run. Not a caveat banner - a stop, with a question. In this repo the trunk carries 390 of the tree's frontend and api files while the delivery ref that was actually deployed carries 753, so "the code" is not one thing and a page written from the wrong one describes a product that does not exist. A manual whose subject cannot be identified cannot be re-checked by anybody, including you next month.

The type may be one the five spines do not cover. Then take other: ask for the reader's question, propose a spine from it, and at the end of the run write that spine into
references/page-spines.md
marked unproven. A type answered once should never be improvised twice.

一开始就一次性提出这四个问题，等待答复。每个问题都会影响验证的内容，所以猜测任何一个问题的答案都意味着要重复验证——而第二次验证往往是在草稿完成后进行的，这时很容易跳过验证步骤。

需要明确的问题	提问方式	若未得到答复
页面类型是什么？	根据读者的需求提供五种文档框架选项，再加“其他”选项	询问，切勿从请求措辞中推断
目标读者是谁？	根据页面类型和发布目标提出建议：“读者是管理层，发布至GlassHull wiki，对吗？”	询问
针对哪个系统、哪个环境？	明确你将验证的产品和环境	停止工作，参见下文①
发布至何处？	明确发布目标和父页面	询问

查看

references/page-spines.md

了解五种文档框架及其章节，确定读者后查看

references/register.md

。

未明确环境则停止工作。不要加免责横幅，直接停止并询问。在本代码库中，主干分支包含390个前端和API文件，而实际部署的交付分支包含753个文件，因此“代码”并非单一实体，基于错误分支撰写的文档描述的是不存在的产品。无法明确验证对象的手册，任何人都无法重新验证，包括你自己下个月也做不到。

页面类型可能不在五种框架范围内。此时选择“其他”：询问读者的核心需求，据此提出一个框架，并在本次任务结束后将该框架写入
references/page-spines.md
，标记为“未验证”。同一类型的页面不应重复临时搭建框架。

① The shot list, before the draft exists

① 先确定截图清单，再撰写草稿

Hand over a numbered list of the pictures the page intends to show - one row per step, saying what each picture must contain. "Do you have screenshots?" is not answerable; this is.

  1. the Send dialog, showing the voyage list and the Send button
  2. the email as the customer receives it, showing one button per voyage
  3. the confirm page, showing the vessel and the departure date

The gate opens only on an explicit answer. Files handed over, or a plain "no images" / "the diagram is enough". Silence, "later", "maybe", and simply moving on to another instruction all leave it closed - ask once more. An absent answer is not a decline.

Once the files are handed over, read them through
read-picture
. Load the

read-picture

skill via your harness's mechanism, asking kind

on-screen-text

for the words this page will quote - button labels, page titles, status names. It answers from the project's picture record when that picture has already been read for the same question, and opens the image when it has not. Carry its not-re-checked flag into ② - a row whose bytes could not be confirmed is not evidence for a sentence on a published page.

A diagram may replace a picture, and it does not replace what the picture proved. A screenshot is evidence the thing exists and carries the exact words on the button; a diagram shows order, branch and state, and proves nothing about what shipped. So when a step is covered by a diagram instead:

quote its on-screen names - button labels, page titles, status words - from the measurement, never from memory, because the picture that would have caught a wrong label is not there;
make sure the diagram actually carries that step, not merely sits near it.

A step with neither stays a visible hole in the draft, written as a line on the page:

> Screenshot needed: the Send dialog showing the voyage list.

Recording the gap in a side file is what happened before, and no reader of a wiki opens the side file - a thin section reads as a complete one.

提交一份带编号的截图清单，列出页面需要展示的内容——每一步对应一项，说明每张截图必须包含的元素。“你有截图吗？”这种问题无法得到明确答复，而清单可以。

  1. 发送对话框，显示航程列表和发送按钮
  2. 用户收到的邮件，显示每个航程对应的按钮
  3. 确认页面，显示船舶信息和出发日期

只有得到明确答复才能进入下一步。要么收到截图文件，要么得到明确的“无需图片”/“已有足够示意图”答复。沉默、“稍后再说”、“可能需要”或直接跳转到其他指令，都意味着无法进入下一步——再询问一次。未答复不等于拒绝。

收到文件后，通过
read-picture
工具查看。通过你的工具加载

read-picture

skill，调用

on-screen-text

获取页面将引用的文字——按钮标签、页面标题、状态名称。如果同一张图片已针对同一问题被查看过，它会从项目的图片记录中获取答案；如果没有，则打开图片查看。将未重新验证的标记带入步骤②——无法确认字节内容的记录不能作为已发布页面中语句的证据。

示意图可替代截图，但无法替代截图能验证的内容。截图能证明功能存在，并显示按钮上的准确文字；示意图仅展示顺序、分支和状态，无法证明已上线的实际情况。因此，当某一步用示意图替代截图时：

从验证结果中引用屏幕上的名称——按钮标签、页面标题、状态词——切勿凭记忆引用，因为原本能发现错误标签的截图不存在了；
确保示意图确实包含该步骤，而不仅仅是放在附近。

既无截图也无示意图的步骤，在草稿中要明确标注缺失，在页面上写成：

> 需补充截图：显示航程列表的发送对话框

。之前的做法是将缺口记录在侧边文件中，但wiki读者不会打开侧边文件——内容单薄的章节会被误认为是完整的。

② The fact ledger - every fact, three places

② 事实台账——每个事实，三个验证来源

For each fact the page will state, read all three places that can answer it:

place	what it answers	how it lies
authored code	what we wrote	it is silent about everything the platform does for us
the platform's own automation	workflows, plug-ins, triggers, jobs, rules, integrations	a sweep of one storage column misses a whole family - reading only classic definitions missed 129 cloud flows whose definition lives elsewhere
a live observation	does this ship	it is a sample. One run does not prove the second branch

Every fact. Not only the ones that look doubtful - the false claims all looked correct to their author. Where a place cannot answer a fact (a button label has no automation behind it), write not applicable; never skip it silently, because a skipped place and an absent place look the same in a week.

Two mechanisms keep this affordable, and without them the run stalls before the draft:

Plan one live journey and take it end to end first. Yesterday a single real quote proved about ten facts in one pass - the link, the confirm page, the won quote, the booking in Planning, the notification email at 16 seconds, the second press, the log row. Read the code and the automation against what the journey produced, not before it.
Cache platform state, decide from a fresh read. Save each live query with its result count and newest modified date, so staleness costs one cheap call next time. A cache orients; it never decides. Re-pull any fact in the session that puts it on the page.

The ledger is one row per fact - the fact, the places that answered, the date - and it is what makes the page auditable without re-reading the system.

A fact no place answers is not a sentence. It goes on the not built yet list, in the page's own words, or it is dropped. An entire reject flow went that way and the page is better for saying so.

对于页面要陈述的每个事实，查看所有三个能验证它的来源：

来源	验证内容	可能存在的误差
编写的代码	我们实现的逻辑	对平台为我们处理的所有内容保持沉默
平台自身的自动化工具	工作流、插件、触发器、任务、规则、集成	仅查看某一类存储定义会遗漏其他类型——仅查看经典定义会遗漏129个存储在别处的云工作流
实时观测	该功能是否已上线	仅为样本，一次运行无法证明分支逻辑的所有情况

每个事实都要验证。不仅是看起来可疑的事实——那些错误描述在作者看来都是正确的。如果某个来源无法验证某一事实（比如按钮标签背后没有自动化逻辑），请写不适用；切勿跳过不记录，因为一周后跳过的记录和不存在的记录看起来没区别。

有两种机制能让这项工作高效可行，否则任务会在草稿阶段停滞：

先规划一次完整的实时流程并从头到尾执行。昨天，一次真实的报价流程就验证了约十个事实——包括拒绝链接、确认页面、已成交报价、规划中的预订、16秒后的通知邮件、重复点击、日志记录。对照流程结果查看代码和自动化工具，而不是先看代码再看流程。
缓存平台状态，基于最新读取结果做决策。保存每次实时查询的结果数量和最新修改日期，这样下次只需一次低成本调用就能判断数据是否过期。缓存仅用于定位，不能用于决策。本次任务中任何要写入页面的事实都要重新获取。

台账按事实逐行记录——事实内容、验证来源、日期——它让页面无需重新查看系统就能被审计。

无来源可验证的事实不能写入页面。要么将其加入“尚未实现”列表，用页面的语言表述，要么直接删除。整个拒绝流程曾因此被加入该列表，最终页面反而更准确。

③ Draft one page

③ 撰写单页草稿

One run publishes one page. A companion page is a second run, with its own shot list and its own measurement pass - and by then the first page exists, so the link between them is written against a path that has been read rather than guessed.

Follow the chosen spine from

references/page-spines.md

. Three things belong on every page whatever the spine:

The provenance line, in the reader's words: "live on the development environment since 20 August 2026, proven on a real quote". Where and when and proven-or-not is what a reader can act on. The ref, the build number and the queries go in the record - a branch name on a management page is noise that goes stale one deploy later while the sentence around it still reads as current.
A not built yet section, when anything decided is unbuilt. Name it plainly, including what the reader should do instead until it ships.
The exact on-screen words, kept as the product spells them - button labels, page titles, status names. Everything else obeys
```
references/register.md
```
, which bans identifiers the chosen reader cannot act on.

No credential reaches the page. A signed accept link is a credential for the quote it names. It stays out of the page, out of the record, and out of the commit. This one does not bend for any reader.

Write the draft into the run's record folder: the repo's existing home for such records if it has one, otherwise

docs/published/<date>-<page-slug>/

. Ask only when two candidates exist. The folder lives in the repo you run in, even when the product lives elsewhere.

一次任务仅发布一篇页面。配套页面属于第二次任务，需要单独的截图清单和验证流程——届时第一篇页面已存在，因此页面间的链接可以基于已确认的路径撰写，而非猜测。

遵循

references/page-spines.md

中选定的框架。无论选择哪种框架，所有页面都必须包含以下三项内容：

来源说明行，用读者能理解的语言表述：“2026年8月20日上线至开发环境，基于真实报价验证”。读者需要知道验证的地点、时间和是否已验证。代码分支、构建编号和查询记录放在台账中——管理层页面上的分支名称是无用信息，部署一次后就会过时，但页面中的语句仍会被视为当前有效。
“尚未实现”章节，如果有已敲定但未上线的功能。明确命名该章节，说明在功能上线前读者应如何操作。
准确的屏幕文字，完全保留产品中的拼写——按钮标签、页面标题、状态名称。其他内容遵循
```
references/register.md
```
，禁止使用目标读者无法理解的标识符。

凭证不得出现在页面中。带签名的确认链接是对应报价的凭证。它不能出现在页面、台账或提交记录中。这条规则对任何读者都不例外。

将草稿写入任务的记录文件夹：如果代码库已有此类记录的存储位置，则使用该位置；否则使用

docs/published/<date>-<page-slug>/

。只有当有两个候选位置时才需要询问。无论产品部署在何处，记录文件夹都要放在当前任务所在的代码库中。

④ Snapshot, then edit where the page came from

④ 快照备份，然后在页面源文件中编辑

Before any write to a page that exists, fetch it live into

<page>-before.md

with its version token - the

ETag

in an API page store, the commit in a git file store. This is not extra work: it is the generator's input, it proves the anchors still match what the destination serves right now, and it is what turns a bad publish into one restore command. Record the token; the write replays it (

If-Match

, or a non-fast-forward push refusal) so a concurrent edit is refused rather than overwritten.

Then edit where the page came from - the publish record names its origin:

origin	how to edit it
a generator script	change the script, re-run it, and never touch its output
a person	one surgical edit, with an assert that the anchor text appears exactly once
unknown	treat as a person's page

scripts/anchored_edit.py

carries the four habits that make either safe: find a place by its own text, assert the text is unique, apply edits from the bottom of the file upward so earlier edits cannot move later anchors, and probe the result.

Then read the produced prose. Asserts prove an anchor matched; they cannot prove a sentence reads. A patch that replaced one line of a two-line sentence passed every assert and published "the Agent clears it with Add Booking, and the quote-list marker and the Agent clears it with Add Booking".

在对已存在的页面进行任何修改前，将其实时内容（包含版本令牌）保存到

<page>-before.md

中——API页面存储中的

ETag

，Git文件存储中的提交哈希。这不是额外工作：它是生成器的输入，能证明锚点仍与目标平台当前提供的内容匹配，还能将错误发布的页面一键恢复。记录版本令牌；写入时要复用该令牌（使用

If-Match

或拒绝非快进推送），这样并发编辑会被拒绝而非覆盖。

然后在页面的源文件中编辑——发布记录会标明页面的来源：

来源	编辑方式
生成器脚本	修改脚本，重新运行，切勿直接修改输出内容
人工编写的页面	做精准的外科式编辑，断言锚点文本恰好出现一次
未知来源	按人工编写的页面处理

scripts/anchored_edit.py

包含四种安全编辑习惯：通过文本定位位置、断言文本唯一、从文件底部向上应用编辑（避免早期编辑移动后续锚点）、验证结果。

然后通读生成的文本。断言能证明锚点匹配，但无法证明语句通顺。某次修改替换了两行语句中的一行，通过了所有断言，但发布后页面显示：“Agent通过添加预订清除它，报价列表标记和Agent通过添加预订清除它”。

⑤ Hand over, and stop

⑤ 交付草稿，停止工作

The run stops at the draft. Publishing is the only step other people see and it cannot be undone quietly - a wiki push is live the instant it lands. Hand over five things, so the decision is one glance:

the page title and the full destination path the write will use;
the parent page to be edited, and the single line to be added there;
the attachment names, when there are images;
what the draft deliberately leaves out - the not-built list, and any fact no place answered;
the internal links that cannot be checked yet, because they only resolve once the page exists.

Then wait. Only the owner saying publish starts ⑥. Not a passing "looks good", not a green check.

A task that names the destination is not authorisation to publish. "Put it in

wiki/

Customer-accept.md

, and the parent must link to it" describes the write; it does not approve it. The same is true of a deadline, of a path handed over in the brief, and of a destination you were given credentials for. Measured in this skill's own test: an agent following this method read a named destination file as pre-approval and published without being asked. Write the hand-over, then wait for the word.

Count the hand-over's numbers off the draft, never from memory - how many holes, how many links, how many unobserved claims. The same test produced a report claiming six screenshot holes on a page carrying three.

任务在草稿阶段停止。发布是唯一会被其他人看到的步骤，且无法悄悄撤销——wiki推送后立即生效。交付以下五项内容，让决策一目了然：

页面标题和写入时将使用的完整目标路径；
待编辑的父页面，以及要添加到父页面的单行内容；
附件名称（如有图片）；
草稿刻意省略的内容——尚未实现的功能列表、无来源可验证的事实；
目前无法验证的内部链接（只有页面发布后才能解析）。

然后等待。只有所有者明确说“发布”才能进入步骤⑥。不能是随口的“看起来不错”，也不能是通过检查的标记。

指定发布目标的任务不等于授权发布。“将其放入

wiki/

目录下的

Customer-accept.md

，且父页面必须链接到它”描述的是写入操作，而非批准发布。截止日期、任务 brief 中给出的路径、提供了凭证的发布目标，都不等于授权。在本skill的测试中：一名遵循该方法的人员将指定的目标文件视为预先批准，未经过询问就发布了。交付草稿后，等待明确的发布指令。

对照草稿核对交付内容的数量，切勿凭记忆——有多少缺失项、多少链接、多少未观测的声明。同一次测试中，一份报告声称页面有六个截图缺失，但实际只有三个。

⑥ Publish

⑥ 发布

Read

references/destinations.md

and answer its eight questions for this destination before the first write. If the destination is not one of the measured adapters, discover it live, publish, and write the measured recipe back into that file in the same run - an adapter is measured or it does not exist.

The protocol is the same in both families:

re-fetch the live page and compare it against the before-snapshot. Different? Re-run the generator against the new content; do not merge by hand;
write, carrying the version token;
read the page back and check a probe list - sentences that must be present, and sentences that must be gone;
edit the parent so the new page is reachable. A page nothing links to is not published, it is uploaded. One-way navigation was the default failure.

Mermaid fences differ per destination (

::: mermaid

on an Azure DevOps wiki, a triple-backtick fence on GitHub). The fence belongs to the destination, not to the writer.

Parse every diagram before the write.

scripts/check_mermaid.py

does it, and nothing else in this method can: the read-back probes check sentences, the link check checks links, and a diagram that does not parse renders as an error box while both pass. Measured 2026-08-21 - a sequence diagram published on 20 August contained

CRM-->>Portal: Quote closes; chosen schedule recorded

and had never rendered once. A semicolon terminates a statement in mermaid, so the tail became a new statement and the parser demanded an arrow. Two runs went past it, both with every assert green, because no assert either run made was about the diagram. A

in a label fails the same way.

The same run found the diagram was also factually wrong - one branch covered both a customer accepting and a customer rejecting, then flowed into "create booking", so it told readers a rejection creates a booking. Fixing only the parse error would have left a diagram that renders and lies, which is worse than one that fails loudly. When a diagram fails to parse, re-read what it claims before you fix the syntax - a diagram nobody could render is a diagram nobody proofread.

在首次写入前，查看

references/destinations.md

并回答针对当前发布目标的八个问题。如果目标平台不在已验证的适配器列表中，实时探索该平台、完成发布，并在本次任务中将验证后的流程写回该文件——适配器要么经过验证，要么不存在。

两类平台的发布流程相同：

重新获取实时页面，与之前的快照对比。如果内容不同？基于新内容重新运行生成器；切勿手动合并；
写入时携带版本令牌；
重新读取页面，检查探针列表——必须存在的语句，以及必须删除的语句；
编辑父页面，确保新页面可访问。没有任何链接指向的页面不是已发布，只是上传了。单向导航是最常见的失败情况。

不同平台的Mermaid语法围栏不同（Azure DevOps wiki使用

::: mermaid

，GitHub使用三重反引号围栏）。围栏格式由目标平台决定，而非作者。

写入前解析所有示意图。

scripts/check_mermaid.py

负责这项工作，其他步骤无法替代：回读探针检查语句，链接检查器检查链接，但无法解析的示意图会显示为错误框，而这两项检查都能通过。2026年8月21日的测试显示：8月20日发布的序列图包含

CRM-->>Portal: Quote closes; chosen schedule recorded

且从未成功渲染过。Mermaid中分号表示语句结束，因此后半部分变成了新语句，解析器要求添加箭头。两次任务都通过了所有断言，因为没有任何断言针对示意图。标签中的

也会导致同样的失败。

同一次任务还发现该示意图事实错误——一个分支同时包含用户接受和拒绝的流程，然后流向“创建预订”，这会误导读者认为拒绝会创建预订。仅修复语法错误会导致示意图能渲染但内容虚假，这比无法渲染更糟糕。当示意图解析失败时，在修复语法前重新核对它声称的内容——无法渲染的示意图也没人校对过。

⑦ Prove it, then record it

⑦ 验证并记录

Resolve every internal link on every page you touched, against the live destination. Not the new page only - the parent too. This is

scripts/check_links.py

, and it is the step that has caught the most: a dead link looks exactly like a page that was never created, and a parent that links to none of its children looks exactly like a parent that does.

Then write, in this order:

the publish record beside the draft: version token before and after, size change, the probes checked, the link-check result, and the page's origin so the next edit knows where to go;
one comment on the ticket, when the task came from one: the page link, the token before and after, what is still not built, and the link-check result. After the publish, never before - a comment written at draft time claims a published page while the page is still a file on disk;
commit the record folder in the same run. An uncommitted record dies with the session, and the next run re-pays the whole fact gate.

针对实时目标平台，解析所有你修改过的页面上的内部链接。不仅是新页面，还包括父页面。这由

scripts/check_links.py

完成，是发现问题最多的步骤：死链接看起来和从未创建的页面完全一样，不链接任何子页面的父页面看起来也和正常父页面一样。

然后按以下顺序记录：

在草稿旁写入发布记录：发布前后的版本令牌、文件大小变化、检查的探针、链接检查结果、页面来源（方便下次编辑时找到位置）；
如果任务来自工单，在工单上写一条评论：页面链接、发布前后的版本令牌、尚未实现的功能、链接检查结果。必须在发布后写，不能在草稿阶段——草稿阶段写的评论会声称页面已发布，但此时页面还只是本地文件；
在本次任务中提交记录文件夹。未提交的记录会随会话结束而丢失，下次任务需要重新完成所有验证步骤。

What this skill refuses

本skill拒绝的操作

To publish without the owner saying so. Draft, record, hand over the paths, stop.
To document unbuilt behaviour as working, however clearly a decision record describes it. It goes on the not-built list or it is left out.
To trust a document about the product - including its own earlier draft, and including its own summary of what it measured an hour ago.
To hand-edit a page a generator produced, or hand-merge when the generator can be re-run.
To put a credential on a page, in a record, or in a commit. A signed link is a credential.
To publish a diagram nobody parsed. It renders as an error box and every other gate passes.
To write a page whose environment nobody can name.

未得到所有者明确指令就发布。撰写草稿、记录、交付路径，然后停止。
将未上线的行为描述为已生效，无论决策记录描述得多么清晰。要么加入“尚未实现”列表，要么删除。
信任关于产品的任何文档——包括自己之前的草稿，以及自己一小时前记录的验证总结。
手动编辑生成器生成的页面，或在可重新运行生成器时手动合并内容。
将凭证放在页面、记录或提交中。带签名的链接属于凭证。
发布未经过解析的示意图。它会显示为错误框，而其他所有检查都能通过。
撰写无法明确验证环境的页面。

Red flags - stop and go back a phase

危险信号——停止并返回上一阶段

thought	what it means
"The ADR describes this precisely, I can write from it"	you are documenting a decision, not a product. Go to ②
"The code clearly does not do X"	code silence is not product silence. Read the platform automation and the live record
"There are no screenshots, I will describe it in words"	① is closed. Ask, or take a plain "no images" first
"One page plus a diagram page is tidier"	two pages is two runs. ③
"The asserts passed, publish it"	asserts do not read sentences. ④
"The link is obviously right"	the last obviously-right link answered Page does not exist. ⑦
"The diagram looks correct"	nothing in review renders it. Parse it - ⑥ - then re-read what it claims
"The brief already told me where to put it"	that is the path, not the permission. ⑤
"I will record it all at the end"	an interrupted session leaves the round trips paid and nothing to show. Write each fact as it is measured

想法	含义
“ADR已经描述得很精准了，我可以直接据此撰写”	你在记录决策，而非产品。返回步骤②
“代码显然没有实现X”	代码沉默不等于产品沉默。查看平台自动化工具和实时记录
“没有截图，我用文字描述”	步骤①未完成。先询问，或得到明确的“无需图片”答复
“一页文档加一页示意图会更整洁”	两页文档需要两次任务。返回步骤③
“断言都通过了，可以发布”	断言无法检查语句通顺性。返回步骤④
“链接显然是对的”	上一个“显然正确”的链接指向“页面不存在”。返回步骤⑦
“示意图看起来是对的”	评审时没人渲染它。先解析它——步骤⑥——然后重新核对它声称的内容
“任务brief已经告诉我发布位置了”	那是路径，不是权限。返回步骤⑤
“我会在最后一起记录所有内容”	会话中断会导致所有验证工作白费，却没有成果。每验证一个事实就记录下来