docs-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

docs-review

A generic docs auditor: reads each markdown file in

docs/

, identifies what source code it documents (by scanning file paths, flag names, command syntax, state names, config examples), then cross-references those claims against actual source files. Reports drift (doc says X, code does Y) with file:line evidence.

一款通用文档审计工具：读取

docs/

目录下的每个markdown文件，识别其记录的源代码内容（通过扫描文件路径、标志名、命令语法、状态名、配置示例），随后将这些记录与实际源文件进行交叉比对。报告内容偏差（文档说明为X，代码实际为Y）并附带文件:行号证据。

When to Use

使用场景

Periodically (weekly cron) to catch docs that fall behind code changes
Before a release to ensure docs are accurate against the current codebase
After refactoring commands, config schemas, or state machines
Skip if
```
docs/
```
does not exist — exit cleanly with a note

定期执行（每周定时任务），捕捉因代码变更而滞后的文档
发布前，确保文档与当前代码库内容一致
重构命令、配置 schema 或状态机之后
若
```
docs/
```
目录不存在则跳过——输出提示后正常退出

When NOT to Use

不适用场景

Pure narrative sections with no verifiable source claims (history, philosophy, rationale)
Docs for external APIs you don't own — you can't grep their source
Formatting or style reviews — only semantic drift matters

纯叙述性章节，无可验证的源代码相关内容（历史、理念、原理）
第三方API文档——无法搜索其源代码
格式或风格审查——仅关注语义偏差

Invocation

调用方式

bash

/docs-review
/docs-review --since 2026-04-01
/docs-review --output reports/docs-drift.md

Flag	Effect
(none)	Review all `docs/*.md` files
`--since <date>`	Narrow to docs files modified since `<date>` ( `git log --since` )
`--output <path>`	Write findings to file in addition to stdout

bash

/docs-review
/docs-review --since 2026-04-01
/docs-review --output reports/docs-drift.md

参数	作用
(无)	检查所有 `docs/*.md` 文件
`--since <date>`	仅检查自 `<date>` 起修改过的文档文件（基于 `git log --since` ）
`--output <path>`	将检查结果写入指定文件，同时输出到标准输出

Workflow

工作流程

Step 1: Discover docs

步骤1：发现文档

bash

