doc-maintenance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation Maintenance

文档维护

Systematically audit, organize, and remediate project documentation by comparing the codebase against existing docs to find staleness, gaps, and misorganization.

通过将代码库与现有文档进行对比，系统性地审核、整理和修复项目文档，找出过时、缺失和组织混乱的问题。

When to Trigger

触发时机

After merging a feature branch or completing a refactor
After dependency upgrades or API changes
When onboarding surfaces confusion about project docs
Periodic maintenance (monthly or per-release)
When
```
scripts/doc_audit.py
```
is run manually and reports findings

合并功能分支或完成代码重构后
依赖升级或API变更后
新成员入职时发现项目文档存在混淆点
定期维护（每月或每次版本发布时）
手动运行
```
scripts/doc_audit.py
```
并得到检测结果时

Workflow Overview

工作流概述

Phase 1: Audit       → Run deterministic scan + haiku search agents
Phase 2: Triage      → Classify findings by severity and action type
Phase 3: Remediate   → Dispatch specialized agents to fix/create docs
Phase 4: Quality     → docs-architect reviews all changes

Phase 1: Audit       → 运行确定性扫描 + haiku搜索代理
Phase 2: Triage      → 按严重程度和操作类型分类检测结果
Phase 3: Remediate   → 调度专业代理修复/创建文档
Phase 4: Quality     → docs-architect审核所有变更

Phase 1: Audit

第一阶段：审核

Step 1a — Run the deterministic scan

步骤1a — 运行确定性扫描

Execute the bundled audit script to get a baseline report:

bash

python3 skills/doc-maintenance/scripts/doc_audit.py

The script produces a structured report covering:

Broken internal links (markdown
```
[text](path)
```
pointing to missing files)
Orphan docs (files not linked from any other doc or README)
Missing required structure (expected folders/files absent from
```
docs/
```
or
```
manual/
```
)
Stale timestamp indicators (files unchanged for >90 days with code siblings that changed)
Empty or stub files (< 3 lines of content)

Pass

--json

for machine-readable output. Pass

--root PATH

to override project root detection.

执行内置的审核脚本以获取基准报告：

bash

python3 skills/doc-maintenance/scripts/doc_audit.py

该脚本生成的结构化报告包含以下内容：

损坏的内部链接（markdown
```
[text](path)
```
指向不存在的文件）
孤立文档（未被任何其他文档或README链接的文件）
缺失的必要结构（
```
docs/
```
或
```
manual/
```
中缺少预期的文件夹/文件）
过时时间戳标识（超过90天未修改，但对应的代码文件已变更的文档）
空文件或占位文件（内容少于3行）

传递

--json

参数可获取机器可读的输出。传递

--root PATH

可覆盖项目根目录的自动检测。

Step 1b — Dispatch haiku search agents

步骤1b — 调度haiku搜索代理

After the deterministic scan, launch parallel haiku subagents to perform deeper analysis. Use

model: "haiku"

on all Task calls in this phase to minimize cost. See

references/agent-dispatch.md

for full prompt templates.

Agent 1 — Code-to-doc coverage scan (

subagent_type: "Explore"

model: "haiku"

): Search the codebase for public APIs, CLI commands, config schemas, and exported modules. Cross-reference against existing docs. Report anything undocumented.

Agent 2 — Doc-to-code freshness scan (

subagent_type: "Explore"

model: "haiku"

): Read each doc file and verify the code constructs it references still exist and match current signatures/behavior. Report mismatches.

Agent 3 — Structure compliance scan (

subagent_type: "Explore"

model: "haiku"

): Compare current

docs/

and

manual/

layout against the prescribed folder structure in

references/folder-structure.md

. Report missing folders, misplaced files, naming violations.

Agent 4 — Diagram opportunity scan (

subagent_type: "Explore"

model: "haiku"

): Scan all markdown files for ASCII/text diagrams (box-drawing characters, arrow notation, indented tree structures beyond a few simple nodes) that should be converted to Mermaid. Also identify sections describing flows, architectures, state machines, sequences, or relationships where a diagram would add clarity but none exists. Report the file path, line range, diagram type (flowchart, sequence, state, ER, etc.), and whether it is a conversion or a net-new diagram.

Launch all four agents in parallel.

完成确定性扫描后，启动并行的haiku子代理进行深度分析。此阶段的所有Task调用均使用

model: "haiku"

以降低成本。详细的提示模板请参考

references/agent-dispatch.md

。

代理1 — 代码-文档覆盖扫描（

subagent_type: "Explore"

model: "haiku"

）：搜索代码库中的公共API、CLI命令、配置架构和导出模块。与现有文档进行交叉比对，报告所有未被文档化的内容。

代理2 — 文档-代码新鲜度扫描（

subagent_type: "Explore"

model: "haiku"

）：读取每个文档文件，验证其引用的代码结构是否仍然存在且与当前签名/行为一致。报告不匹配的内容。

代理3 — 结构合规性扫描（

subagent_type: "Explore"

model: "haiku"

）：将当前

docs/

和

manual/

的布局与

references/folder-structure.md

