maintain-project-context

维护项目上下文

此技能需要 define-product。开始任何工作前，请确认它已安装。如果未安装，请停止并报告这一情况，同时提供其安装命令 npx skills@latest add toy-crane/skills --skill define-product；如果项目指定了包管理器运行器，则使用该运行器。

对未来工作会复用的持久上下文进行一次有计划的清理。让当前含义更容易查找，但不要替任何产物做决策。

保留权威性

• 只有在用户确认、明确委托了该类决策，或权威项目来源已明确说明某项含义时，才应用该含义。
• 使用已发布的代码来发现过时文档，而不是用来证明意图。本次检查期间不要更改产品代码。
• 如果来源之间的预期含义相互冲突，或发布情况不明确，请保持来源不变。提出继续所需的确切问题；绝不要根据文件日期、实现的普遍程度、accepted 等标签或沉默来做选择。
• 当前事实或决策只保留在负责维护它的产物中。不要另建平行摘要，也不要在多个文件中重复相同的权威信息。

检查持久信息载体

只检查已存在或清理所需的信息载体：

• 根目录中的 PRODUCT.md，用于说明应用级产品前提；
• 根目录中的 GLOSSARY.md，用于说明当前项目术语；
• docs/decisions/README.md 和相关主题契约；
• 其工作可能已发布的 docs/specs/<slug>/ 文件夹；
• 始终加载的仓库指导文件，例如 AGENTS.md 和 CLAUDE.md。

不要仅因某个可选文件缺失就采取行动。这是一次跨产物的定期检查，不是对某个刚刚确定的新术语、决策或后续事项进行增量记录。

维护产品上下文

如果存在 PRODUCT.md，请将其中的陈述与明确的当前产品决策及其他权威上下文进行比较。删除重复或过时的措辞，并应用已确定的产品含义，同时保留仍然有效的内容。

让 PRODUCT.md 只包含产品内容：应用定义、用户及其所处情境、问题与替代方案、承诺带来的改变、核心循环、应用级能力与边界、体验原则、成功信号、假设和未知事项。不要将技术栈、架构、仓库机制、屏幕要求、工作单元范围或验收标准移入其中。

如果拟议的编辑会为新受众、问题、承诺、核心循环、产品边界或其他产品意图做出选择，请保持文件不变，并请用户确定该含义。如果用户希望重新审视产品前提，请调用 define-product，并提供当前的 PRODUCT.md、发现的确切歧义，以及受其影响的信息载体，使其只修订该前提中的相关部分；它会交还更新后的 PRODUCT.md，之后本次检查再继续，并据此协调其余持久信息载体。

维护决策契约

列出 docs/decisions/，并在存在索引时阅读该索引。检查是否有文件未列入索引，然后将相关主题与当前上下文和剩余规范进行比较。

每个主题保留一个可编辑的决策文件。使用 Git 记录历史，而不要在活动文件夹中保留旧决策文件。如果多个文件明确表达了同一项决策，就用最清晰、稳定的主题名称将它们合并。删除冗余文件前，更新所有指向这些文件的链接。

本次创建或编辑的每份决策契约都必须包含主题标题和以下必需章节：

• Decisions：列出所有当前规则；
• Why：说明应用规则所需的最低限度理由，避免重复相同的讨论。

仅在以下章节具有当前价值时添加：

• Boundaries：限制或例外；
• Reconsider when：应重新审议该决策的具体条件；
• Still-rejected alternatives：未来的 Agent 可能会重试的已否决方案；
• Evidence worth preserving：重新获取成本较高的测量结果或实验。

删除状态字段、取代关系链、采用或更新日期、拉取请求顺序以及旧实现说明。若日期用于设定当前规则或告知未来工作何时重新审议，则保留该日期。

删除其他内容前，先考虑：缺少这些内容是否会导致有能力的未来 Agent 在相同条件下重复提出相同方案、开展相同调查或实验，或重走失败的路径？如果会，就保留最简短的说明以避免重复。删除重复内容，以及不太可能再次出现的替代方案。

维护相关文件

• 在 docs/decisions/README.md 中，每个决策文件恰好保留一条索引项： - [主题](subject.md) — 在……时阅读。确保每个链接都有效。路由短语应说明何时打开文件，而不是文件作出了什么决策。
• 在 GLOSSARY.md 中，仅保留项目当前使用的术语；只有当项目用语已经改变时才重写定义。
• 对于已确认发布的每个 docs/specs/<slug>/，先将所有符合条件、可复用的决策保存在其所属契约中，再删除该文件夹。如果是否发布尚不明确，则保留该文件夹并提出询问。在活动规范中，仅更新已在其他地方确认的链接和术语。
• 在始终加载的说明中，保留仓库工作规则以及指向决策索引的路径。删除复制的决策或产品内容，但不要更改无关说明。

