update-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Documentation

更新文档

CRITICAL: Oracle-First Protocol

重要提示：Oracle优先协议

BEFORE making ANY changes to documentation, you MUST consult the Oracle to understand what exists and what must be preserved.

Documentation often contains hard-won knowledge, historical context, and decisions that aren't obvious from code alone. Blindly updating docs risks losing this irreplaceable information.

在对文档进行任何修改之前，你必须先咨询Oracle，了解现有内容以及必须保留的部分。

文档中通常包含来之不易的知识、历史背景以及仅从代码中无法体现的决策。盲目更新文档可能会丢失这些不可替代的信息。

Mandatory Pre-Update Oracle Consultation

更新前必须进行的Oracle咨询

For EACH significant document (especially AGENTS.md, architecture docs, decision records):

teams(action: 'delegate', tasks: [{
  text: 'You are The Oracle - analyze this documentation before it gets updated.\n\nDOCUMENT PATH: [path]\nDOCUMENT CONTENT:\n[full content]\n\nANALYSIS REQUIRED:\n\n1. **Critical Knowledge Inventory**\n   - What unique insights/decisions does this document contain?\n   - What historical context would be lost if overwritten?\n   - What hard-won lessons or gotchas are documented?\n   - What non-obvious information exists that code doesn\'t reveal?\n\n2. **Preservation Requirements**\n   - List specific sections/paragraphs that MUST be preserved\n   - Identify any warnings, caveats, or "don\'t do X" guidance\n   - Note any project-specific conventions explained here\n   - Flag any links to external resources or related docs\n\n3. **Safe to Update**\n   - What sections are purely factual and safe to update from code?\n   - What sections are demonstrably outdated based on codebase?\n   - What can be verified objectively vs. requires human judgment?\n\n4. **Update Recommendations**\n   - Specific guidance for updating this document safely\n   - Sections to leave untouched without human approval\n   - Suggested merge strategy (preserve + add vs. replace)\n\nBe thorough. Assume any knowledge lost here is lost forever.',
  assignee: 'doc-oracle'
}])

对于每一份重要文档（尤其是AGENTS.md、架构文档、决策记录）：

teams(action: 'delegate', tasks: [{
  text: 'You are The Oracle - analyze this documentation before it gets updated.\n\nDOCUMENT PATH: [path]\nDOCUMENT CONTENT:\n[full content]\n\nANALYSIS REQUIRED:\n\n1. **Critical Knowledge Inventory**\n   - What unique insights/decisions does this document contain?\n   - What historical context would be lost if overwritten?\n   - What hard-won lessons or gotchas are documented?\n   - What non-obvious information exists that code doesn\'t reveal?\n\n2. **Preservation Requirements**\n   - List specific sections/paragraphs that MUST be preserved\n   - Identify any warnings, caveats, or "don\'t do X" guidance\n   - Note any project-specific conventions explained here\n   - Flag any links to external resources or related docs\n\n3. **Safe to Update**\n   - What sections are purely factual and safe to update from code?\n   - What sections are demonstrably outdated based on codebase?\n   - What can be verified objectively vs. requires human judgment?\n\n4. **Update Recommendations**\n   - Specific guidance for updating this document safely\n   - Sections to leave untouched without human approval\n   - Suggested merge strategy (preserve + add vs. replace)\n\nBe thorough. Assume any knowledge lost here is lost forever.',
  assignee: 'doc-oracle'
}])

When Oracle Consultation is MANDATORY

必须进行Oracle咨询的场景

ALWAYS for: AGENTS.md files, architecture docs, decision records, onboarding guides
ALWAYS for: Any doc >200 lines or last modified >30 days ago
ALWAYS for: Docs with sections titled "Why", "History", "Decisions", "Gotchas", "Warnings"
RECOMMENDED for: All other significant documentation

所有AGENTS.md文件、架构文档、决策记录、入职指南
所有篇幅超过200行或上次修改时间超过30天的文档
所有包含“Why”、“History”、“Decisions”、“Gotchas”、“Warnings”等标题章节的文档
建议对所有其他重要文档进行咨询

When You Can Skip Oracle (rare)

