audit-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Audit Docs

文档审计

A read-first audit answering "do the docs still match reality?" Produces a findings report; it does not silently rewrite docs.

这是一项以读取为主的审计工作，旨在回答“文档是否仍与实际情况相符？”的问题。审计会生成一份发现报告，但不会静默重写文档。

Turn contract — verify before ending the turn

回合约定——结束前需验证

✓ The AUDIT DOCS fixed-format report was printed, ending in `Decision: PASS | FAIL`
✓ No doc was rewritten without explicit --fix / user go-ahead
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output

About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose).

✓ 已输出AUDIT DOCS固定格式报告，结尾为`Decision: PASS | FAIL`
✓ 未在未获得明确--fix参数或用户许可的情况下重写任何文档
✓ 结尾的`→ Next:`块作为最后输出内容打印

如果即将结束回合时仍有未勾选的项？说明回合未完成——请先完成缺失的项（弱模型可能会忽略文档末尾的任务，因此本列表放在最前面）。

When to use

使用场景

Before a release or milestone, after merging several features/fixes, or whenever the doc set might have drifted from the code and issues.

发布版本或里程碑之前、合并多个功能/修复之后，或任何文档集可能与代码和问题出现偏差的时刻。

Step 0 — Discover the project (always first)

步骤0——发现项目（始终第一步）

Per the agent guide's Workflow conventions + documentation map, then read what THIS skill needs: the roadmap, the fix index + template, and the feature folder layout — the map tells you which links and invariants to check.

遵循Agent指南中的工作流约定 + 文档地图，然后了解本skill的需求：路线图、修复索引+模板，以及功能文件夹布局——文档地图会告知需要检查哪些链接和不变量。

Checks

检查项

Run these and collect findings (cite paths/lines/issue numbers each):

Roadmap ↔ feature folders. Every
```
docs/features/<NN>-<slug>/
```
is in the roadmap, and every roadmap entry has a folder (or is explicitly "scheduled").
Feature dependencies. SPEC
```
Depends on
```
/
```
Branch
```
fields are valid; no dependency cycles; ordering is consistent with the roadmap.
Fix index hygiene. Every entry maps to an open issue and an unmerged branch; flag entries whose issue is closed or whose PR merged (should have been removed). Flag open fix branches missing from the index.
Documentation-map links resolve. Every file the map references exists; flag "scheduled, not yet authored" items so they aren't mistaken for drift.
Broken intra-doc links. Relative links/anchors point at real files/sections.
Issue references. Acceptance/known-issues lines referencing
```
#N
```
aren't pointing at long-closed issues without note.
Language & naming conventions. Artifacts in the project's docs language (this repo: English); file/dir naming matches conventions (e.g. kebab-case TS files, PascalCase components).
Invariant tags. If the project uses invariant/decision IDs (e.g. INV-/D-/KI-), spot-check that referenced IDs exist where claimed.
PR-link integrity on
done
rows. Every roadmap row (and fix-index entry) with status
```
done
```
carries a linked PR reference —
```
done · [#<pr>](<pr-url>)
```
. For each bare
```
done
```
, find its PR in the forge (
```
gh pr list --state all --head feat/<NN>-<slug>
```
or by title) and propose the row update; a
```
done
```
with no PR found at all is HIGH severity (the unit may never have been closed out).

Workflow discipline (checks 10–14) — the executor skills enforce these at write time; this audit verifies they actually held. Each check is mechanical: run the command shown, don't infer.

Phase naming.
```
grep -rnE '\bS[0-9]+\b|\bStep [0-9]' docs/features/*/{PLAN,TASKS,progress}.md
```
must return nothing — plans use
```
P1, P2, …
```
("phases") only. Any hit: LOW (rename), plus check the executor argument still resolves.
Per-phase doc discipline. For every M/L feature
```
in-progress
```
/
```
done
```
: completed phases are ticked in
```
TASKS.md
```
,
```
progress.md
```
has one entry per completed phase, and (features planned under the current template) the final phase ends with the literal close-out tasks (open PR + print URL, link roadmap row, push the link commit). A
```
done
```
feature with unticked tasks or a phase missing from
```
progress.md
```
: HIGH.
Branch & PR discipline vs the forge. For every
```
done
```
unit: its PR exists, targets the default branch, has a non-empty body, and carries
```
Closes #<n>
```
when the unit is issue-born (SPEC references an issue). Also scan recent default-branch history (
```
git log --first-parent
```
) for feature/fix-scoped changes committed directly without a PR: HIGH.
Generated-docs provenance (only when the documentation map declares a
Docs site
block; otherwise state n/a). Scan the declared content dir for pages carrying
```
generated-by: agentic-workflow/generate-docs
```
. For each: (a) its
```
source-unit
```
exists in the roadmap or fix index — no match is an orphan (MEDIUM: propose deletion or re-attribution); (b) the unit's PR merged after the page's
```
updated
```
date with commits touching the page's subject paths — that page is stale (LOW: propose
```
/generate-docs <unit>
```
to refresh). Cite page path + unit per finding.
Commit format & dependency discipline. Sample the unit branches' commits:
```
<type>(<scope>): <summary>
```
conventional format (violations: LOW). Every
```
in-progress
```
/
```
done
```
row's
```
Depends on:
```
closure was merged — a unit built on unmerged deps is HIGH unless
```
decisions.md
```
records a user-forced override (
```
--force
```
), which downgrades it to LOW (documented risk).

