Hai Audit Docs Internally

Hai Audit Docs Internally

For Chinese readers, see SKILL.zh_CN.md. The English SKILL.md is the execution source of truth.

Overview

The source of truth is the document's own goal, structure, terminology, claims, and cross-references — not the codebase.

Core Principle

A document is a coherent argument, and the audit reads it as one. Judge it for consistency of purpose, terms, and claims: every section should serve the same target, the same concept should carry the same name, and nothing should assert what another section denies or what no evidence supports. The enumerated consistency checks live in Workflow step 3.

Workflow

1. Identify the document scope.

• The scope is exactly what the user points at: a single file, an arbitrary batch of files, a

PRD pack, README plus docs, or a generated spec set. Do not widen it to a directory uninvited.

• Note the document's apparent audience, purpose, and expected decision/use.

2. Build a document map.

• List the main sections and what each section is trying to do.
• Extract key claims, definitions, terminology, assumptions, scope boundaries, examples, dates, owners, statuses, and cross-links.
• Identify repeated claims and places where the same concept appears under different names.

3. Find internal issues.

• Direct conflict: two sections make incompatible claims.
• Scope conflict: in-scope and out-of-scope sections disagree.
• Terminology drift: the same concept uses different names, or one name means different things.
• Lifecycle conflict: statuses, phases, dates, or dependencies do not line up.
• Acceptance conflict: success criteria do not prove the stated goal.
• Stale signal: text references old decisions, old names, old dates, deprecated sections, or superseded assumptions.
• Redundant content: repeated paragraphs, examples, or checklists should be merged or removed.
• Misplaced content: implementation detail, policy, background, or task planning lives in the wrong document section.
• Unsupported claim: a strong claim lacks evidence, owner, source, or decision record.

4. Decide the repair type.

• Update when the content is useful but stale or imprecise.
• Move when the content belongs elsewhere in the same document.
• Merge when repeated content fragments one idea.
• Remove when content is out of scope, obsolete, unsupported, or harmful.
• Split when one document contains multiple independent goals or audiences.
• Ask when a conflict cannot be resolved from the document itself.

5. Produce the audit.

• Deliver: Verdict, Document Map, prioritized Findings (each with type, location, evidence, impact, repair), a Remove/Update/Move decision table, Open Decisions, and a Suggested Repair Order.
• Read references/output-template.md before finalizing.
• Prioritize issues that change understanding, decisions, scope, or execution.
• Keep wording fixes secondary unless wording causes ambiguity or conflict.

Severity

Use a different skill when

• The truth source is the code: use hai-audit-docs-against-code to check docs against implementation, config, and API contracts. This skill never compares against code.
• The document is a PRD that needs product-requirement crafting or repair (scope, acceptance, structure as a spec): use hai-prd.
• The docs just need formatting and presentation cleanup, not consistency judgment: use readme-beautifier.
• The user wants the document rewritten around the current conclusions, not a findings report: use hai-rewrite-doc. This skill diagnoses; it does not rewrite.

Internal Documentation Audit Output Template

Use this template when reporting conflicts, stale content, and update/remove decisions inside one document or a documentation set.

# Internal Documentation Audit: <document or doc set>

## Verdict
- **Status**: healthy (no P0/P1) / needs cleanup (P2-P3 only) / inconsistent (has P0/P1) / blocked by decisions (has Needs-decision forks)
- **Main issue**: <one sentence>
- **Scope reviewed**: <files or sections>

## Document Map
| Section / Doc | Apparent purpose | Notes |
|---------------|------------------|-------|
| <section> | <purpose> | <key observation> |

## Findings

Order by severity (P0 first). Severity levels are defined in SKILL.md; types and repairs are defined in Workflow steps 3-4.

### P0: <conflict that could cause a wrong decision, unsafe action, or failed launch>
- **Type**: direct conflict / scope conflict / terminology drift / lifecycle conflict / acceptance conflict / stale signal / redundant content / misplaced content / unsupported claim
- **Location**: `<doc>:<section or line>`
- **Evidence**:
  - <claim A>
  - <claim B or stale signal>
- **Impact**: <the wrong decision, unsafe action, or failed launch this could cause>
- **Repair**: update / move / merge / remove / split / ask
- **Recommendation**: <specific edit direction>