中规定的文件夹结构进行对比。报告缺失的文件夹、放错位置的文件和命名违规情况。

代理4 — 图表优化机会扫描（

subagent_type: "Explore"

model: "haiku"

）：扫描所有markdown文件，找出应转换为Mermaid格式的ASCII/文本图表（复杂的方框绘制字符、箭头符号、超出几个简单节点的缩进树结构）。同时识别那些描述流程、架构、状态机、序列或关系的章节——这些章节添加图表会更清晰，但目前没有图表。报告文件路径、行范围、图表类型（流程图、序列图、状态图、ER图等），以及是转换现有图表还是新增图表。

并行启动这四个代理。

Step 1c — Merge results

步骤1c — 合并结果

Combine the script output with agent findings into a single audit report. Deduplicate overlapping findings. The report becomes the input for Phase 2.

将脚本输出与代理的检测结果合并为一份统一的审核报告。去除重复的检测项。该报告将作为第二阶段的输入。

Phase 2: Triage

第二阶段：分类处理

Classify each finding into one of these action categories:

Category	Description	Example
stale	Doc exists but references outdated code/behavior	CLI flag renamed but docs show old name
missing	No doc exists for a documented-worthy item	Public API endpoint with no reference doc
orphan	Doc exists but is unreachable / unlinked	Guide file not in any index or nav
misplaced	Doc exists but is in the wrong folder	Tutorial sitting in `docs/architecture/`
irrelevant	Doc covers removed functionality	Guide for a deleted feature
structural	Folder structure deviates from prescribed layout	Missing `docs/security/` folder
diagram-convert	ASCII/text diagram should be Mermaid	Complex box-drawing flowchart in architecture doc
diagram-missing	Section would benefit from a diagram	Multi-step process described only in prose

Assign severity:

P0 — User-facing doc is factually wrong (manual/)
P1 — Developer doc references nonexistent code
P2 — Missing doc for public API or feature
P3 — Structural / organizational issues
P4 — Minor staleness, cosmetic

将每个检测项归类为以下操作类别之一：

类别	描述	示例
过时	文档存在，但引用的代码/行为已过时	CLI标志已重命名，但文档仍显示旧名称
缺失	值得文档化的内容没有对应的文档	公共API端点没有参考文档
孤立	文档存在，但无法访问/未被链接	指南文件未出现在任何索引或导航中
放错位置	文档存在，但位于错误的文件夹中	教程放在 `docs/architecture/` 目录下
无关	文档描述的功能已被移除	针对已删除功能的指南
结构问题	文件夹结构偏离规定布局	缺少 `docs/security/` 文件夹
图表转换	ASCII/文本图表应转换为Mermaid格式	架构文档中的复杂方框绘制流程图
缺失图表	章节添加图表会更清晰	仅用文字描述的多步骤流程

分配严重程度：

P0 — 面向用户的文档存在事实错误（manual/目录下）
P1 — 开发者文档引用了不存在的代码
P2 — 公共API或功能缺少文档
P3 — 结构/组织问题
P4 — 轻微过时、 cosmetic问题

Phase 3: Remediate

第三阶段：修复

Route each finding to the appropriate specialist agent. Use the Task tool with the subagent types listed below. See

references/agent-dispatch.md

for detailed prompt templates.

Doc type	Subagent type	Target location
API reference docs	`reference-builder`	`docs/reference/` or `docs/api/`
Architecture docs	`technical-writer`	`docs/architecture/`
Developer guides (style, local dev, workflows)	`technical-writer`	`docs/development/`
Testing docs	`technical-writer`	`docs/testing/`
Security docs	`technical-writer`	`docs/security/`
User-facing tutorials	`learning-guide`	`manual/tutorials/`
User-facing how-to guides	`learning-guide`	`manual/guides/`
User-facing getting started	`learning-guide`	`manual/getting-started/`
Plans and proposals	`technical-writer`	`docs/plans/`
ASCII diagram conversion	`mermaid-expert`	Inline in existing doc
New diagrams for prose sections	`mermaid-expert`	Inline in existing doc

Parallel dispatch: Group independent remediation tasks and dispatch them simultaneously. Only serialize when one doc depends on another (e.g., an API reference needed before a tutorial that links to it). Dispatch up to 4 remediation agents in parallel per batch.

For updates to existing docs: Provide the agent with the current file contents and the specific finding to fix. Instruct it to make minimal, targeted edits.

For new docs: Provide the agent with the relevant source code, the target file path, and the folder-structure spec so it follows naming conventions.

将每个检测项分配给对应的专业代理。使用Task工具并指定以下子代理类型。详细的提示模板请参考

references/agent-dispatch.md

。

文档类型	子代理类型	目标位置
API参考文档	`reference-builder`	`docs/reference/` 或 `docs/api/`
架构文档	`technical-writer`	`docs/architecture/`
开发者指南（风格、本地开发、工作流）	`technical-writer`	`docs/development/`
测试文档	`technical-writer`	`docs/testing/`
安全文档	`technical-writer`	`docs/security/`
面向用户的教程	`learning-guide`	`manual/tutorials/`
面向用户的操作指南	`learning-guide`	`manual/guides/`
面向用户的入门指南	`learning-guide`	`manual/getting-started/`
计划与提案	`technical-writer`	`docs/plans/`
ASCII图表转换	`mermaid-expert`	嵌入现有文档中
为文字章节新增图表	`mermaid-expert`	嵌入现有文档中