ls docs/*.md 2>/dev/null || echo "No docs/ directory found"

If no

docs/

directory exists, exit cleanly:

No docs/ directory found — nothing to review.
Exit 0.

--since <date>

was provided, narrow the file list:

bash

git log --since="<date>" --name-only --pretty=format: -- docs/*.md | sort -u | grep '\.md$'

If this returns nothing, exit cleanly:

No docs files modified since <date> — nothing to review.
Exit 0.

bash

ls docs/*.md 2>/dev/null || echo "No docs/ directory found"

若

docs/

目录不存在，则正常退出：

No docs/ directory found — nothing to review.
Exit 0.

若指定了

--since <date>

，则缩小文件范围：

bash

git log --since="<date>" --name-only --pretty=format: -- docs/*.md | sort -u | grep '\.md$'

若未返回任何结果，则正常退出：

No docs files modified since <date> — nothing to review.
Exit 0.

Step 2: For each doc file, extract verifiable claims

步骤2：为每个文档提取可验证的记录

Read each doc and extract claims that can be cross-referenced against source code:

Claim type	What to look for	Example
Command flags	`--flag-name` patterns	`--group-id` , `--not-before`
State names/transitions	`state/ → state/` or quoted state strings	`pending/ → running/ → done/`
Config keys	backtick-quoted key names in config context	`max_concurrent` , `not_before`
File paths	paths mentioned as "located at X" or "see X"	`dispatch.sh` , `executor.sh`
Exit codes	"exits with N" or "returns N"	`exit 0` , `exit 1`
Example invocations	command examples in code blocks	`./dispatch.sh --agent lexgo`

Skip sections that are clearly non-verifiable: intro prose, motivation, design rationale, future plans.

读取每个文档，提取可与源代码交叉比对的记录：

记录类型	识别规则	示例
命令标志	`--flag-name` 格式的内容	`--group-id` , `--not-before`
状态名/状态转换	`state/ → state/` 格式或带引号的状态字符串	`pending/ → running/ → done/`
配置键	配置场景中用反引号包裹的键名	`max_concurrent` , `not_before`
文件路径	被提及为“位于X”或“详见X”的路径	`dispatch.sh` , `executor.sh`
退出码	包含“exits with N”或“returns N”的内容	`exit 0` , `exit 1`
示例调用	代码块中的命令示例	`./dispatch.sh --agent lexgo`

跳过明显不可验证的章节：介绍性文字、动机、设计原理、未来规划。

Step 3: Cross-reference each claim against source

步骤3：将每条记录与源代码交叉比对

Command flags — search shell scripts and code files:

bash

grep -rn "\-\-flag-name" --include="*.sh" --include="*.mjs" --include="*.js" --include="*.py" --include="*.ts" .

If no match: DRIFT candidate. Confirm the flag truly doesn't exist before reporting.

State names — search executor/dispatcher scripts for the state strings:

bash

grep -rn "pending\|running\|done\|failed" --include="*.sh" --include="*.js" --include="*.py" .

Cross-check the exact transition order documented against what the code enforces.

Config keys — grep the relevant config files and any code that reads them:

bash

grep -rn "max_concurrent\|not_before" --include="*.sh" --include="*.yml" --include="*.json" --include="*.js" .

File paths — check they exist:

bash

[ -f "path/to/file" ] && echo "EXISTS" || echo "MISSING"

Or for directories:

bash

[ -d "path/to/dir" ] && echo "EXISTS" || echo "MISSING"

Exit codes — grep the relevant scripts for the actual exit calls:

bash

grep -n "exit [0-9]" script.sh

Example invocations — verify the binary/script exists and the flags used in the example are real:

bash

[ -x "./dispatch.sh" ] && echo "executable exists" || echo "MISSING"
grep -n "\-\-agent" dispatch.sh

命令标志——搜索shell脚本和代码文件：

bash

grep -rn "\-\-flag-name" --include="*.sh" --include="*.mjs" --include="*.js" --include="*.py" --include="*.ts" .

若无匹配结果：标记为偏差候选。报告前需确认该标志确实不存在。

状态名——搜索执行器/调度器脚本中的状态字符串：

bash

grep -rn "pending\|running\|done\|failed" --include="*.sh" --include="*.js" --include="*.py" .

交叉比对文档记录的状态转换顺序与代码实际执行的顺序是否一致。

配置键——搜索相关配置文件及读取配置的代码：

bash

grep -rn "max_concurrent\|not_before" --include="*.sh" --include="*.yml" --include="*.json" --include="*.js" .

文件路径——检查路径是否存在：

bash

[ -f "path/to/file" ] && echo "EXISTS" || echo "MISSING"

针对目录的检查：

bash

[ -d "path/to/dir" ] && echo "EXISTS" || echo "MISSING"

退出码——搜索相关脚本中的实际退出调用：

bash

grep -n "exit [0-9]" script.sh

示例调用——验证二进制文件/脚本是否存在，且示例中使用的标志真实有效：

bash

[ -x "./dispatch.sh" ] && echo "executable exists" || echo "MISSING"
grep -n "\-\-agent" dispatch.sh

Step 4: Format findings

步骤4：格式化检查结果

For each drift item found:

DRIFT: docs/dispatch.md:42 claims "--context" flag exists
  Source check: grep "--context" *.sh → not found
  Evidence: no match in dispatch.sh, executor.sh, or any .sh file

For each verified claim:

OK: docs/dispatch.md:15 "--group-id" → dispatch.sh:47 (confirmed)

For each skipped claim (non-verifiable):

SKIP: docs/overview.md:1-10 — intro prose, no verifiable source claims

针对每个发现的偏差项：

DRIFT: docs/dispatch.md:42 claims "--context" flag exists
  Source check: grep "--context" *.sh → not found
  Evidence: no match in dispatch.sh, executor.sh, or any .sh file

针对每个已验证记录：

OK: docs/dispatch.md:15 "--group-id" → dispatch.sh:47 (confirmed)

针对每个跳过的记录（不可验证）：

SKIP: docs/overview.md:1-10 — intro prose, no verifiable source claims

Step 5: Summary

步骤5：总结

After processing all files, emit:

=== docs-review summary ===
Docs reviewed: N files
Claims checked: M
  OK:    X verified
  DRIFT: Y items
  SKIP:  Z non-verifiable

Drift items:
  - docs/dispatch.md:42 — "--context" flag not found in source
  - docs/executor.md:18 — state "queued" not found; code uses "pending"

Exit 0 if no drift found, exit 1 if any drift items exist.

--output <path>

was provided, write the full findings (all OK/DRIFT/SKIP lines + summary) to that file.

处理完所有文件后，输出：

=== docs-review summary ===
Docs reviewed: N files
Claims checked: M
  OK:    X verified
  DRIFT: Y items
  SKIP:  Z non-verifiable

Drift items:
  - docs/dispatch.md:42 — "--context" flag not found in source
  - docs/executor.md:18 — state "queued" not found; code uses "pending"

Exit 0 if no drift found, exit 1 if any drift items exist.

若指定了

--output <path>

，则将完整检查结果（所有OK/DRIFT/SKIP记录 + 总结）写入该文件。

Checks to Perform

执行的检查项

The six canonical checks — apply all of them:

Check	What to grep	Where to look
Flag parity	`--flag-name` patterns from docs	`.sh` , `.js` , `.py` , `.ts`
State parity	state strings and transition order	executor, dispatcher scripts
Config key parity	config key names	config files, scripts that read them
Link validity	`[text](./path)` or `[text](path.md)` internal links	resolve against filesystem
Path existence	paths mentioned as real locations	`[ -f path ]` or `[ -d path ]`
Exit code accuracy	"exits N" or "returns N"	`grep -n "exit [0-9]" script`

Link validity check — extract and verify all internal markdown links:

bash

undefined

六大标准检查项——全部执行：

检查项	搜索内容	检查范围
标志一致性	文档中的 `--flag-name` 格式内容	`.sh` , `.js` , `.py` , `.ts`
状态一致性	状态字符串及转换顺序	执行器、调度器脚本
配置键一致性	配置键名	配置文件、读取配置的脚本
链接有效性	`[text](./path)` 或 `[text](path.md)` 格式的内部链接	基于文件系统验证链接有效性
路径存在性	被提及为实际位置的路径	通过 `[ -f path ]` 或 `[ -d path ]` 检查
退出码准确性	包含“exits N”或“returns N”的内容	通过 `grep -n "exit [0-9]" script` 检查

链接有效性检查——提取并验证所有markdown内部链接：

bash

undefined

Extract internal links (not http/https)

grep -oP '[.*?](\K[^)]+(?=))' docs/file.md | grep -v '^https?://' | while read link; do [ -f "$link" ] || [ -d "$link" ] && echo "OK: $link" || echo "DRIFT: broken link → $link" done

---

grep -oP '[.*?](\K[^)]+(?=))' docs/file.md | grep -v '^https?://' | while read link; do [ -f "$link" ] || [ -d "$link" ] && echo "OK: $link" || echo "DRIFT: broken link → $link" done

---

Anti-Patterns

反模式

Do NOT do these:

Fabricate drift — only report what you actually verified with grep/read. If grep returns results but you can't find the exact claim, mark SKIP not DRIFT.
Skip docs that look correct — every doc gets checked; intuition is not evidence.
Fail on formatting — wrong indentation, different phrasing of correct content: not drift.
Report style issues — "this example could be clearer" is not drift.
Check external API docs — if the doc describes a third-party API, skip it.
Over-grep — match the exact flag name, not a substring.
```
--group
```
should not match
```
--group-id
```
.

请勿执行以下操作：

编造偏差——仅报告经grep/读取验证的内容。若grep返回结果但无法找到对应记录，标记为SKIP而非DRIFT。
跳过看似正确的文档——所有文档均需检查；直觉不能作为证据。
因格式问题报错——缩进错误、内容表述不同但信息正确：不属于偏差。
报告风格问题——“此示例可更清晰”不属于偏差。
检查第三方API文档——若文档描述的是第三方API，跳过检查。
过度搜索——匹配确切的标志名，而非子字符串。
```
--group
```
不应匹配
```
--group-id
```
。

Adding to a Team Cron

添加到团队定时任务

To run docs-review automatically on a schedule:

yaml

undefined

如需定期自动执行docs-review：

yaml

undefined

In crew.yml, under the team's cron section:

cron:

schedule: "0 6 * * 1" # Weekly Monday 6am UTC task: "Run docs-review: check docs/ for drift against code"


For repos with active doc changes, use a daily schedule:

```yaml
cron:
  - schedule: "0 7 * * *"  # Daily 7am UTC
    task: "Run docs-review --since yesterday: check docs/ for overnight drift"

cron:

schedule: "0 6 * * 1" # Weekly Monday 6am UTC task: "Run docs-review: check docs/ for drift against code"


对于文档变更频繁的仓库，可使用每日定时任务：

```yaml
cron:
  - schedule: "0 7 * * *"  # Daily 7am UTC
    task: "Run docs-review --since yesterday: check docs/ for overnight drift"

Exit Codes

退出码

Exit code	Meaning
`0`	No drift found (or no docs to review)
`1`	One or more drift items found

退出码	含义
`0`	未发现偏差（或无文档可检查）
`1`	发现一个或多个偏差项