Adapt the list to what the project has; skip checks for absent structures and say so.

执行以下检查并收集发现结果（每项需引用路径/行号/问题编号）：

路线图 ↔ 功能文件夹：每个
```
docs/features/<NN>-<slug>/
```
都存在于路线图中，且每个路线图条目都有对应的文件夹（或明确标记为“已排期”）。
功能依赖：SPEC中的
```
Depends on
```
/
```
Branch
```
字段有效；无依赖循环；顺序与路线图一致。
修复索引卫生：每个条目都对应一个开放的问题和未合并的分支；标记问题已关闭或PR已合并的条目（应已移除）。标记修复索引中缺失的开放修复分支。
文档地图链接可解析：地图引用的每个文件都存在；标记“已排期，尚未编写”的项，避免被误认为是偏差。
文档内部链接失效：相对链接/锚点指向真实的文件/章节。
问题引用：引用
```
#N
```
的验收/已知问题行未指向长期关闭且无说明的问题。
语言与命名规范：项目文档语言的工件（本仓库为英文）；文件/目录命名符合规范（例如kebab-case格式的TS文件、PascalCase格式的组件）。
不变量标签：如果项目使用不变量/决策ID（如INV-/D-/KI-），抽查引用的ID是否存在于声明的位置。
“已完成”行的PR链接完整性：每个状态为
```
done
```
的路线图行（及修复索引条目）都带有链接的PR引用——格式为
```
done · [#<pr>](<pr-url>)
```
。对于每个仅显示
```
done
```
的行，在代码托管平台中查找其PR（使用
```
gh pr list --state all --head feat/<NN>-<slug>
```
或按标题查找）并建议更新该行；完全找不到PR的
```
done
```
项属于高严重程度（该单元可能从未完成收尾）。

工作流规范（检查项10–14）——执行类skill在写入时会强制执行这些规范；本审计会验证这些规范是否实际被遵守。每项检查都是机械性的：执行所示命令，无需推断。

阶段命名：执行
```
grep -rnE '\bS[0-9]+\b|\bStep [0-9]' docs/features/*/{PLAN,TASKS,progress}.md
```
必须无返回结果——计划仅使用
```
P1, P2, …
```
（“阶段”）格式。任何匹配项：低严重程度（需重命名），同时检查执行器参数是否仍可解析。
按阶段的文档规范：对于每个中/大型的
```
in-progress
```
/
```
done
```
功能：已完成的阶段在
```
TASKS.md
```
中已勾选，
```
progress.md
```
中每个已完成阶段对应一条记录，且（当前模板下规划的功能）最后一个阶段以字面意义上的收尾任务结束（提交PR并打印URL、链接路线图行、推送链接提交）。
```
done
```
功能存在未勾选任务或
```
progress.md
```
中缺失阶段记录：高严重程度。
分支与PR规范 vs 代码托管平台：对于每个
```
done
```
单元：其PR存在，目标为默认分支，正文非空，且当单元源于问题时（SPEC引用问题）带有
```
Closes #<n>
```
标记。同时扫描最近的默认分支历史（
```
git log --first-parent
```
），查找直接提交到默认分支的功能/修复范围变更：高严重程度。
生成文档的来源（仅当文档地图声明了
Docs site
块时执行；否则标注n/a）：扫描指定的内容目录，查找带有
```
generated-by: agentic-workflow/generate-docs
```
的页面。对于每个此类页面：(a) 其
```
source-unit
```
存在于路线图或修复索引中——无匹配项则为孤儿页面（中严重程度：建议删除或重新归属）；(b) 单元的PR在页面的
```
updated
```
日期之后合并，且提交涉及页面主题路径——该页面为过时页面（低严重程度：建议执行
```
/generate-docs <unit>
```
刷新）。每项发现需引用页面路径+单元信息。
提交格式与依赖规范：抽样检查单元分支的提交：需符合
```
<type>(<scope>): <summary>
```
的约定式格式（违规：低严重程度）。每个
```
in-progress
```
/
```
done
```
行的
```
Depends on:
```
闭包已合并——基于未合并依赖构建的单元属于高严重程度，除非
```
decisions.md
```
记录了用户强制覆盖（
```
--force
```
），此时降级为低严重程度（已记录风险）。

根据项目实际情况调整检查列表；跳过不存在的结构对应的检查项并说明原因。

Process

流程

Discover, then run the checks with
```
grep
```
, file reads, and the forge CLI (per Workflow conventions; examples use
```
gh
```
).