如果清理需要，创建、重命名或重建决策契约及其索引。不要合并无关主题，也不要为了达到大小目标而删除必要说明。若索引或始终加载的文件仍然难以浏览，请报告并说明原因。

对齐问题追踪器镜像

当 AGENTS.md 或 CLAUDE.md 中包含 ## Issue tracker 部分时，读取这两个文件，并使用最先找到的该部分及其链接的详细约定（如有）。现有的内联约定仍然有效；无需安装设置技能。如果无法读取链接的文档，请报告追踪器相关工作受阻，并继续维护仓库上下文。将其中的问题视为衍生的协调界面，绝不将其视为产品含义、发布、术语或决策的权威来源。不要将问题描述或评论导入持久项目上下文。

解析并获取远程仓库公布的默认分支。将追踪器与该已获取分支上的 docs/specs/<slug>/ 文件夹进行比较，而不是与当前检出中的未合并更改进行比较。每个文件夹的 spec.md 都通过 Issue: <tracker>:<id> 行标明一个问题；按该 ID 获取每个问题。绝不要通过列出问题或按标题搜索来查找文件夹对应的问题，也不要查找孤立或重复的问题；由人员在追踪器中整理重复项。如果约定仍描述 spec:<slug> 标题键、Source-Issue 行或受管理的问题列表，请告知用户重新运行 setup-issue-tracker，而不要使用这些操作；并让用户在活动的规范文件夹中将 Source-Issue: 改为 Issue:；不读取旧行。

对于默认分支上的每个规范文件夹，按以下规则处理：

• 报告缺少 Issue: 行或无法按 ID 获取问题的文件夹，不创建任何内容；下一个包含该文件夹的 PR 会创建其问题。
• 仅根据已获取的 spec.md，刷新问题中由约定标记界定的规范部分：其第一个部分的文本、其余部分标题、文件夹路径，以及指向 Blocked by: docs/specs/<other>/ 的问题引用。保留问题标题和正文的所有其他部分，无论这些内容由人员还是 Agent 创建。
• 将其阻塞项集合替换为其 Blocked by 文件夹的 Issue: 行所列的问题，删除过时的关联并添加缺失的关联，同时保留问题的指派对象以及打开或关闭状态。如果某个阻塞文件夹没有 Issue: 行，请报告该情况，并保持依赖问题的整个阻塞关系集合不变，而不要根据不完整信息删除关联。
• 绝不要因为文件夹不存在而关闭问题，也绝不要仅因文件夹仍然存在就重新打开已关闭的问题。只有已确认的实现交付或记录在案的追踪器约定才能决定关闭状态。

搜索已合并 PR 正文中的精确 Issue: <tracker>:<id> 行，包括其规范文件夹后来已删除的 PR，并按 ID 获取每个问题。只有当已合并 PR 的差异和验证能够证明该问题的实现已交付时，它才是关闭操作失败后的可靠重试依据；Spec-Folder 尾注、关联的规范 PR、Issue: 行或文件夹缺失本身都不足以证明这一点。对于打开的问题，重试约定规定的关闭操作，然后验证其状态。对于没有实现交付的仅规范类已合并 PR，保持问题打开。如果问题仍带有 PR 审查或活动工作的信号，请检查是否有更新的实现工作，然后使用约定规定的标记为就绪操作并验证结果。绝不要将已开始的工作降级。如果既无法安全关闭，也无法确认就绪状态，请报告确切缺失的 PR 证据或失败的操作。即使原始合并运行报告了追踪器故障，也要执行此追补；不要依赖该运行的分支或提交尾注在压缩合并后仍然存在。

如果配置的工具不可用或任何操作失败，请完成仓库清理，报告未完成的追踪器操作及原因，并保留其余问题状态以供后续处理。

完成

当每个可安全确定归属的主题都有一个负责人和一种当前表述形式、已确认发布的规范已退役、当前可选界面中不再存在已知的过时重复内容、配置的跟踪器镜像已在其记录的操作所允许的范围内完成协调，并且含义不明确之处仍得到保留时，即可完成。

报告更改内容、删除内容、有意未作更改的内容，以及已更新、已关闭或因何理由保持不变的跟踪器问题，并列出每个未解决冲突或发布状态不明之处所需的确切问题。