可跳过Oracle咨询的罕见场景

Trivial typo fixes
Adding new sections (not modifying existing)
Updating version numbers or dates
Fixing broken links to known-good targets

微小的拼写错误修复
添加新章节（不修改现有内容）
更新版本号或日期
将失效链接修复为已知可用的目标

Instructions

操作说明

Systematically review and update all project documentation to ensure accuracy, completeness, and alignment with current codebase state.

系统性地审查和更新所有项目文档，确保其准确性、完整性，并与当前代码库状态保持一致。

Phase 0: Oracle Pre-Analysis (NEW - MANDATORY)

阶段0：Oracle预分析（新增 - 必须执行）

Before touching ANY documentation:

Identify high-value documents - AGENTS.md, architecture docs, decision records
Run Oracle analysis on each high-value document
Create preservation checklist from Oracle findings
Add preservation requirements to TodoWrite - these are non-negotiable

Example TodoWrite entries from Oracle:

- [ ] PRESERVE: Authentication decision rationale in AGENTS.md (lines 45-67)
- [ ] PRESERVE: Database migration warnings in architecture.md
- [ ] PRESERVE: "Why we don't use X" section in conventions.md
- [ ] SAFE TO UPDATE: API endpoint list (verify against code)

在接触任何文档之前：

识别高价值文档 - AGENTS.md、架构文档、决策记录
对每份高价值文档执行Oracle分析
根据Oracle的分析结果创建留存清单
将留存要求添加到TodoWrite中 - 这些要求不可协商

来自Oracle的TodoWrite条目示例：

- [ ] PRESERVE: Authentication decision rationale in AGENTS.md (lines 45-67)
- [ ] PRESERVE: Database migration warnings in architecture.md
- [ ] PRESERVE: "Why we don't use X" section in conventions.md
- [ ] SAFE TO UPDATE: API endpoint list (verify against code)

Phase 1: Discovery & Analysis

阶段1：发现与分析

Find all documentation files:
- Plan tickets (tagged
```
plan
```
  ) - search with
```
tk list --tag plan
```
- ```
**/AGENTS.md
```
  - Claude-specific guidelines
- ```
docs/**/*
```
  - General documentation
- ```
.tasks/**/*
```
  - Task tracking files
- Any other doc files the user specifies
Git analysis (if applicable):
- Check when docs were last modified
- Identify code changes since last doc update
- Use
```
git log
```
  to understand what changed
Create comprehensive todo list - One item per document to review
- Include Oracle preservation requirements from Phase 0

查找所有文档文件：
- 计划工单（标记为
```
plan
```
  ） - 使用
```
tk list --tag plan
```
  搜索
- ```
**/AGENTS.md
```
  - Claude相关指南
- ```
docs/**/*
```
  - 通用文档
- ```
.tasks/**/*
```
  - 任务跟踪文件
- 用户指定的其他任何文档文件
Git分析（如适用）：
- 检查文档上次修改的时间
- 识别自上次文档更新以来的代码变更
- 使用
```
git log
```
  了解变更内容
创建完整的待办事项列表 - 每份待审查文档对应一个条目
- 包含阶段0中的Oracle留存要求

Phase 2: Systematic Document Review

阶段2：系统性文档审查

For EACH document in the todo list:

对待办事项列表中的每一份文档：

Step 1: Read & Understand

步骤1：阅读与理解

Fully read the document
Understand its purpose and scope
Note any references to code, features, or architecture
Check Oracle preservation list for this document

完整阅读文档
理解其目的和范围
记录所有对代码、功能或架构的引用
查看该文档对应的Oracle留存清单

Step 2: Validate Against Codebase

步骤2：与代码库验证

Audit the codebase to check if documentation is:

Misleading: Claims something that isn't true
Outdated: References old code, deprecated patterns, or removed features
Wrong: Contains factual errors about implementation
Missing: Lacks important information about current state
Redundant: Duplicates information found elsewhere

CRITICAL: Cross-reference with Oracle preservation list. If something seems outdated but Oracle flagged it as "preserve", DO NOT modify without explicit confirmation.

审核代码库，检查文档是否：

