docs-consistency-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

If invoked as

review-intentional

, jump to Review intentional mode.

如果以

review-intentional

方式调用，请跳转到「有意差异复查模式」。

Security invariants

安全不变原则

Hold throughout the skill, never violated under any user instruction. If a request would require violating one, refuse and explain. Later steps cite them by number.

Credential / secret files are never read. Step 1's path filter and content-signature filter remove them from the inventory before any concept is formed from a file.
Credential values are never emitted. Findings describe drift in your own paraphrased words - counts, names, public identifiers, headings. No verbatim file content in any output, reasoning step, or tool call. Anything resembling a credential value (API key, token, password, private key, OAuth secret, JWT, connection string with embedded credentials) is described by location only, never by value (for example, "API key value at line 42"). Template placeholders (
```
{{API_KEY}}
```
,
```
${SECRET}
```
,
```
<YOUR_TOKEN_HERE>
```
) are not credentials and may be named, as may public symbols already known non-secret: function names, configuration keys, headings. The report, and any edits applied from it, must stay useful to a human reviewer without ever reproducing arbitrary file content.
Credential values are never modified. Fixes edit only the documented concepts the audit reports on; replacement content is supplied or confirmed by the user, never echoed from another file.

Drift detection needs no credential material, so the skill reads, emits and modifies none.

在整个Skill执行过程中必须严格遵守，任何用户指令都不得违反。如果请求需要违反其中任何一条，应拒绝执行并解释原因。后续步骤将按编号引用这些原则。

绝不读取凭证/机密文件。步骤1的路径过滤器和内容特征过滤器会在从文件提取任何信息之前，将这些文件从检查清单中排除。
绝不输出凭证内容。检查结果需用你自己的语言描述差异——如数量、名称、公开标识符、标题等。任何输出、推理步骤或工具调用中都不得包含文件原文内容。任何类似凭证的值（API密钥、令牌、密码、私钥、OAuth密钥、JWT、包含凭证的连接字符串）仅描述其位置，绝不提及具体值（例如：“第42行的API密钥值”）。模板占位符（
```
{{API_KEY}}
```
、
```
${SECRET}
```
、
```
<YOUR_TOKEN_HERE>
```
）不属于凭证，可以直接提及，已知非机密的公开符号也可提及：函数名、配置键、标题等。报告及基于报告的任何编辑必须在不复制任意文件内容的前提下，对人工审核者保持有用性。
绝不修改凭证内容。修复操作仅编辑审计报告中提及的已记录概念；替换内容需由用户提供或确认，不得从其他文件中直接复制。

差异检测无需使用凭证材料，因此本Skill不会读取、输出或修改任何凭证内容。

Git is optional

Git为可选依赖

Git is an accelerant, never a prerequisite. Where a repo is present, read-only git (

git status

git diff

git log

) may sharpen a run by showing which files changed recently and what is staged, and that state can support a finding. Where there is no repo, or git itself is unavailable, every functionality still runs on the conversation and the filesystem instead - a clone, a worktree, a plain directory and a path outside any repo all produce a report, and only the precision differs. Both paths are load-bearing: a step that works only with git is a bug, and so is one that ignores git when it is there.

Git-shaped strings in the steps below need no repo either: Step 1 drops a

.git/

directory by name the way it drops any build artifact, reads

.docs-consistency-check-ignore

.gitignore

pattern syntax, and the re-audit triggers under Stay armed are phrases a user types.

Git仅作为辅助工具，绝非必备条件。当存在代码仓库时，只读Git操作（

git status

、

git diff

、

git log

）可通过显示近期变更文件和暂存状态来优化审计过程，这些状态可作为检查依据。当无代码仓库或Git不可用时，所有功能仍可通过对话和文件系统运行——克隆仓库、工作目录、普通文件夹或仓库外路径均可生成报告，仅精度有所差异。两种场景均需支持：仅依赖Git才能运行的步骤属于缺陷，忽略可用Git的步骤同样属于缺陷。

