documentation-impact

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation impact

文档影响

Match the documentation to the behavior people will use. Inspect the actual change and its callers before deciding which docs need work. A supported no-change conclusion is a complete result.

让文档与人们实际使用时的行为保持一致。在决定哪些文档需要处理之前，检查实际变更及其调用方。得出“无需变更”的结论也是完整结果。

Choose the mode and scope

选择模式和范围

Use

author

when the task authorizes documentation updates. Use

review

for an audit, independent review, status request, or other read-only task. Honor the caller's mode. If update authority is unclear, inspect and report in

review

mode.

In
```
author
```
mode, update affected documentation within the authorized change. Leave unrelated edits alone.
In
```
review
```
mode, inspect without editing the artifact you judge. Return findings to its author. Do not fix a document and certify your own fix.

The calling workflow owns delegation, model selection, continuation, and human gates. Do not spawn another coordinator or start a publication workflow here.

Use the accepted request, issue, or existing work brief. Do not require a new spec, ticket, docs tree, or work ledger.

Bind the pass to what you actually examine:

For committed work, resolve and record the fixed base and head. Inspect the base-to-head diff and the surrounding implementation and documentation at those revisions.
For local work, also inspect staged and unstaged changes and relevant untracked files. Record a content fingerprint or retained snapshot of those inputs. A clean-looking HEAD or a filename list does not identify dirty file contents.
Outside Git, record an explicit content snapshot of the scoped implementation and docs. If a relevant input is unavailable, name the gap instead of claiming coverage.

Record the examined paths and either the fingerprint method or the retained snapshot location so another agent can reproduce the comparison. Recheck the inputs before returning the result. If concurrent edits changed them, refresh the affected checks or report that the result no longer describes the current artifact.

当任务授权更新文档时，使用

author

。对于审查、独立复核、状态请求或其他只读任务，使用

review

。遵循调用方指定的模式。如果更新权限不明确，则以

review

模式进行检查并报告结果。

在
```
author
```
模式下，在授权范围内更新受影响的文档。不要改动无关内容。
在
```
review
```
模式下，只检查而不编辑所审查的产物。将发现返回给其作者。不要修复文档后再认证自己的修复结果。

调用方工作流负责委派、模型选择、续接和人工关卡。不要在此处启动另一个协调器或发布工作流。

使用已接受的请求、issue 或现有工作简报。不要要求提供新的 spec、ticket、docs tree 或 work ledger。

将本次检查与实际检查的内容绑定：

对于已提交的工作，解析并记录固定的 base 和 head。检查 base 到 head 的 diff，以及这些修订版本中的相关实现和文档。
对于本地工作，还要检查已暂存、未暂存的变更以及相关的未跟踪文件。记录这些输入的内容指纹或保留的快照。看起来干净的 HEAD 或文件名列表无法标识脏文件的具体内容。
在 Git 之外，记录范围内实现和文档的明确内容快照。如果无法获取相关输入，请指明缺口，而不是宣称已经覆盖。

记录已检查的路径，以及指纹方法或保留快照的位置，以便其他 Agent 复现比较。返回结果前重新检查输入。如果并发编辑导致输入发生变化，请刷新受影响的检查，或报告结果已不再描述当前产物。

Map the change to readers

将变更映射到读者

Read the repository's instructions and discover where its maintained docs and examples live. Trace changed behavior to the people who use, run, upgrade, or develop the project. Include public workflow changes in skills and configuration, even when no application code changed.

Consider these document types where the change affects them:

Changed behavior	Candidate documentation
Installation, onboarding, or basic usage	README, quickstarts, tutorials
Commands, APIs, flags, defaults, configuration, or environment variables	CLI and API reference, configuration guides, executable examples
Compatibility, storage, or upgrade behavior	Migration and upgrade instructions, deprecation notices
Release-visible behavior	Release notes or changelog, if the repository maintains them
Module boundaries, data flow, or operational behavior	Architecture explanations, diagrams, runbooks, developer guides

