维护文档
1. 明确职责和当前范围
使用本技能来决定是创建还是重用记录、组织内容、验证描述、暴露差距，以及维护源关系、状态和导航。这需要工程判断：在解释当前机制时，应调查实际路径；不要仅仅重新格式化对话或通过填充模板来制造虚假确定性。
- 执行当前任务的代理负责技术选择、权衡、任务分解、实现、调试和验证；当输出需要被保留时，使用这些共享规则。对子系统文档进行有针对性的调查和更新是有效的任务，不要求首先启动单独的设计流程。
- 使用
to-docs创建可读的设计交付物，供人员审阅、编辑和后续参考。设计可以是完整的来源；本技能指导从保存起文档的所有权和一致性。不要首先要求工程记录，也不要在技能之间创建循环调用。 - 使用
grilling来深入澄清当前主题；grill-me是其明确的入口点。基于已建立的内容继续，无需重新打开决策或为每次迭代添加审批门。 - 使用
decision-notes来查找、记录、取代和组织长期决策。本技能引用其结论；它不建立单独的面试流程或决策生命周期。当其触发条件适用时进行搜索，即使没有直接链接。 - 根据需要，使用
handoff来准备或验证跨会话或跨代理的交接。本技能继续维护工程材料和状态；不要仅仅因为执行任务的人员改变了就创建一个完整的副本，也不要在技能之间创建循环调用。 - 普通的阅读、即时的问题以及不影响现有材料的小修改不会独立触发完整的维护流程；但仍然要阅读任务所需的材料。仅文档请求不会扩展更改产品行为、运行不相关的检查或提交代码的权限；现有的工程任务授权仍然有效。
使用环境中实际可用的名称。如果某个技能无法调用，则改为阅读项目配置的指导；不要声称已调用不可用的技能。协作不得导致循环加载或重复搜索。
2. 定位来源并决定是重用还是创建记录
从项目实际的代理入口点开始，定位约束、需求和验收标准、相关子系统、变更记录和注释；验证当前工作的范围。对于现有项目，优先使用现有位置和名称；不要求迁移。对于跨子系统的工作，覆盖相关接口和共享约束。
如果对于同一任务已经读取并验证的上下文仍然适用，则重用它。当范围、关键前提或来源发生变化，或出现冲突时，重新检查受影响的区域。不要仅仅因为轮次或技能变更而重新扫描整个仓库或重新开始访谈。
在选择位置、名称、文件拆分或导航时，请阅读 组织和来源。
- 首先查找仍然适用于同一变更的现有文档；相似的主题不一定意味着同一变更。要继续现有工作，定位其原始记录并验证当前状态，而不是自动编写完整的交接文档。
- 当目标设计、迁移计划、依赖关系或要调查或验证的问题必须被保留以供后续实现、验收或跨会话延续时，创建或更新记录。这也适用于调查和解决方案比较期间。
- 在当前轮次中完成的小而清晰的变更可以仅通过对话交付，同时仍然维护受影响的现有文档和既定规则要求的注释。如果用户明确要求保存某些内容，则将其记录下来，优先选择适当的现有来源。
- 不要根据行数、文件数、对话轮次或提交次数机械地创建记录。不要预先创建空页面或完整的文档库，也不要每次都询问是否要编写文档。
3. 根据其目的验证和维护材料
| 当前工作 | 根据需要阅读 | 信息所有权 |
|---|---|---|
| 验证人可读设计与工程材料之间的所有权和对齐 | 组织和来源 | 人可读设计保留目标、场景和行为的完整来源；工程材料引用和补充它们 |
| 描述当前子系统或纠正文档与实现之间的差异 | 子系统文档 | 当前职责、机制、契约以及指向源代码、测试和注释的导航 |
| 记录变更目标、设计、任务和延续上下文 | 变更设计和计划 | 当前目标、与现有状态的差距、未解决的问题、实现和验证计划 |
| 更新状态；完成、暂停、取消、恢复或关闭记录 | 状态和结项 | 总体进度、任务结果、实际验证以及剩余工作的处理 |
在每个事实的单一位置维护它；在其他位置总结并链接到它。docs/designs/<topic>.md 可以是完整的人可读设计来源。仅在必要时将工程细节、依赖关系、验证和进度添加到 .agents/changes/；不要复制设计。不要将对现有来源的概述变成完整的副本，不要在索引中创建第二个状态或进度记录，也不要在其注释来源之外维护长期理由。
工程变更入口点、README、计划和总体状态规则仅适用于需要工程变更记录的工作；它们不适用于人可读设计。设计的已确定或未确定内容不是工程进度。不要引入强制性的设计状态机，也不要为每个设计创建配套的工程目录。
区分已确定的结论、未确定的建议、假设和要调查的项目与源代码验证、现有测试覆盖和实际运行时验证。链接应解释它们所支持的机制、覆盖的行为或决策主题。测试的存在并不意味着它已成功运行。采用目标并不意味着它已实现，也不会自动删除过渡或兼容性义务。
当文档与实现不一致时，检查相关的源代码、测试、需求、适用的注释和实现状态。确定文档是否过时、实现是否偏离预期行为，或者过渡是否不完整。纠正已验证的文档错误；在现有授权范围内处理实现错误。不要将缺陷描述为正常契约，也不要使用旧文档来推翻新的用户指令。如果关键行为或权衡仍不明确，则描述冲突并要求用户决定，同时继续不依赖于该决定的工作。
4. 使材料与实质性变更保持同步
- 当子系统职责、边界、主路径、接口、状态、故障行为、兼容性行为或必要导航发生变更时，在已验证的变更旁边更新相关文档，而不是等待项目完成。不要机械地重写那些在内部重构后仍然准确的描述，但要修复损坏的链接。
- 当目标、范围、关键选择或前提明显发生变化时，更新设计；继续将未解决的内容标记为未解决。当任务结果、依赖关系、阻碍或后续步骤发生影响执行或延续的变更时，更新计划。在执行受影响步骤之前同步重要的时间表变更；不要记录每个工具操作。
- 在现有授权范围内自主处理调整。文档更新不会增加审批要求，也不能替代必要的用户决策。要求用户决定超出授权范围的行为、范围或关键权衡变更；不要重新确认已确定的事项。
- 在交付、暂停或交接之前，验证需要持续保留的相关材料允许下一个代理识别当前状态、与目标的差距、剩余工作和下一步。不要等到这些时刻才进行第一次记录。
仅处理当前任务相关的范围。将当前的事实保留在子系统文档中，长期决策保留在 decision-notes 中，其他位置引用它们。
5. 检查和交付
检查为此任务商定的范围；不要将其变成仓库范围的审计：
- 覆盖面和所有权：保留需要持久化的内容；重用适当的来源，不重复的散文、空占位符或仅留在临时对话中的延续上下文。
- 准确性：明确说明当前状态、目标、已确定和未确定的点以及证据；不要混淆阶段进度、代码变更、成功验证和所需的手动验收。
- 状态和延续：如果存在工程变更记录，则仅在其变更入口点维护其总体状态，并根据实际进度标记任务。使相关的阻碍、差距、后续步骤和剩余工作可定位；在结项记录中保留必要的结论和证据。
- 链接和一致性：保持相关需求与验收标准、设计、计划、子系统和注释的准确连接；确保链接有效。重新组织材料或记录不得丢失独特信息。
- 验证范围：根据任务和项目运行适用的现有检查，并审查结果；如果没有专用工具，则执行手动审查。不要为了完成文档而强加不相关的检查、完整的测试套件或新的工具链。当内容未更改时重用已验证的结果，并准确描述未验证或受限的区域。
完成当前文档任务意味着商定的信息是准确的，来源是可定位的，未知项和验证差距已被披露，并且材料支持延续。它不证明设计是充分的、实现是正确的或功能是完整的。使用 状态和结项 分别验证整个变更的完成。
通过简洁的解释和指向实际文件的链接交付此轮中的变更、检查和必要差距；将需要持续维护的结果放入仓库。将相关的代码、文档和注释作为待交付物放在一起。保存文档不授权提交、推送、PR 或发布；遵循项目现有的提交确认规则，不要仅仅因为保存了文档就过早提交。