存在误导：描述内容与实际不符
已过时：引用旧代码、已弃用的模式或已移除的功能
存在错误：包含关于实现的事实错误
内容缺失：缺少关于当前状态的重要信息
冗余：重复其他地方已有的信息

重要提示：对照Oracle留存清单交叉验证。如果某些内容看似过时但Oracle标记为“需留存”，则未经明确确认不得修改。

Step 3: Check Compliance

步骤3：合规性检查

Verify document follows guidelines in

AGENTS.md

Naming conventions
Architecture patterns
Code style requirements
File organization rules

验证文档是否遵循AGENTS.md中的指南：

命名规范
架构模式
代码风格要求
文件组织规则

Step 4: Special Handling for Plan Documents

步骤4：计划文档的特殊处理

Plan tickets require careful status tracking:

Investigation:

Thoroughly audit codebase to determine implementation status
Check each item in the plan against actual code
NEVER assume - verify everything with code inspection

Status Categorization:

Open: Plan not yet implemented or partially implemented
Closed: Plan completely implemented and verified (close with
```
tk close <id>
```
)
Obsolete: Plan no longer relevant or superseded (close with note)

Progress Marking:

Add progress notes to plan tickets using
```
tk add-note <id> "<progress>"
```
Be conservative - only close with 100% confirmation

CRITICAL: NEVER close a plan ticket until you have 100% confirmation through code audit that EVERY item is implemented.

计划工单需要仔细跟踪状态：

调查：

彻底审核代码库以确定实现状态
将计划中的每一项与实际代码进行核对
绝不假设 - 所有内容都必须通过代码检查验证

状态分类：

已完成：计划已完全实现并验证（使用
```
tk close <id>
```
关闭）
待处理：计划尚未实现或仅部分实现
已废弃：计划不再相关或已被取代（添加说明后关闭）

进度标记：

使用
```
tk add-note <id> "<progress>"
```
向计划工单添加进度说明
保持谨慎 - 只有100%确认后才能标记为完成

重要提示：在通过代码审核100%确认计划中的每一项都已实现之前，绝不要关闭计划工单。

Step 5: Update Document (WITH PRESERVATION PROTOCOL)

步骤5：更新文档（遵循留存协议）

Before ANY edit, verify:

Oracle preservation requirements are honored
No "Why", "History", or "Decision" sections are being removed
Warnings and gotchas are being kept
You're ADDING to existing knowledge, not replacing it

Safe update patterns:

Fix factual errors (wrong file paths, outdated API signatures)
Add new information alongside existing
Update status markers and dates
Fix broken links

Dangerous patterns (require confirmation):

Deleting any paragraph >2 sentences
Rewriting explanatory sections
Removing "deprecated" or "don't use" warnings
Changing architectural guidance

在进行任何编辑之前，验证：

已遵循Oracle留存要求
未删除任何“Why”、“History”或“Decision”章节
保留了警告和注意事项
是在现有知识基础上添加内容，而非替换

安全的更新模式：

修复事实错误（错误的文件路径、过时的API签名）
在现有内容旁添加新信息
更新状态标记和日期
修复失效链接

危险的更新模式（需要确认）：

删除任何超过2句话的段落
重写解释性章节
移除“已弃用”或“请勿执行此操作”的警告
更改架构指南

Step 6: Validate Changes

步骤6：验证变更

Ensure changes are accurate
Verify Oracle preservation requirements were followed
Verify no information was lost
Check that references/links still work

确保变更内容准确
验证是否遵循了Oracle留存要求
确认没有信息丢失
检查引用/链接是否仍然可用

Step 7: Document Changes

步骤7：记录变更

Add to running change log:

File: [path]
Changes made: [description]
Reason: [why it was updated]
Preserved sections: [what was kept per Oracle guidance]

添加到变更日志中：

文件：[路径]
变更内容：[描述]
原因：[更新的理由]
留存章节：[根据Oracle指南保留的内容]

Step 8: Mark Complete

步骤8：标记完成

Update todo list to mark this document as completed

更新待办事项列表，将该文档标记为已完成

Phase 3: Cross-Document Analysis

阶段3：跨文档分析