Produce the findings report — return exactly (fixed output contract):

AUDIT DOCS — scope: <docs tree / roadmap / fix index / issues checked>

| # | Check (1-13) | Finding | Sev | Evidence | Proposed fix |
|---|-------------|---------|-----|----------|--------------|
| 1 | <which>     | <what>  | high|low | <path:line / #issue> | <smallest action> |

Checks run: <n>/13 (skipped: <which + why — absent structures only>)
Summary: <1-2 sentences>
Decision: PASS | FAIL   (FAIL if any high-severity finding is open)

Sev: high = misleading or broken; low = cosmetic.

Fix only on request. With explicit
```
--fix
```
(or user go-ahead), apply the low-risk corrections (remove a merged fix-index row, fix a dead link, register a missing roadmap entry, add a verified PR link to a bare
```
done
```
row). Leave judgment calls to the user.

先发现项目信息，然后使用
```
grep
```
、文件读取和代码托管平台CLI（遵循工作流约定；示例使用
```
gh
```
）执行检查。

生成发现报告——严格返回（固定输出约定）：

AUDIT DOCS — scope: <检查的文档树 / 路线图 / 修复索引 / 问题>

| # | Check (1-13) | Finding | Sev | Evidence | Proposed fix |
|---|-------------|---------|-----|----------|--------------|
| 1 | <具体检查项> | <发现内容> | high|low | <路径:行号 / #问题编号> | <最小操作> |

Checks run: <已执行数量>/13 (skipped: <跳过的检查项及原因——仅因结构不存在>)
Summary: <1-2句话总结>
Decision: PASS | FAIL   (存在未解决的高严重程度发现则为FAIL)

Sev：high = 具有误导性或已失效；low = 仅影响美观。

仅在请求时修复：在获得明确的
```
--fix
```
参数（或用户许可）后，应用低风险修正（移除已合并的修复索引条目、修复失效链接、注册缺失的路线图条目、为仅显示
```
done
```
的行添加已验证的PR链接）。将判断类决策留给用户。

Guardrails

防护规则

Read-first; never bulk-rewrite docs unprompted.
Distinguish genuine drift from intentionally "scheduled/deferred" items — don't report deliberate tradeoffs as errors.
Keep changes surgical and within docs; no code or behavior changes.

以读取为主；未经提示绝不批量重写文档。
区分真实偏差与故意“排期/延迟”的项——不要将有意权衡的情况报告为错误。
保持修改精准且仅针对文档；不修改代码或行为。

Portability (agents other than Claude Code)

可移植性（Claude Code之外的Agent）

The workflow is the contract; Claude Code features are conveniences. On an agent that lacks one, apply the fallback — never skip the step the feature enables:

No slash-command menu — where this skill says
```
/<skill>
```
, open that skill's
```
SKILL.md
```
(wherever your agent installed the skills) and follow it literally, in a fresh conversation: hand-offs assume a clean context.
No per-skill
model:
/
effort:
— on the
```
#claude
```
branch the frontmatter pins these tiers; here, pick tiers yourself: these are mostly mechanical cross-document checks — a mid-tier model is enough; escalate to your strongest only for a deep audit.

工作流是核心约定；Claude Code的功能是便利特性。如果使用的Agent缺少某项特性，应用替代方案——绝不要跳过该特性支持的步骤：

无斜杠命令菜单——当本skill提到
```
/<skill>
```
时，打开该skill的
```
SKILL.md
```
（无论你的Agent将skills安装在何处）并严格遵循其中的步骤，在新对话中执行：交接需假设上下文干净。
无按skill划分的
model:
/
effort:
设置——在
```
#claude
```
分支中，前置元数据固定了这些层级；在本分支中，请自行选择层级：这些大多是机械性的跨文档检查——中端模型足够；仅在深度审计时升级到最强模型。

Relationship to other skills

与其他skill的关系

Complements
```
plan-feature
```
(which creates the docs this audits) and
```
triage-issue
```
(which keeps the fix index honest).
Run standalone anytime; no required predecessor.

补充
```
plan-feature
```
（创建本审计所检查的文档）和
```
triage-issue
```
（维护修复索引的准确性）。
可随时独立运行；无需前置skill。

Done when

完成标志

A severity-ranked findings report exists, and any approved low-risk fixes are applied — with genuine deferrals left untouched and labeled as such.

The closing
→ Next:
block is printed:

→ Next: apply the approved low-risk fixes, then re-run /audit-docs to confirm clean
  · real drift (not cosmetic) → /triage-issue   · a concrete defect → /plan-fix
  · already clean → nothing to do

已生成按严重程度排序的发现报告，且已应用所有获批的低风险修复——真实的延迟项保持不变并标记。

已打印结尾的
→ Next:
块：

→ Next: apply the approved low-risk fixes, then re-run /audit-docs to confirm clean
  · real drift (not cosmetic) → /triage-issue   · a concrete defect → /plan-fix
  · already clean → nothing to do