并行调度： 将独立的修复任务分组，同时调度。仅当一个文档依赖于另一个文档时才串行执行（例如，教程需要链接的API参考文档需先完成）。每批最多并行调度4个修复代理。

更新现有文档： 向代理提供当前文件内容和需要修复的具体检测项。指示其进行最小化、针对性的编辑。

创建新文档： 向代理提供相关的源代码、目标文件路径和文件夹结构规范，使其遵循命名约定。

Phase 4: Quality Gate

第四阶段：质量把关

After all remediation agents complete, dispatch a single

docs-architect

agent to review the full set of changes. The quality gate checks:

Accuracy — Do docs match current code?
Completeness — Are all public interfaces covered?
Organization — Does folder structure match the prescribed layout?
Cross-references — Are all internal links valid?
Consistency — Tone, formatting, heading levels
No orphans — Every new doc is linked from an index or parent doc

If the quality gate fails, loop back to Phase 3 for the specific issues flagged. Maximum 2 remediation loops before escalating to the user.

所有修复代理完成任务后，调度一个

docs-architect

代理审核所有变更。质量把关检查以下内容：

准确性 — 文档是否与当前代码一致？
完整性 — 所有公共接口是否都有文档覆盖？
组织性 — 文件夹结构是否符合规定布局？
交叉引用 — 所有内部链接是否有效？
一致性 — 语气、格式、标题层级
无孤立文档 — 每个新文档都链接到索引或父文档

如果质量把关未通过，则回到第三阶段修复指出的具体问题。最多允许2次修复循环，之后需升级给用户处理。

Folder Structure

文件夹结构

The prescribed folder layout is defined in

references/folder-structure.md

. Summary:

规定的文件夹布局定义在

references/folder-structure.md

中。摘要：

docs/

— Internal / developer documentation

docs/

— 内部/开发者文档

docs/
├── architecture/    — System design, ADRs, component diagrams
├── development/     — Developer guides: style, local setup, issue tracking
├── plans/           — Proposals, RFCs, roadmaps
├── reviews/         — Code review records, audit reports
├── testing/         — Test strategy, coverage reports, test plans
├── reports/         — Generated reports, metrics, analysis
├── security/        — Security policies, threat models, audit findings
├── api/             — Internal API docs (OpenAPI specs, gRPC protos)
├── reference/       — CLI reference, config reference, manpages
├── ideas/           — Exploratory notes, spikes, brainstorms
└── archive/         — Deprecated docs preserved for history

docs/
├── architecture/    — 系统设计、ADR、组件图
├── development/     — 开发者指南：风格、本地设置、问题跟踪
├── plans/           — 提案、RFC、路线图
├── reviews/         — 代码评审记录、审核报告
├── testing/         — 测试策略、覆盖率报告、测试计划
├── reports/         — 生成的报告、指标、分析
├── security/        — 安全策略、威胁模型、审核结果
├── api/             — 内部API文档（OpenAPI规范、gRPC原型）
├── reference/       — CLI参考、配置参考、手册页
├── ideas/           — 探索性笔记、研究、头脑风暴
└── archive/         — 为历史保留的已弃用文档

manual/

— User-facing documentation (project root)

manual/

— 面向用户的文档（项目根目录）

manual/
├── getting-started/ — Installation, quickstart, first steps
├── guides/          — How-to guides for common tasks
├── tutorials/       — Step-by-step learning paths
├── reference/       — User-facing command/config reference
└── troubleshooting/ — FAQ, common errors, known issues

manual/
├── getting-started/ — 安装、快速入门、第一步
├── guides/          — 常见任务的操作指南
├── tutorials/       — 分步学习路径
├── reference/       — 面向用户的命令/配置参考
└── troubleshooting/ — FAQ、常见错误、已知问题

README.md

— Project root

README.md

— 项目根目录

The main README is audited for accuracy but not reorganized. Findings about the README are reported as stale/missing items for manual remediation.

主README会被审核准确性，但不会被重新组织。关于README的检测项会作为过时/缺失内容报告，供手动修复。

Anti-Patterns

反模式

Do not delete docs without confirming the feature they describe is truly removed
Do not reorganize docs without updating all internal cross-references
Do not create stub files just to fill the folder structure — only create docs with real content
Do not duplicate content between
```
docs/
```
and
```
manual/
```
— link instead
Do not move user-facing docs into
```
docs/
```
or developer docs into
```
manual/
```

不要在未确认文档描述的功能确实已被移除的情况下删除文档
不要在未更新所有内部交叉引用的情况下重新组织文档
不要为了填充文件夹结构而创建占位文件——只创建有实际内容的文档
不要在
```
docs/
```
和
```
manual/
```
之间重复内容——应使用链接代替
不要将面向用户的文档移到
```
docs/
```
目录，也不要将开发者文档移到
```
manual/
```
目录