### P1: <conflict or stale-content title>
- **Type**: <one of the types above>
- **Location**: `<doc>:<section or line>`
- **Evidence**:
  - <claim A>
  - <claim B or stale signal>
- **Impact**: <why this changes understanding, decisions, or execution>
- **Repair**: update / move / merge / remove / split / ask
- **Recommendation**: <specific edit direction>

### Needs decision: <real fork the document cannot resolve on its own>
- **Type**: <one of the types above>
- **Location**: `<doc>:<section or line>`
- **Evidence**:
  - <option A and what assumes it>
  - <option B and what assumes it>
- **Impact**: <what stays inconsistent until the owner picks>
- **Repair**: ask
- **Recommendation**: <the question to put to the owner; mirror it in Open Decisions below>

## Remove / Update / Move Decisions
| Content | Decision | Reason | Suggested destination or replacement |
|---------|----------|--------|--------------------------------------|
| <claim/section> | remove / update / move / merge | <why> | <target or replacement> |

## Open Decisions
- <question that must be answered by the document owner>

## Suggested Repair Order
1. <highest leverage repair>
2. <next repair>

Hai Audit Docs Internally 中文版

本文件是中文阅读版；执行规则以 SKILL.md 为准。

概览

真相来源不是代码，而是文档自己的目标、结构、术语、声明和交叉引用。

核心原则

把文档当成一篇连贯论证，审计就按这一篇来读。从目的、术语、声明三个维度判断一致性：每个 section 都应服务同一个目标，同一个概念应使用同一个名字，任何声明都不应与别处矛盾或缺乏依据。具体的一致性检查项列在工作流第 3 步。

工作流

1. 明确文档范围。

• 范围就是用户点名的那些：单个文件、任意一批文件、PRD 包、README + docs 或生成的规格集。不要擅自扩大到整个目录。
• 记录文档的受众、目的，以及它期望支撑的决策或用途。

2. 建立文档地图。

• 列出主要 section 以及每个 section 想做什么。
• 提取关键声明、定义、术语、假设、范围边界、示例、日期、负责人、状态和交叉链接。
• 找出重复声明，以及同一概念以不同名字出现的地方。

3. 找内部问题。

• 直接冲突：两个 section 给出互相矛盾的声明。
• 范围冲突：in-scope 和 out-of-scope 的 section 互相打架。
• 术语漂移：同一概念用了不同名字，或同一个名字指代不同含义。
• 生命周期冲突：状态、阶段、日期或依赖对不上。
• 验收冲突：成功标准无法证明所声明的目标。
• 过期信号：文本引用旧决策、旧名称、旧日期、废弃 section 或被取代的假设。
• 重复内容：重复的段落、示例或清单，应该合并或删除。
• 错位内容：实现细节、策略、背景或任务规划放错了文档/section。
• 无依据声明：强声明缺少证据、负责人、来源或决策记录。

4. 决定修复类型。

• 更新（update）：内容有用但过期或不精确。
• 移动（move）：内容应放到同一文档的别处。
• 合并（merge）：重复内容把一个想法拆碎了。
• 删除（remove）：内容越界、过时、无依据或有害。
• 拆分（split）：一篇文档装了多个独立目标或受众。
• 提问（ask）：冲突无法仅凭文档自身解决。

5. 输出审计。

• 交付物：结论（Verdict）、文档地图（Document Map）、按优先级排序的问题（每条含类型、位置、证据、影响、修复方式）、删除/更新/移动决策表、开放问题（Open Decisions）和建议修复顺序（Suggested Repair Order）。
• 定稿前先读 references/output-template.md。
• 优先处理会改变理解、决策、范围或执行的问题。
• 措辞类修复放次要位置，除非措辞本身造成歧义或冲突。

严重级别

什么时候改用别的 skill

• 真相来源是代码：用 hai-audit-docs-against-code 检查文档是否符合实现、配置和 API 契约。本 skill 从不对照代码。
• 文档是 PRD，需要按产品规格打磨或修复（范围、验收、作为 spec 的结构）：用 hai-prd。
• 文档只需要排版和呈现美化，而非一致性判断：用 readme-beautifier。
• 用户要的是按当前结论把文档重写出来，而不是一份问题报告：用 hai-rewrite-doc。本 skill 只诊断，不重写。