| name | hai-audit-docs |
| description | Audits documentation for internal contradictions and/or mismatches with code, config, schemas, and approved contracts. Use for 文档审计、前后冲突、术语漂移、README 是否过时、文档和代码一致吗, including check-and-fix requests. Select evidence sources from the request; return prioritized findings, source precedence, and repair ownership. Apply clear local repairs only when requested. Use hai-rewrite-doc for wholesale reconstruction, hai-prd for product shaping, and readme-beautifier for formatting only.
|
Hai Audit Docs
For Chinese readers, see SKILL.zh_CN.md. The English file is the execution source of truth.
Principle
A coherent document can be factually wrong; implementation can violate an approved requirement.
Declare which authority settles each claim before deciding which side needs repair.
Select evidence and action
- Internal: compare claims within the named document set. Respect "only docs/no code".
Internal agreement proves consistency, not runtime truth.
- Implementation/contract: compare current-behavior claims with code/config and intended
behavior with approved specs/contracts. Inspect related internal contradictions as useful.
- Combined: use both when the user asks for both or a general accuracy audit has both sources
available. State the chosen scope; if code is unavailable, mark claims unverified instead of
implying they match.
- Audit only: deliver findings without editing.
- Check and fix: when requested, apply evidence-backed repairs to the named local documents,
then recheck affected claims and links. Do not silently change implementation to make docs true.
Escalate unresolved product/authority choices; continue independent clear repairs.
These are internal modes, not questions the user must answer before work starts.
Workflow
- Identify the named document surface, audience, scenarios, and requested action. Do not expand
named targets into sibling documents without reason or authorization. With no named targets,
inspect README, setup/API docs, and examples relevant to the question.
- Build a claim map: behavior, commands, defaults, lifecycle, permissions, terminology,
assumptions, acceptance, and cross-links. Record source precedence per class of claim.
- For internal evidence, read
references/internal-audit.md; distinguish explicit supersession
from unsupported claims. Absence of support alone does not prove a claim false or obsolete.
- For implementation evidence, read
references/checklist.md. Trace documented scenarios to
implementation and inspect public/config contracts back toward documentation for important
omissions. Cite both locations and identify generated versus canonical sources.
- Classify each finding as document defect, implementation gap, internal conflict, or needs
evidence/decision. If a doc describes approved future behavior, mark the implementation gap;
do not rewrite it to bless current behavior. Consult
references/worked-examples.md when
authority is disputed.
- Recommend update, move, merge, remove, split, or resolve. Separate a suggested repair from an
applied edit. Preserve real contracts and unresolved claims explicitly.
- If repairs were requested, make the bounded authorized edits and verify them. Route a wholesale
rewrite to
hai-rewrite-doc with the established evidence; product decisions belong to
hai-prd, plan changes to hai-goal.
- Read
references/output-template.md and report scope, findings, actual edits, verification,
and unresolved decisions without repeating a full report for each evidence mode.
Impact
- P0: evidenced severe wrong decision, data/security harm, or launch failure.
- P1: core scenario, scope, or acceptance is materially wrong.
- P2: bounded drift, omission, duplication, or misleading terminology.
- P3: minor wording or link issue.
- Needs evidence/decision: unresolved; not a confirmed defect.
Rate actual impact, not the presence of a sensitive keyword. A security-related typo alone
does not become a release blocker.
Boundaries
- Formatting without factual changes →
readme-beautifier.
- Whole-document reconstruction →
hai-rewrite-doc.
- Product requirements or acceptance definition →
hai-prd.
- Entity fields and storage/migration placement →
entity-model-auditor.
- Proving a software change works →
write-technical-acceptance-report; documentation
inspection alone does not prove runtime acceptance.
