Entry/Exit
- Entry: Changes already merged into the main branch
- Exit: Documentation consistency report
- Points to: After completion, proceed to
reflect-team-documentation(optional) or return to project work - Preloading: CANON.md
- Output path: After completion, proceed to
ship-workflow-ship
When not to use
- Code or artifacts have not yet been merged; documentation sync would be based on unstable facts
- You are only writing documentation for a new feature, not correcting project truth after a release
- The changes do not affect the README, architecture description, commands, paths, versions, or user documentation
Core anchors
Fact vs Narrative Dichotomy
Distinguish factual updates (paths, version numbers, counts, commands) from narrative changes (feature descriptions, architecture rationale, migration guides). Fix facts directly; narrative must ask the human partner.
Execution rules:
- Factual updates (paths/versions/counts/commands/config fields/links/spelling) → execute directly, do not ask
- Narrative changes (new feature descriptions/architecture rationale/new sections/migration guides/deprecation notices/project positioning) → ask the human partner item by item
- Confusing the two = documentation loses the human perspective = documentation becomes a lie
Process
Step 1: Diff analysis
Collect the files involved in the merged commit:git diff-tree --no-commit-id --name-only -r <merge-sha>
Classify changes: code files → affect README/ARCHITECTURE/API documentation; config files → affect deployment sections; dependency files → affect installation documentation; CI/CD files → affect CONTRIBUTING.
Step 2: Per-document audit
Cross-reference the changed files with project documentation. Check dimensions:
| Document | Content to check |
|---|---|
| README.md | Project description, installation steps, quick start, feature list |
| CLAUDE.md | Command mapping, skill list, project structure |
| AGENTS.md | Entry contract, activation gate, command mapping |
| docs/contracts/*.md | Detailed runtime rules (loaded on demand) |
| ARCHITECTURE.md | Component relationships, data flow, tech stack |
| CHANGELOG.md | Version entries, change types |
| CONTRIBUTING.md | Development process, PR rules, CI description |
Step 3: Automatically update factual content
Directly fix factual inconsistencies. Record each modification in the documentation consistency report. Do not modify narrative content, do not add new sections. Count changes must first verify the actual count.
Step 4: Ask about narrative changes
Ask the human partner about narrative inconsistencies item by item, one question at a time. Each question includes: file path + specific location + current content + reason for change. The human partner provides new content or chooses to skip. Do not write narrative content on behalf of the human partner.
Step 5: CHANGELOG polishing
Check the latest entry in CHANGELOG.md. Never overwrite or delete historical entries. Only polish the wording of the latest entry (clearer, more consistent), keeping it consistent with the existing format. Change types: Added / Changed / Fixed / Deprecated / Removed / Security, each starting with a verb.
Step 6: Cross-document consistency check
Verify that the same facts are stated consistently across all documents: version numbers, feature lists, component lists, command lists, API endpoints. When inconsistent, update the documents using code as the source of truth.
Step 7: Discoverability check
Confirm that every document can be reached from the entry point (README.md or CLAUDE.md) via links. Orphaned documents need references added.
Verification evidence
Output or records must include: input/source, action taken, verification result, blockers/fallbacks.
Common claims
| Claim | Reality | Consequence |
|---|---|---|
| "Documentation can be updated later" | "Later" never comes. Updating in sync with code changes is the lowest cost. | Updating documentation after the fact takes ×3-5 longer; a newcomer following old documentation = +2h on environment setup |
| "The CHANGELOG can just be written by itself" | AI polishes the wording, but only the human partner knows the business meaning of the changes. | Inaccurate narrative → users misunderstand the impact of changes → wrong upgrade decisions |
| "The README doesn't need to be that detailed" | The README is the first file a newcomer reads. One missing step = one more hour for the newcomer. | Each newcomer spends 1h extra × 10 people = 10h of team waste |
| "Nobody reads this document" | Nobody reads it because it is outdated. Documentation kept accurate will be discovered and used. | Outdated → trust collapses → the team stops referring to any documentation |
| "Just update it automatically, no need to ask" | Facts can be updated automatically. Narrative, judgments, and rationale cannot. | Automatically writing narrative → wording does not match true intent → documentation becomes lies |
Red flags
- Not distinguishing factual updates from narrative changes, modifying everything automatically
- Modifying or deleting historical entries in the CHANGELOG
- Updating numbers in documentation without verifying the actual counts
- Adding new sections that the human partner does not know about
- Skipping cross-document consistency checks
- Having orphaned pages in the documentation that cannot be reached from the entry point
- Skipping the entire sync process on the grounds that "documentation is not important"
- Listing multiple issues at once for the human partner to answer in bulk
Verification failure handling
| Verification item | Failure symptom | Handling method |
|---|---|---|
| Incomplete identification of changed files | Some merged files were not discovered | Expand the diff scope; check submodules and generated files |
| Factual updates not performed | Paths/versions/counts still inconsistent | Correct immediately; do not pause factual updates |
| Narrative changes not asked about | AI wrote the description on behalf of the human partner | Roll back the narrative modifications; ask item by item |
| CHANGELOG history modified | Old entries deleted or rewritten | Restore historical entries; only polishing the latest entry is allowed |
| Cross-document counts inconsistent | README does not match the code | Use code as the source of truth, verify, then update all documents |
Output template
文档同步完成：
事实性更新（已自动执行）:
- [文件]: [变更描述] (old → new)
叙事性更新（已询问 human partner）:
- [文件] [位置]: 已更新 (user provided) / 跳过 (user declined)
CHANGELOG:
- 最新条目措辞已润色
- 历史条目: 未修改
一致性检查:
- 版本号: 一致 / 不一致 → 已修复
- 特性列表: 一致 / 不一致 → 已修复
- 组件列表: 一致 / 不一致 → 已修复
- 命令列表: 一致 / 不一致 → 已修复
- API 端点: 一致 / 不一致 → 已修复
可发现性:
- 所有文档可从入口点到达 / [孤立文档] → 已添加引用
Verification checklist
- All changed files identified and classified
- Factual updates automatically performed and recorded
- Narrative changes have been asked item by item to the human partner
- CHANGELOG only polishes the latest entry, history untouched
- Version numbers are consistent across documents
- Feature list is consistent across documents
- Component list is consistent across documents
- All documents are reachable from the entry point
- Documentation consistency report has been output