Hai Rewrite Doc

Hai Rewrite Doc

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

Overview

Take one document that has rotted through rounds of discussion and patching, verify it block by block, and rewrite it around what survives. The old document is raw material and evidence — never the base to patch.

The default stance toward old content is preservation: every block gets verified, what passes keeps its original wording, and only what fails verification is removed. The skill's value is catching the many small wrong claims a messy document hides — one by one, with the check on record — not composing a prettier document.

Verification runs at two levels: macro (the document's frame — frontmatter/YAML metadata, title, stated purpose) and micro (every individual point). Both levels carry the same rule: fail means removal.

Deliver three things: the rewritten document, a disposition verdict for every block of the old one, and the open questions that cannot be verified without the user.

Core Principle

A document rots because the real consensus lives in the conversation while the document only receives patches — and each patch was written against a different snapshot of that consensus. More patching cannot fix this. The fix is to make the consensus explicit first, then re-derive the document from it.

So the order is fixed: anchor first, then rewrite. Never start writing before the anchor is written down, and never merge old text into the new document without a verdict.

And verdicts are earned by verification, not by smell. A claim that can be checked — against the anchor, the codebase, a config file, a schema, a runnable command — must actually be checked before it is kept or deleted. A claim that cannot be checked is never silently kept or dropped; it goes to Open Questions.

Verification failure means removal, not repair. The instinct to fix a failing block — to explain why it failed and write a corrected version — is exactly how rot enters: the "fix" is a guess wearing a fix's clothes, and it reads as authoritative. Remove the block. If its topic still needs covering, that coverage comes from the anchor; if the anchor has nothing to say, the gap goes to Open Questions for the user to fill deliberately.

Workflow

1. Build the anchor. Collect the conclusions that are true now: decisions made, decisions later reversed (the reversal wins), constraints still standing, and the document's target reader and job. Sources: the user's message, the discussion history, linked docs. Write the anchor as a numbered list of conclusions — it ships in the output so the reader can check the rewrite against it.

2. Interrogate the holes. If the anchor cannot answer "who is this document for" or "what did we finally decide about X", ask the user pointed questions before writing anything. A rewrite from a guessed anchor just produces the next rotten version.

3. Inventory the old document. Split it into blocks (sections, claims, tables, examples, commands, numbers). The inventory exists so that every block gets verified — none skipped.

4. Verify at two levels: macro first, then micro.

• Macro — the document's frame. Verify the frontmatter/YAML metadata, title, stated

purpose, and top-level framing before anything else. A frame that no longer fits the current scenario, or has simply fallen behind it, fails like any other block: remove it (replacement framing comes from the anchor). And a failed frame casts suspicion downward — content that existed only to serve the dead frame must be re-verified against the anchor, not against the frame.

• Micro — every point, one by one. Check each block against the anchor, then against

anything else checkable: the code, config, schema, the commands and paths it cites, linked documents. List-heavy documents are where rot hides: a list is never verified wholesale — it passes only when every item in it has passed individually, and failed items are removed individually.

Record what was checked at both levels — the disposition table cites it.

5. Give every block exactly one verdict:

• Keep — verified still true; reuse it with the original wording and voice.
• Delete — failed verification: verified wrong, contradicts the anchor, or is patch

residue nobody can explain. Cite the check that failed. Do not rewrite it into a version that would pass — remove it; any replacement coverage comes from the anchor, not from the failed block.

• Undecided — unverifiable without the user; park it in Open Questions. Never silently

keep or drop it.

6. Decide the structure deliberately. Keep the old structure when it still serves the anchor — preservation extends to structure, not only wording. Re-derive it from the anchor only when the structure itself is patch residue.

7. Write the new document in full. It must stand alone — a reader with no access to the discussion history should understand it. Match the original language and register unless the anchor changes the audience.

8. Check the rewrite against the anchor, item by item. Every anchor conclusion is represented; everything in the new document traces to the anchor or to a Keep verdict. Anything that fails this check gets fixed or moved to Open Questions.

Output

Replace the original file in place — version control and the disposition table carry the history; a sibling copy just becomes the next piece of patch residue. Write to a separate file only when the user explicitly asks to keep the original untouched. The reply carries the rest:

# Hai Rewrite Doc: <document>
## Anchor               — numbered current conclusions the rewrite derives from
## Rewritten Document   — path to the rewritten file (inline only when the document is short)
## Disposition Table    — old block → Keep / Delete / Undecided, each citing the check it passed or failed
## Open Questions       — what the anchor cannot settle, and which section each one blocks

Read references/output-template.md before finalizing.

Use a different skill when

• The user wants a findings report, not a rewritten document — use hai-audit-docs-internally.
• The truth source is the code, not the discussion — use hai-audit-docs-against-code.
• The document is a PRD — use hai-prd; its Craft mode owns PRD repair and rewrite.
• The document is a plan or goal document — use hai-goal; its rewrite mode re-anchors plans

around a target.

• Only structure and formatting are wrong and the content is fine — use readme-beautifier.
• The real question is which concepts deserve to exist at all — run hai-razor first, then

rewrite.

What this skill is NOT

• Not a beautifier — it changes content and judgment, not just formatting.
• Not a patch merger — it never produces "the old doc plus the latest edits".
• Not a summarizer — the output is a full working document, not a digest.
• Not a fresh composition — verified-true content is preserved, not paraphrased.
• Not a repair shop — a failing block is removed, never patched into a passing one.
• Not silent — nothing from the old document disappears without a line in the disposition table.

Common Mistakes

• Writing before the anchor is explicit — the rewrite inherits guesses instead of conclusions.
• Judging blocks by smell instead of checking them — checkable claims get checked.
• Passing a list wholesale — a list passes only when every item in it passed individually.
• Skipping the frame because it "looks structural" — stale frontmatter/YAML metadata fails and

gets removed like any other block.

• Repairing a failing block instead of removing it — explaining why it failed and writing a

"corrected" version reintroduces guesses; failure means removal.

• Deleting without citing the check that failed; a Delete verdict is earned, not asserted.
• Treating "it was discussed once" as consensus; only the latest standing decision counts.
• Silently dropping blocks instead of recording a Delete verdict.
• Rewriting Keep blocks anyway and destroying the author's voice.

Hai Rewrite Doc Output Template

The canonical report shape. The rewritten document replaces the original file in place (version control and the Disposition Table carry the history); write a separate file only when the user explicitly asked to keep the original. This report is the reply. Every block of the old document must appear in the Disposition Table — nothing disappears silently. User-visible text may be written in Chinese when the audience is Chinese.

# Hai Rewrite Doc: <document name>

## Anchor

The current conclusions this rewrite derives from. Numbered, so dispositions and the final check
can cite them.

1. <conclusion — e.g. "the doc targets new contributors, not maintainers">
2. <conclusion — e.g. "the X mechanism was replaced by Y in the 6/08 discussion">
3. <reversed decision — state the reversal explicitly: "A was decided on 6/01, overturned 6/09">
...

## Rewritten Document

Path: `<absolute path to the rewritten file>`

<inline the full document only when it is short enough to read in the reply>

## Disposition Table

Every verdict cites the check it passed or failed — an anchor item, a code/config/schema
reference, a command that was run, or a linked document. "Looked wrong" is not a check.

A failed check means the block is removed, never repaired into a passing version — replacement
coverage, when needed, comes from the anchor. Cover both levels: macro rows (frontmatter/YAML
metadata, title, stated purpose) and micro rows (individual points — list items are dispositioned
one by one, never as a whole list).

| # | Old block | Verdict | Check (passed / failed) |
| --- | --- | --- | --- |
| 1 | frontmatter / YAML metadata | Delete | macro: frame no longer fits the current scenario (anchor 1) |
| 2 | <section / claim / table> | Keep | verified against anchor 2 + `src/config.ts:14`; wording preserved |
| 3 | <list item 3 of section X> | Delete | verified wrong: default value contradicts `settings.py:88` |
| 4 | <section / claim> | Delete | verified wrong: command no longer exists (`make build` removed in a1b2c3) |
| 5 | <section / claim> | Undecided | unverifiable without user — see Open Question 1 |

## Open Questions

Each question names what it blocks. The rewrite ships without these sections resolved; do not
guess answers into the document.

1. <question> — blocks <section> (old block #4)
2. <question> — blocks <section>

## Next Step

<one line: what the user should confirm or decide for the rewrite to be final>

Hai Rewrite Doc 中文版

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

触发：文档在多轮讨论中积累了一堆乱七八糟、真假难辨的内容，用户要的是逐块核实并清理，而不是再打一轮补丁。逐块对照当前结论、代码库和一切可查证的东西核实：核实通过的保留原文，核实不过的直接移除——绝不修补成一个"看起来能通过"的版本。触发语包括：重写这份文档、这文档已经烂了、文档已经不对了、逐条核实这份文档、把不对的内容删掉、按最新结论重写、文档跟讨论结论对不上、别再缝缝补补了、推倒重写。只要问题报告不要重写时用 hai-audit-docs-internally；文档是 PRD 用 hai-prd；是计划/目标文档用 hai-goal。

概览

接手一份在多轮讨论和补丁中烂掉的文档，逐块核实，再围绕核实结果重写。旧文档是原材料和证据——绝不是继续打补丁的基底。

对旧内容的默认姿态是保留：每个块都要核实，核实通过的保留原文措辞，只有核实不过的才被移除。这个 skill 的价值在于把烂文档里藏着的大量小错误一条一条揪出来、留下核实记录——而不是写一篇更漂亮的文章。

核实分两个层次进行：宏观（文档的框架——YAML frontmatter、标题、宗旨）和微观（每一个具体的点）。两层适用同一条规则：没过就移除。

交付三样东西：重写后的完整文档、旧文档每个块的处置判定、没有用户参与就无法核实的遗留问题清单。

核心原则

文档烂掉的根因：真正的共识活在对话里，文档只收到补丁——而每个补丁面对的都是共识的不同快照。继续打补丁治不了这个病。解法是先把共识显式化，再从共识重新推导出文档。

所以顺序是固定的：先锚点，后重写。锚点没写下来之前不动笔；旧文本没有判定之前不进新文档。

而且判定靠核实挣来，不靠感觉。能查证的论断——对照锚点、代码库、配置文件、schema、可运行的命令——在保留或删除之前必须真的查证过。查证不了的论断绝不悄悄保留或悄悄丢弃，进遗留问题。

核实即移除，不是核实即修复。面对核实不过的块，解释它为什么没过、然后写一个"修正版"的冲动，恰恰是腐烂进入文档的方式：那个"修复"是穿着修复外衣的猜测，而且读起来一脸权威。直接移除它。如果它覆盖的主题仍然需要，覆盖内容来自锚点；锚点里没有，缺口就进遗留问题，由用户来有意识地补。

工作流

1. 构建锚点。收集此刻成立的结论：已做的决定、后来被推翻的决定（以推翻为准）、仍然有效的约束、文档的目标读者和职责。来源：用户的消息、讨论历史、关联文档。把锚点写成带编号的结论列表——它会随输出一起交付，让读者能对照检查重写结果。

2. 逼问缺口。如果锚点回答不了"这文档给谁看"或"X 最终怎么定的"，先向用户提出尖锐的问题，再动笔。基于猜测的锚点重写出来的，只是下一版烂文档。

3. 盘点旧文档。把它拆成块（章节、论断、表格、示例、命令、数字）。盘点的目的是让每个块都被核实到——一个不漏。

4. 分宏观、微观两层核实。

• 宏观——文档的框架。最先核实 frontmatter/YAML 元数据、标题、宗旨和顶层框架。框架已经不符合当前场景、或者干脆落后于场景的，和任何块一样按没过处理：移除（替代框架从锚点来）。框架没过还会向下连坐——只为旧框架服务的内容必须重新对照锚点核实，而不是对照那个已经死掉的框架。
• 微观——逐点过，一个不漏。每个块先对照锚点，再对照一切可查证的东西：代码、配置、schema、它引用的命令和路径、关联文档。点很多的文档正是腐烂藏身的地方：列表绝不整体放行——只有每一项都单独核实通过，列表才算通过；没过的项单独移除。

两层核实了什么都要记录——处置决策表要引用它。

5. 给每个块恰好一个判定：

• 保留——核实后仍然成立；复用原文措辞和语感。
• 删除——核实没过：核实为错、与锚点矛盾，或是没人能解释的补丁残留。写明是哪项核实没过。不要把它改写成一个能通过的版本——移除它；需要替代覆盖时从锚点来，不从失败块来。
• 待定——没有用户参与无法核实；放进遗留问题。绝不悄悄保留或悄悄丢弃。

6. 有意识地决定结构。旧结构仍然服务于锚点时就保留它——保留不只针对措辞，也针对结构。只有结构本身就是补丁残留时，才从锚点重新推导。

7. 完整写出新文档。它必须能独立成立——一个没看过讨论历史的读者也能读懂。除非锚点改变了受众，否则沿用原文的语言和语域。

8. 逐条对照锚点检查重写结果。每条锚点结论都有体现；新文档里的每样东西都能追溯到锚点或某个"保留"判定。不通过的地方要么修掉，要么移入遗留问题。

输出

原地替换原文件——历史由版本控制和处置决策表承载；旁路副本只会变成下一块补丁残留。只有用户明确要求保留原文件时才写入单独的文件。回复里承载其余部分：

# Hai Rewrite Doc: <文档名>
## 锚点                 ——重写所依据的带编号当前结论
## 重写后的文档          ——重写后文件的路径（足够短时才内联）
## 处置决策表            ——旧块 → 保留 / 删除 / 待定，各自写明通过或未通过的那项核实
## 遗留问题              ——锚点无法回答的问题，以及各自阻塞哪个章节

最终输出前读取 references/output-template.md。

何时改用别的 skill

• 用户要的是问题报告，不是重写后的文档——用 hai-audit-docs-internally。
• 真相源是代码而不是讨论——用 hai-audit-docs-against-code。
• 文档是 PRD——用 hai-prd，它的 Craft 模式负责 PRD 的诊断与修复重写。
• 文档是计划或目标文档——用 hai-goal，它的 rewrite 模式负责围绕目标重新锚定计划。
• 只是结构和排版有问题、内容没毛病——用 readme-beautifier。
• 真正的问题是哪些概念该不该存在——先跑 hai-razor，再重写。

这个 skill 不是什么

• 不是美化器——它改的是内容和判断，不只是排版。
• 不是补丁合并器——它绝不产出"旧文档加上最新修改"。
• 不是摘要器——产出是一份完整可用的文档，不是文摘。
• 不是重新创作——核实为真的内容原样保留，不做无谓的转述。
• 不是修理铺——核实不过的块被移除，绝不修补成能通过的样子。
• 不沉默——旧文档里的任何东西消失，处置决策表里都有一行交代。

常见错误

• 锚点还没显式化就动笔——重写继承的是猜测而不是结论。
• 凭感觉判块而不去查证——能查证的论断必须查证。
• 列表整体放行——只有每一项都单独核实通过，列表才算通过。
• 因为框架"看起来是结构"就跳过它——过时的 frontmatter/YAML 元数据和任何块一样，没过就移除。
• 修补核实不过的块而不是移除它——解释它为什么没过、再写个"修正版"，等于把猜测重新放回文档；没过就移除。
• 删除时不写明哪项核实没过；"删除"判定是挣来的，不是断言出来的。
• 把"讨论过一次"当成共识；只有最新仍然成立的决定才算数。
• 悄悄丢块，而不是记一条"删除"判定。
• 把"保留"块也重写一遍，毁掉原作者的语感。