Search for old names, old values, and contradictory examples beyond files already changed. Read the matched claims in context. A recent timestamp, a path match, generated prose, or a rendered diagram cannot establish factual accuracy.

For each affected reader task, identify the maintained document or explain why no document needs a change. Existing docs may already be correct. Internal refactoring may leave every documented contract unchanged. Do not create filler docs to make the pass appear productive.

阅读仓库的说明，并找出其中维护的文档和示例所在位置。将发生变化的行为追踪到使用、运行、升级或开发项目的人。即使没有应用代码变更，也应包含 skills 和配置中的公开工作流变更。

如果变更影响以下文档类型，应加以考虑：

变化的行为	候选文档
安装、引导或基本用法	README、快速入门、教程
命令、API、flags、默认值、配置或环境变量	CLI 和 API 参考、配置指南、可执行示例
兼容性、存储或升级行为	迁移和升级说明、弃用通知
对外可见的发布行为	Release notes 或 changelog（如果仓库维护这些文档）
模块边界、数据流或运行行为	架构说明、图表、runbooks、开发人员指南

除已变更的文件外，还要搜索旧名称、旧值和相互矛盾的示例。结合上下文阅读匹配到的陈述。最近的时间戳、路径匹配、生成的文本或渲染后的图表都不能证明事实准确性。

对于每个受影响的读者任务，确定对应的维护文档，或者解释为什么无需更改文档。现有文档可能已经正确。内部重构可能不会改变任何已记录的契约。不要为了显得检查有成效而创建填充性文档。

Update or inspect

更新或检查

author

mode, make the smallest corrections needed for the changed behavior. Follow the repository's documentation layout and generation commands. Update the source of generated docs instead of hand-editing generated output.

Use the technical-writing skill on documentation you write or review. Then use the unslop skill on it. Keep examples tied to real symbols, paths, flags, defaults, and supported versions. If an upgrade requires user action, state that action and the old-to-new behavior.

Trace documented effects through the implementation. Accepting or reporting a setting does not prove that the corresponding operation runs. If intended behavior and observed behavior disagree, report the mismatch as an implementation finding instead of documenting a defect as supported behavior.

review

mode, derive the affected reader tasks from the implementation yourself. Check the author's coverage decisions against the source, including claims that nothing changed. Treat the author's receipt as evidence to inspect, not as the verdict.

Use the repository's existing diagram format when a diagram explains an affected relationship better than prose. Check each changed actor, edge, direction, and boundary against the implementation. Optional visual tools can help present findings if available. Otherwise use Markdown or the existing diagram source. Do not install a visual dependency, require branding input, or wait for annotation feedback to complete this pass.

在

author

模式下，仅进行更改行为所需的最少修正。遵循仓库的文档布局和生成命令。对于生成的文档，应更新其源文件，而不是手动编辑生成结果。

对编写或审查的文档使用 technical-writing skill，然后对其使用 unslop skill。让示例与真实的符号、路径、flags、默认值和受支持的版本保持一致。如果升级需要用户采取行动，请明确说明该行动以及升级前后的行为变化。

通过实现追踪文档所描述的影响。接受或报告某个设置，并不能证明对应的操作一定会执行。如果预期行为与实际行为不一致，请将这种不匹配作为实现问题报告，而不要将缺陷记录为受支持的行为。

在

review

模式下，根据实现自行确定受影响的读者任务。依据源码检查作者对覆盖范围的判断，包括“没有任何变化”的结论。将作者的回执视为需要检查的证据，而不是最终结论。

如果图表比文字更能说明受影响的关系，请使用仓库现有的图表格式。依据实现检查每个发生变化的 actor、edge、direction 和 boundary。如果可用，可选的可视化工具可以帮助呈现发现。否则使用 Markdown 或现有的图表源文件。不要安装可视化依赖、要求提供品牌素材输入，或等待标注反馈后才完成本次检查。

Decide whether author mode requires review

判断 author 模式是否需要审查