After reviewing all individual documents:

Consistency check:
- Ensure all docs use consistent terminology
- Verify no conflicting information between docs
- Check that cross-references are valid
Coverage analysis:
- Identify features/code that lack documentation
- Find orphaned docs (no corresponding code)
- Note gaps in documentation coverage
Link validation:
- Verify internal references point to existing files
- Check that example code paths are correct
- Validate any external links

在审查完所有单个文档后：

一致性检查：
- 确保所有文档使用一致的术语
- 验证文档之间不存在冲突信息
- 检查交叉引用是否有效
覆盖范围分析：
- 识别缺乏文档的功能/代码
- 查找孤立文档（无对应代码）
- 记录文档覆盖范围的空白
链接验证：
- 验证内部引用指向现有文件
- 检查示例代码路径是否正确
- 验证所有外部链接

Phase 4: Summary & Recommendations

阶段4：总结与建议

Generate update summary:

markdown

undefined

生成更新总结：

markdown

undefined

Documentation Update Summary - [Date]

文档更新总结 - [日期]

Oracle Consultation

Oracle咨询情况

Documents analyzed: X
Critical sections preserved: Y
Preservation requirements followed: ✅/❌

分析的文档数量：X
留存的关键章节数量：Y
是否遵循留存要求：✅/❌

Files Updated: X

更新的文件数量：X

Changes Made:

变更内容：

Plans Status

计划状态

✅ Done: [list]
📋 Todo: [list]
⚠️ Obsolete: [list]

✅ 已完成：[列表]
📋 待处理：[列表]
⚠️ 已废弃：[列表]

Updates by Document

按文档分类的更新

[file path]
- Fixed: [what was wrong]
- Added: [what was missing]
- Removed: [what was redundant]
- Preserved: [what was kept per Oracle]

[文件路径]
- 修复：[存在的问题]
- 添加：[缺失的内容]
- 移除：[冗余的内容]
- 留存：[根据Oracle指南保留的内容]

Coverage Gaps

覆盖范围空白

[Undocumented features]
[Orphaned documentation]

[未文档化的功能]
[孤立文档]

Recommendations

建议

[Suggested improvements]
[New docs needed]


2. **Save summary** to `.docs-updates/update-[timestamp].md`

[建议的改进措施]
[需要新增的文档]


2. **保存总结**到`.docs-updates/update-[timestamp].md`

Phase 5: Validation

阶段5：验证

Build check - Ensure any doc-related code samples build correctly
Link check - Verify all internal references work
Completeness check - Confirm all todos were addressed
Preservation check - Verify Oracle requirements were honored

构建检查 - 确保所有文档相关的代码示例可以正确构建
链接检查 - 验证所有内部引用可用
完整性检查 - 确认所有待办事项都已处理
留存检查 - 验证是否遵循了Oracle的要求

Critical Principles

核心原则

ORACLE FIRST - Always consult Oracle before modifying significant docs
PRESERVE OVER REPLACE - Add new info, don't delete old wisdom
100% VERIFICATION REQUIRED - Never mark plans as done without complete code audit
NEVER SKIP DOCUMENTS - Review every file in the todo list
BE CONSERVATIVE - When in doubt about plan status, keep as todo
THOROUGH INVESTIGATION - Actually read the code to verify claims
PRESERVE INTENT - Keep the original purpose while updating facts
TRACK CHANGES - Document what was changed and why
COMPLIANCE FIRST - ALWAYS follow AGENTS.md guidelines
NO ASSUMPTIONS - Verify everything against actual code

Oracle优先 - 修改重要文档前必须先咨询Oracle
留存优先于替换 - 添加新信息，不要删除旧的经验
必须100%验证 - 未经过完整代码审核，绝不要标记计划为已完成
绝不跳过任何文档 - 审查待办列表中的每一个文件
保持谨慎 - 对计划状态存疑时，标记为待处理
彻底调查 - 实际阅读代码以验证所有声明
留存意图 - 在更新事实的同时保留原始目的
跟踪变更 - 记录变更内容及原因
合规优先 - 始终遵循AGENTS.md指南
绝不假设 - 所有内容都必须与实际代码验证