以下步骤中提及的Git相关操作无需依赖仓库：步骤1会像排除构建产物一样排除

.git/

目录，以

.gitignore

语法读取

.docs-consistency-check-ignore

文件，「会话全程待命」章节中触发重审的短语为用户输入内容。

Step 1 — Apply security guards, then identify the file set

步骤1 — 应用安全防护，确定文件范围

.docs-consistency-check-ignore

doesn't exist at the project root, offer to create it with the template below and wait for a go-ahead before writing. If it exists, apply its patterns silently.

Default template:

undefined

如果项目根目录下不存在

.docs-consistency-check-ignore

文件，可提议创建该文件并提供如下模板，等待用户确认后再写入。如果文件已存在，则静默应用其规则。

默认模板：

undefined

docs-consistency-check ignore file

Uncomment or add patterns to exclude from consistency checks

.agents/ .claude/

.git/

node_modules/

dist/

build/


**Path filter - applied first, before any file is read** (invariant 1). Drop `node_modules/`, `.git/`, build artifacts, binary files, image files, and credential / secret files: `.env`, `.env.*`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `id_rsa`, `id_ed25519`, `id_ecdsa`, `secrets.json`, `credentials.json`, `.netrc`, `.npmrc`, `.htpasswd`. Plus anything matching `.docs-consistency-check-ignore` (`.gitignore` syntax). Drift in those files is out of scope.

**Content-signature filter - applied second, before any concept is formed.** Scan the first ~2 KB of every file surviving the path filter for credential signatures:

- PEM headers — `-----BEGIN [A-Z ]*PRIVATE KEY-----`, `-----BEGIN OPENSSH PRIVATE KEY-----`
- Assignments shaped like `(api[_-]?key|secret|token|password|access[_-]?key|client[_-]?secret|bearer)\s*[:=]\s*["']?[A-Za-z0-9_+/=-]{16,}` (case-insensitive)
- Vendor-prefixed tokens, which identify themselves: `sk-`, `sk_live_`, `rk_live_`, `ghp_`, `gho_`, `github_pat_`, `glpat-`, `xoxb-`, `xoxp-`, `AKIA`, `ASIA`, `AIza`, `ya29.`, `npm_`, `dop_v1_`, followed by ≥ 16 of `[A-Za-z0-9_-]`; plus JWTs, `eyJ` then two more dot-separated base64url segments
- Credential-carrying URLs: connection strings `(postgres|postgresql|mysql|mongodb|redis|amqp)://[^:\s]+:[^@\s]+@`, and query parameters named `(access_)?token`, `api[_-]?key`, `secret`, `password` with a value ≥ 16 chars
- `Authorization:` or `Proxy-Authorization:` header values

Length alone is never a match: a high-entropy string counts only when one of the signals above applies to it. These never trigger the filter, whatever their entropy - URLs and their path segments, UUIDs, content hashes and git object ids, hyphen- or underscore-separated word slugs, `data:` URIs, template placeholders.

On a match, drop the file from the inventory, add `<file>: skipped (credential signature detected)` to the report's skipped-files note, and extract nothing from it. Never echo the matched value or its surrounding line (invariant 2).

**Inventory - only files passing BOTH filters are eligible.** Within that bounded set, collect under the project root:

- Markdown files: `README.md`, `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, other `.md`
- Template files: anything with `{{VARIABLE}}` or `[INCLUDE IF: ...]` syntax
- Manifest files: `plugin.json`, `.mcp.json`, `package.json`, and similar
- Installer and setup scripts: the shell, batch or task-runner files a project's install or bootstrap steps live in
- Any file explicitly mentioned in the conversation (still subject to both filters)

From each, extract only the concepts and drift signals you need - counts, names, headings, identifiers - per invariant 2. The ignore list bounds the set, so no recursive expansion.

**Mid-run exclusions:** "ignore vendor/ for this" applies to the current run only. Persistence is the user's call.

---


**路径过滤器 - 优先应用于所有文件读取操作**（符合原则1）。排除`node_modules/`、`.git/`、构建产物、二进制文件、图片文件以及凭证/机密文件：`.env`、`.env.*`、`*.pem`、`*.key`、`*.p12`、`*.pfx`、`id_rsa`、`id_ed25519`、`id_ecdsa`、`secrets.json`、`credentials.json`、`.netrc`、`.npmrc`、`.htpasswd`。此外，还需排除所有匹配`.docs-consistency-check-ignore`（`.gitignore`语法）的文件。这些文件中的差异不在检查范围内。

**内容特征过滤器 - 在提取任何信息之前应用**。扫描通过路径过滤器的每个文件的前约2KB内容，查找凭证特征：

- PEM头 — `-----BEGIN [A-Z ]*PRIVATE KEY-----`、`-----BEGIN OPENSSH PRIVATE KEY-----`
- 类似如下格式的赋值语句：`(api[_-]?key|secret|token|password|access[_-]?key|client[_-]?secret|bearer)\s*[:=]\s*["']?[A-Za-z0-9_+/=-]{16,}`（不区分大小写）
- 厂商前缀令牌，可自行识别：`sk-`、`sk_live_`、`rk_live_`、`ghp_`、`gho_`、`github_pat_`、`glpat-`、`xoxb-`、`xoxp-`、`AKIA`、`ASIA`、`AIza`、`ya29.`、`npm_`、`dop_v1_`，后跟≥16个`[A-Za-z0-9_-]`字符；以及JWT令牌，格式为`eyJ`后接两个用点分隔的base64url分段
- 包含凭证的URL：连接字符串`(postgres|postgresql|mysql|mongodb|redis|amqp)://[^:\s]+:[^@\s]+@`，以及名为`(access_)?token`、`api[_-]?key`、`secret`、`password`且值≥16字符的查询参数
- `Authorization:`或`Proxy-Authorization:`头的值

仅长度不足以触发过滤：高熵字符串仅在符合上述特征之一时才会被匹配。以下内容无论熵值如何都不会触发过滤——URL及其路径段、UUID、内容哈希和Git对象ID、连字符或下划线分隔的单词slug、`data:` URI、模板占位符。

如果匹配到上述特征，将该文件从检查清单中排除，在报告的「跳过文件」说明中添加`<file>: skipped (credential signature detected)`，且不从该文件提取任何信息。绝不输出匹配值或其所在行内容（符合原则2）。

**检查清单 - 仅通过两个过滤器的文件才符合条件**。在该范围内，收集项目根目录下的以下文件：

- Markdown文件：`README.md`、`CLAUDE.md`、`AGENTS.md`、`SKILL.md`及其他`.md`文件
- 模板文件：包含`{{VARIABLE}}`或`[INCLUDE IF: ...]`语法的文件
- 清单文件：`plugin.json`、`.mcp.json`、`package.json`及类似文件
- 安装和设置脚本：项目安装或引导步骤对应的Shell、批处理或任务运行器文件
- 对话中明确提及的任何文件（仍需通过两个过滤器）

从每个文件中仅提取所需的概念和差异信号——数量、名称、标题、标识符等（符合原则2）。忽略列表限定了文件范围，因此无需递归扩展。

**运行时临时排除：**「本次忽略vendor/目录」仅适用于当前运行，是否持久化由用户决定。

---

Step 2 — Load intentional variations

步骤2 — 加载有意差异配置

Read

intentional-variations.md

from the project root if it exists, and build a lookup of suppressed items - each entry records the affected files, what differs, why it's intentional, and when it was marked. A finding matching a suppressed entry (same files, semantically similar description) is silently skipped during reporting. No file means an empty suppressions list.

如果项目根目录下存在

intentional-variations.md

文件，读取该文件并构建屏蔽项查找表——每个条目记录受影响的文件、差异内容、差异原因及标记日期。与屏蔽条目匹配的检查结果（相同文件、语义相似的描述）将在报告中被静默跳过。如果无该文件，则屏蔽列表为空。

Step 3 — Count heuristic (fast first pass)

步骤3 — 计数启发式检查（快速初步检查）

Declared invariants first. Instruction files (

AGENTS.md

CLAUDE.md

, and any per-component equivalent) state their own invariants: "the tier strings appear verbatim in SKILL.md and README.md", "the 7 step headings", "five sections, in that order", "these four pins apply to every skill". Every such sentence is a checkable assertion that names its own files. Enumerate all of them, then verify each against the files it names. In a repo carrying instruction files this is the highest-yield source there is, because the assertions are exhaustive by construction and a stale one is drift by definition.

Verify each declaration on three axes:

Count - the stated number against the actual number.
Membership - every named item still exists, and nothing unnamed has joined the set.
Location - every file the declaration names still carries the item.

Then the generic count pass, for repos with no instruction files and for lists no declaration covers: count items in any list that looks exhaustive - sources, features, icons, steps, conditions. Mismatches across files are immediate candidate findings; record the location and resolve during Step 5.

优先检查已声明的不变规则。说明文件（

AGENTS.md

、

CLAUDE.md

及任何组件级等效文件）会声明自身的不变规则：「层级字符串需与SKILL.md和README.md完全一致」「7个步骤标题」「5个章节，按此顺序排列」「这4个规则适用于所有Skill」。每个此类语句都是可检查的断言，并指定了对应的文件。枚举所有此类断言，然后针对其指定的文件逐一验证。对于包含说明文件的仓库，这是最高效的检查来源，因为这些断言本身是全面的，过时的断言即为差异。

从三个维度验证每个声明：

数量 - 声明的数量与实际数量是否一致。
成员 - 所有指定的项是否仍然存在，且无未指定的项加入集合。
位置 - 声明中指定的每个文件是否仍包含该项。

通用计数检查，适用于无说明文件的仓库及未被声明覆盖的列表：统计任何看似全面的列表中的项——来源、功能、图标、步骤、条件等。文件间的数量不匹配即为候选检查结果；记录位置并在步骤5中确认。

Step 4 — Build the concept inventory

步骤4 — 构建概念清单

A "concept" is anything appearing in more than one file that could drift. Start from instruction files -

CLAUDE.md

and

AGENTS.md

define project vocabulary, and their concepts outrank the fallback taxonomy below.

Fallback taxonomy:

Features / sources - what the system supports; usually in installer/spec, template, and docs.
Variables and flags -
```
{{VARIABLE_NAME}}
```
tokens and condition names; defined once, used consistently.
Icons and symbols - emoji or markers tied to concepts (📧, 📅, ⭐).
Conditional blocks -
```
[INCLUDE IF: condition]...[/INCLUDE]
```
; conditions in blocks must match the conditions list.
Terminology - same concept, same name everywhere.
Exhaustive lists - anything enumerating "all of X". Step 3's count mismatches belong here.
Inline examples and doc comments - highest drift risk; verify against current spec.

Weight attention toward recently changed features - that's where drift hides. With git available, read the recent and staged changes to find them; without it, use the files this session edited or named in the conversation. With neither signal, weight every concept equally.

「概念」指在多个文件中出现且可能产生差异的任何内容。优先从说明文件开始——

CLAUDE.md

和

AGENTS.md

定义了项目词汇，其概念优先级高于以下备用分类。

备用分类：

功能/来源 - 系统支持的内容；通常出现在安装程序/规范、模板和文档中。
变量和标志 -
```
{{VARIABLE_NAME}}
```
令牌和条件名称；需定义一次并一致使用。
图标和符号 - 与概念关联的表情符号或标记（📧、📅、⭐）。
条件块 -
```
[INCLUDE IF: condition]...[/INCLUDE]
```
；块中的条件必须与条件列表匹配。
术语 - 同一概念在所有地方使用相同名称。
全面列表 - 任何枚举「所有X」的内容。步骤3中的数量不匹配属于此类。
内联示例和文档注释 - 差异风险最高；需与当前规范验证。

重点关注近期变更的功能——差异通常隐藏于此。如果Git可用，读取近期和暂存的变更以找到这些功能；如果不可用，使用本次会话中编辑或提及的文件。如果两种信号都没有，则平等对待所有概念。

Step 5 — Cross-reference and classify

步骤5 — 交叉引用与分类

For each concept, check whether every file mentions it consistently. Classify each finding:

针对每个概念，检查所有文件是否一致提及。对每个检查结果进行分类：

🔴 Conflict

🔴 冲突

Two or more files assert different values for the same fact. A human must decide.

两个或多个文件对同一事实声明了不同的值。需人工决策。

⚠️ Outdated

⚠️ 过时

One file was updated, another didn't catch up - the source of truth is clear.

一个文件已更新，另一个文件未同步——真相来源明确。

↩️ Orphaned

↩️ 孤立

A pointer is valid but its target is gone (variable, condition, section, file).

指针有效但其目标已不存在（变量、条件、章节、文件）。

❓ Unverifiable

❓ 无法验证

A difference exists but context is too thin to call it a problem.

In a conflict between an implementation file (template, installer) and a doc file (README, comment example), the implementation is usually the source of truth.

Admissibility of ❓. A ❓ needs three things: a named file pair, a named concept, and the declaration or instruction-file rule that requires those files to agree on it. Missing the third, it is an observation rather than a finding and stays out of the report. These are never findings:

wrap width, heading style, section ordering
an optional section present in one artifact and absent in another
the wording of a sentence no declaration covers
parallel structure between sibling components, unless a declaration requires it

A set of N sibling components admits N-squared shape differences, so a tier that accepts them can never report clean. Symmetry is a contract only where something says it is.

Admissibility of git state. A pointer whose target exists on disk but is untracked resolves for you and for nobody else, so it is drift - but only once the pointer itself has shipped. A committed file pointing at an untracked target is ↩️ Orphaned. While the pointer is itself uncommitted, both halves can still be staged together, so it is ❓ at most, and a target that is merely uncommitted rather than untracked is never a finding. Without git none of this is visible, and its absence is not a clean verdict for the pointer - it is out of scope for that run.

存在差异但上下文不足以判断是否为问题。

当实现文件（模板、安装程序）与文档文件（README、注释示例）冲突时，实现文件通常为真相来源。

❓的可接受性。一个❓结果需要三个要素：指定的文件对、指定的概念、要求这些文件保持一致的声明或说明文件规则。缺少第三个要素时，它只是一个观察结果而非检查结果，不应纳入报告。以下内容永远不会成为检查结果：

换行宽度、标题样式、章节顺序
一个工件中存在而另一个工件中不存在的可选章节
未被声明覆盖的句子措辞
同级组件间的并行结构，除非声明要求一致

N个同级组件可能存在N²种结构差异，因此接受此类差异的层级永远无法生成无问题报告。仅当有明确约定时，对称性才是必须遵守的。

Git状态的可接受性。指向磁盘上存在但未被跟踪的目标的指针仅对你可见，因此属于差异——但仅当指针本身已发布时。已提交的文件指向未被跟踪的目标属于↩️孤立。当指针本身未提交时，两者仍可一起暂存，因此最多属于❓；仅未提交而非未被跟踪的目标永远不会成为检查结果。如果无Git，则无法看到这些状态，其缺失并不代表指针无问题——仅在本次运行中不在检查范围内。

Step 6 — Report findings

步骤6 — 报告检查结果

Skip findings matching a Step 2 intentional variation.

Output a numbered list ordered by severity (🔴, ⚠️, ↩️, ❓). Within a tier, wider user impact first.

Per-finding template:

#N — [icon] [TierName]
Files: <file>, <file2>, …
<file>: <line> — <paraphrase, in your own words, of the differing concept — never quoted text>
[<file2>: <line> — <paraphrase, in your own words, of the differing concept — never quoted text>]
Fix: <concrete edit — for ❓, a confirmation question instead>

Rules:

Paraphrase only - see invariant 2.
Every detail line carries a line number, one line per affected file:
```
<file>: <line> — <paraphrase>
```
. Non-contiguous lines are
```
<file>: <lineA>, <lineB> — …
```
; a contiguous run is
```
<file>: <lineA>-<lineB>
```
. Unknown line at report time: search the file and resolve it - never emit a finding for a file without one.
Nothing concrete to paraphrase (e.g. a dangling reference with no target): describe inline, pointing at the reference itself -
```
<file>:<line> — <reference> never defined
```
.

For ❓ Unverifiable,

Fix:

becomes a confirmation question (e.g.

Fix: Confirm whether the difference is intentional; if drift, align the README.

No decorative whitespace alignment - single space after every colon.

Example (⚠️ Outdated):

#1 — ⚠️ Outdated
Files: README.md, SKILL.md
README.md:12 — lists 3 sources
SKILL.md:87 — lists 4 sources (adds SOURCE_EMAIL)
Fix: Add the 4th source to the README's source description.

Summary line (always last, icon-only counts; emit both lines even when M=0):

Found N issues: X 🔴, Y ⚠️, Z ↩️, W ❓.
Skipped M intentional variations.

Skipped-files note - emit only when Step 1's content-signature filter dropped something, directly above the summary. One line per file, naming the file and nothing else (invariant 2):

<file>: skipped (credential signature detected)

Clean verdict.

No drift detected.

is a claim about what was checked, not about what happened to catch your eye, so it carries its evidence:

No drift detected.
Declared invariants: <N> verified, 0 stale.
Concept pass: <N> concepts across <N> files.
Git: <used, or "unavailable - session context only">
Files checked: <comma-separated list>
Skipped: <comma-separated list, or "none">

Emit it only when Step 3 came back empty and Step 7's convergence loop closed with no new findings. Never emit it after a run that skipped a step.

跳过与步骤2中有意差异匹配的检查结果。

按严重程度排序输出编号列表（🔴、⚠️、↩️、❓）。同一严重程度内，按用户影响范围从大到小排序。

检查结果模板：

#N — [图标] [层级名称]
Files: <file>, <file2>, …
<file>: <line> — <用自己的语言描述差异概念——绝不能引用原文>
[<file2>: <line> — <用自己的语言描述差异概念——绝不能引用原文>]
Fix: <具体编辑内容——对于❓，改为确认问题>

规则：

仅用自己的语言描述 - 符合原则2。
每个细节行必须包含行号，每个受影响文件一行：
```
<file>: <line> — <描述内容>
```
。非连续行格式为
```
<file>: <lineA>, <lineB> — …
```
；连续行格式为
```
<file>: <lineA>-<lineB>
```
。报告时未知行号：搜索文件并确认——绝不输出无行号的文件检查结果。
无具体内容可描述（例如：无目标的悬空引用）：直接描述引用本身——
```
<file>:<line> — <引用> 未定义
```
。

对于❓无法验证，

Fix:

改为确认问题（例如：

Fix: 确认该差异是否为有意；如果是差异，请对齐README内容。

）。

无需装饰性空格对齐——每个冒号后仅留一个空格。

示例（⚠️ 过时）：

#1 — ⚠️ 过时
Files: README.md, SKILL.md
README.md:12 — 列出3个来源
SKILL.md:87 — 列出4个来源（新增SOURCE_EMAIL）
Fix: 在README的来源描述中添加第4个来源。

总结行（始终放在最后，仅统计图标数量；即使M=0也需输出两行）：

Found N issues: X 🔴, Y ⚠️, Z ↩️, W ❓.
Skipped M intentional variations.

跳过文件说明 - 仅当步骤1的内容特征过滤器排除了文件时才输出，放在总结行上方。每个文件一行，仅提及文件名（符合原则2）：

<file>: skipped (credential signature detected)

无差异结论。

No drift detected.

是针对已检查内容的结论，而非主观判断，因此需附带证据：

No drift detected.
Declared invariants: <N> verified, 0 stale.
Concept pass: <N> concepts across <N> files.
Git: <used, or "unavailable - session context only">
Files checked: <逗号分隔的列表>
Skipped: <逗号分隔的列表，或"none">

仅当步骤3无结果且步骤7的收敛循环结束后无新结果时，才可输出该结论。跳过任何步骤的运行都不得输出该结论。

Step 7 — Apply fixes and manage intentional variations

步骤7 — 应用修复与管理有意差异

After reporting, ask: "Apply all fixes now, or go through them one by one?"

On "all fixes now", first list the files to be modified with their per-file change count, then wait for explicit confirmation before any Edit. Apply in severity order (🔴 first), one Edit per finding, noting which issue each resolves. Confirm the correct value with the user before editing a 🔴 conflict, and any ⚠️ Outdated finding whose source of truth is ambiguous.

For ❓ findings, ask per-item: "Real problem, or intentional? [Fix it / Mark as intentional / Skip for now]"

On Mark as intentional, append to

intentional-variations.md

markdown

- files: [file-a.md, file-b.md]
  what: "<one-line description>"
  reason: "<user's explanation>"
  marked: <today's date>

intentional-variations.md

doesn't exist, say it will be created for this entry, then create it with this header first:

markdown

undefined

报告完成后，询问："立即应用所有修复，还是逐一处理？"

如果用户选择「立即应用所有修复」，首先列出将被修改的文件及其每个文件的变更数量，然后等待用户明确确认后再执行编辑。按严重程度顺序应用修复（先处理🔴），每个检查结果对应一次编辑，并注明解决的问题。编辑🔴冲突前需与用户确认正确值，对于来源不明确的⚠️过时结果也需确认。

对于❓结果，逐个询问："是否为真实问题，还是有意差异？[修复/标记为有意差异/暂时跳过]"

如果用户选择标记为有意差异，将以下内容追加到

intentional-variations.md

：

markdown

- files: [file-a.md, file-b.md]
  what: "<一行描述>"
  reason: "<用户的解释>"
  marked: <今日日期>

如果

intentional-variations.md

不存在，告知用户将创建该文件用于记录此条目，然后先添加以下头部内容再创建文件：

markdown

undefined

Intentional Variations

Differences marked as intentional. Run

docs-consistency-check review-intentional

to revisit.

标记为有意差异的内容。运行

docs-consistency-check review-intentional

可重新查看。

undefined

undefined

Discharge each fix's own obligations

履行每个修复的关联义务

A fix that resolves drift usually adds contract surface: a heading, a declared invariant, a fixed string the tool emits, a taxonomy entry. Each addition creates obligations in files the edit never touched, and an audit that stops at the edit hands those obligations to the next run as fresh findings. No fix is complete until they are discharged in the same run.

Match every edit against this table and check what it implies:

Edit shape	Also check
Added or renamed a heading	every reference pointing at it; every declaration naming it
Added a declared invariant	whether a "how to add one of these" checklist produces it; any stated count of such invariants; whether a sibling component needs the same one
Added a string the tool emits	whether a fixed-string or vocabulary declaration names it
Added an inventory or taxonomy entry	the spec's own scope clause; every public description of scope
Changed a contract sentence	every restatement of that sentence in the set
Fixed one of several sibling components	the same concept in every sibling

The last row bites hardest: fixing one sibling and leaving the others converts one finding into as many findings as there are siblings.

解决差异的修复通常会增加约定内容：标题、已声明的不变规则、工具输出的固定字符串、分类条目等。每个新增内容会对未被编辑的文件产生义务，如果审计仅停留在编辑步骤，这些义务将成为下一次运行的新检查结果。修复完成的标准是在同一次运行中履行所有关联义务。

将每个编辑与下表匹配，检查其隐含要求：

编辑类型	需同步检查的内容
添加或重命名标题	所有指向该标题的引用；所有提及该标题的声明
添加已声明的不变规则	是否有「如何添加此类规则」的检查清单生成该规则；此类规则的声明数量；同级组件是否需要相同规则
添加工具输出的固定字符串	是否有固定字符串或词汇声明提及该字符串
添加清单或分类条目	规范自身的范围条款；所有关于范围的公开描述
修改约定语句	该语句在所有文件中的重述内容
修复多个同级组件中的一个	所有同级组件中的同一概念

最后一行最容易被忽略：修复一个同级组件而忽略其他组件，会将一个检查结果转化为与同级组件数量相同的新检查结果。

Converge before reporting done

报告完成前收敛

After the last edit, re-run Step 3 and a Step 5 pass scoped to the touched files and their contract pairs. New findings mean more fixes: apply them, discharge their obligations, scope again. Repeat until a pass comes back empty, then emit Step 6's clean verdict.

Cap the loop at three iterations. Still finding drift on the fourth pass means the fixes are generating drift faster than they clear it - stop, report what the last pass found, and say plainly that the set has not converged rather than looping on.

最后一次编辑后，重新运行步骤3和针对被修改文件及其约定配对文件的步骤5检查。新的检查结果意味着需要更多修复：应用修复、履行关联义务、再次限定范围。重复此过程直到检查无结果，然后输出步骤6的无差异结论。

循环上限为3次。如果第4次检查仍发现差异，说明修复产生差异的速度快于解决差异的速度——停止循环，报告最后一次检查的结果，并明确说明文件集尚未收敛，而非继续循环。

Review intentional mode

有意差异复查模式

When invoked as

docs-consistency-check review-intentional

Read
```
intentional-variations.md
```
. Missing or empty: report and stop.
Display each entry numbered:

#1 — Marked intentional on 2026-05-03
Files: README.md, SKILL.md
What: "README says 3 sources, SKILL.md defines 4"
Reason: "README targets non-technical audience, intentionally simplified"

Ask per entry: "Still intentional, or re-open as a finding?"
Remove re-opened entries and run a targeted check on those files immediately.
Keep confirmed entries.

当以

docs-consistency-check review-intentional

方式调用时：

读取
```
intentional-variations.md
```
文件。如果文件不存在或为空：报告并停止。
编号显示每个条目：

#1 — Marked intentional on 2026-05-03
Files: README.md, SKILL.md
What: "README says 3 sources, SKILL.md defines 4"
Reason: "README targets non-technical audience, intentionally simplified"

逐个询问条目："是否仍为有意差异，还是重新作为检查结果？"
删除重新开启的条目，并立即对这些文件进行针对性检查。
保留确认仍为有意差异的条目。

Stay armed for the rest of the session

会话全程待命

A finished audit cycle doesn't end this skill's responsibility. For the rest of the conversation, offer a focused re-audit whenever:

≥2 audit-set files are edited (by user or by Claude on the user's behalf)
A file is structurally rewritten or has a section removed
The user signals "done" / "ready to commit" / "looks good"

Scope the re-audit to the changed files and their contract pairs - full re-audits are rarely needed.

完成审计周期并不代表本Skill的责任结束。在剩余会话中，出现以下情况时应主动提议进行针对性重审：

≥2个审计范围内的文件被编辑（用户编辑或Claude代表用户编辑）
文件被结构化重写或删除了某个章节
用户发出「完成」「准备提交」「看起来没问题」等信号

重审范围限定为变更的文件及其约定配对文件——通常无需全面重审。