An author pass returns exactly one result:

```
independent review required
```
when documentation changed, a public workflow or documented contract changed, or a documentation gap remains unresolved.
```
independent review not required
```
only when evidence shows that an internal change has no documentation impact.

independent review not required

is invalid for a public workflow or documentation change. Record the evidence that supports the author result with the examined artifact. A completion or shipping workflow can start an independent review only when the author result is

independent review required

When independent review is required, a different agent reviews the resulting artifact without editing it. The independent review verdict is

pass

needs changes

, or

unverified

. After repairs, the reviewer checks the resulting artifact before returning

pass

. Reuse the verdict only while its examined change, docs, and relevant surrounding context still match. A matching stable patch-id after a rebase does not establish that the documentation context is unchanged. Recheck that context or rerun the pass.

一次 author 检查仅返回以下一种结果：

```
independent review required
```
：文档已更改、公开工作流或已记录的契约发生变化，或者仍存在未解决的文档缺口。
```
independent review not required
```
：仅当证据表明内部变更没有任何文档影响时，才能使用此结果。

对于公开工作流或文档变更，

independent review not required

是无效结果。记录支持 author 结果的证据以及已检查的产物。完成或发布工作流仅可在 author 结果为

independent review required

时启动独立审查。

需要独立审查时，应由不同的 Agent 在不编辑产物的情况下进行审查。独立审查结论为

pass

、

needs changes

或

unverified

。修复完成后，审查者必须再次检查修复后的产物，然后才能返回

pass

。仅当所检查的变更、文档及相关上下文仍然一致时，才能复用之前的结论。rebase 后得到相同的稳定 patch-id，并不能证明文档上下文未发生变化。请重新检查上下文或重新执行检查。

Verify and return the result

验证并返回结果

Run the relevant repository documentation checks and exercise changed examples against the actual implementation when safe within the task's authority. Use the verify-commands skill on commands used as completion evidence. In review mode, run checks without modifying the reviewed files, using a disposable copy if the check writes output.

Check factual meaning as well as syntax and rendering. An example that runs with the wrong default or a diagram that invents an approval step is still wrong. Report unsafe or unavailable checks as gaps. Never run a deployment, publish docs, or change external data just to verify an example.

Return a compact result in the conversation or the existing work record:

The mode, scope, and examined revision or snapshot, including relevant local changes.
The affected reader tasks and document paths, with updates made or evidence for leaving them unchanged.
The checks actually run, their outcomes, and any remaining findings or verification gaps.
In author mode, the author result and its evidence. In review mode, return
```
pass
```
,
```
needs changes
```
, or
```
unverified
```
. Use
```
needs changes
```
for established omissions or incorrect claims. Use
```
unverified
```
when missing evidence prevents a decision.

An author result is not an independent review verdict.

运行仓库的相关文档检查，并在任务权限允许且安全的情况下，针对实际实现演练发生变化的示例。对作为完成证据使用的命令使用 verify-commands skill。在 review 模式下运行检查时不得修改被审查的文件；如果检查会写入输出，请使用临时副本。

不仅要检查语法和渲染效果，还要检查事实含义。即使示例能够运行，但使用了错误的默认值，或者图表虚构了审批步骤，该示例仍然是不正确的。将不安全或无法执行的检查报告为缺口。不得仅为验证示例而运行部署、发布文档或更改外部数据。

在对话或现有工作记录中返回简明结果：

模式、范围以及已检查的修订版本或快照，包括相关的本地变更。
受影响的读者任务和文档路径，以及已进行的更新或无需更改的证据。
实际运行的检查及其结果，以及任何剩余问题或验证缺口。
在 author 模式下，返回 author 结果及其证据。在 review 模式下，返回
```
pass
```
、
```
needs changes
```
或
```
unverified
```
。对于已确认的遗漏或错误陈述，使用
```
needs changes
```
。当缺少必要证据导致无法作出判断时，使用
```
unverified
```
。

author 结果不等于独立审查结论。