The Documentation Preservation Hierarchy

文档留存优先级

NEVER delete without explicit approval:

Architectural decisions and their rationale
"Why we did X" explanations
Warnings, gotchas, and "don't do this" guidance
Historical context and migration notes
Non-obvious conventions and their reasons

Safe to update freely:

Code examples (verify against actual code)
File paths and line numbers
Version numbers and dates
Status markers and checkboxes
Broken links (to known-good targets)

未经明确批准绝不能删除：

架构决策及其理由
“我们为什么选择X”的解释
警告、注意事项和“请勿执行此操作”的指南
历史背景和迁移说明
非显而易见的规范及其原因

可自由更新的内容：

代码示例（需与实际代码验证）
文件路径和行号
版本号和日期
状态标记和复选框
失效链接（修复为已知可用的目标）

Plan Status Decision Tree

计划状态决策树

Is EVERY item in the plan implemented?
├─ YES (verified in code) → Mark items with ✅
│  └─ Are ALL items marked ✅?
│     ├─ YES → Rename to .done.md
│     └─ NO → Rename to .todo.md (still has work)
│
├─ NO (some items not implemented) → Rename to .todo.md
│  └─ Mark implemented items with ✅
│
└─ Plan is superseded or irrelevant → Rename to .obsolete.md

Is EVERY item in the plan implemented?
├─ YES (verified in code) → Mark items with ✅
│  └─ Are ALL items marked ✅?
│     ├─ YES → Rename to .done.md
│     └─ NO → Rename to .todo.md (still has work)
│
├─ NO (some items not implemented) → Rename to .todo.md
│  └─ Mark implemented items with ✅
│
└─ Plan is superseded or irrelevant → Rename to .obsolete.md

Mermaid Diagrams in Documentation

文档中的Mermaid图表

When updating documentation, add or update Mermaid diagrams to visualize complex concepts.

更新文档时，添加或更新Mermaid图表以可视化复杂概念。

When to Add Diagrams

何时添加图表

Document Type	Diagram Use
Architecture docs	Component relationships, data flow
API documentation	Request/response sequences
Process guides	Workflow flowcharts
Decision records	Before/after state diagrams

文档类型	图表用途
架构文档	组件关系、数据流
API文档	请求/响应序列
流程指南	工作流流程图
决策记录	变更前后状态图

Diagram Maintenance

图表维护

When updating docs:

Check existing diagrams - Are they still accurate?
Update outdated diagrams - Reflect current architecture
Add missing diagrams - Where text alone is insufficient
Remove obsolete diagrams - If they show removed features

更新文档时：

检查现有图表 - 它们是否仍然准确？
更新过时的图表 - 反映当前架构
添加缺失的图表 - 当仅靠文字不足以说明时
移除废弃的图表 - 如果它们展示的是已移除的功能

Example: Architecture Update

示例：架构更新

markdown

undefined

markdown

undefined

Current Architecture

当前架构

mermaid

flowchart TD
    subgraph Frontend
        A[React App] --> B[API Client]
    end
    subgraph Backend
        B --> C[Express Server]
        C --> D[PostgreSQL]
        C --> E[Redis Cache]
    end


**Note:** Diagrams in documentation should be verified against actual code, just like text.

---

mermaid

flowchart TD
    subgraph Frontend
        A[React App] --> B[API Client]
    end
    subgraph Backend
        B --> C[Express Server]
        C --> D[PostgreSQL]
        C --> E[Redis Cache]
    end


**注意：** 文档中的图表应像文本一样，与实际代码进行验证。

---

Supporting Tools Integration

支持工具集成

Use Task (Oracle) to analyze docs before modification
Use Grep to search for TODOs or implementation evidence
Use Glob to find related files
Use Bash for git operations
Use Read to examine code thoroughly
Use Edit to update documentation
Use TodoWrite to track review progress AND preservation requirements

使用**Task (Oracle)**在修改前分析文档
使用Grep搜索TODO项或实现证据
使用Glob查找相关文件
使用Bash执行Git操作
使用Read仔细检查代码
使用Edit更新文档
使用TodoWrite跟踪审查进度和留存要求