change-boot

change-boot

概述

这是 team-boot 的 Class Boots 目录列出的五种 class boot 之一。team-boot 会在会话开始时注入始终相关的团队上下文（constitution、CDR 索引、技能注册表）；此技能按需加载变更历史层，即从 git 历史记录中挖掘并发布的 ChDR 索引，并附上记录建议，以便找回变更理由（挖掘历史使用 /change-init，记录本次会话中作出的决定使用 /change-specify），而不是让它们只留在提交消息中。此 boot 从不写入文件：它会建议使用记录技能，由用户运行该技能。

阅读过往理由并记录新理由是一个闭环：已发布的 ChDR 会说明代码为何如此；工作中发现的理由则通过记录技能回流到同一套记录系统中。

何时使用

在匹配的任务开始时调用——在规划待办列表和开始实施之前——让 ChDR 上下文为规划提供依据。 切勿等到会话结束时再调用。

在以下情况调用：

• 重构或修改不熟悉的代码——更改之前，先检查 ChDR 是否解释了当前代码结构。
• 分析回滚、热修复或修复链（“为什么要回滚这个变更？”）。
• 会话中创建了由人编写消息的 git 变更（使用了自编消息的提交/合并/回滚/变基/摘取提交/标签、由人编写的 PR 标题/正文、CHANGELOG 编辑）——在会话结束时评估其理由是否足够不显而易见，值得记录为 ChDR；使用自动生成或空消息的常规操作不属于 ChDR（合比例性门槛）。
• 会话中产生了变更理由：回滚/热修复说明，或关联到问题跟踪器的提交（即 /change-init 的挖掘信号）。

核心流程

步骤 1：定位 ChDR 索引

从当前工作目录开始（不要遍历父目录）：

• 首选：docs/adlc/memory/chdr/chdr.md（由 /change-publish 生成，位于 class 目录中，与 adr/adr.md 和 pdr/pdr.md 类似；行以 | ChDR 开头）
• 备用：docs/adlc/memory/chdr.md（较早的根目录布局）
• 备用：.adlc/memory/chdr.md（旧版布局，已弃用）

如果索引缺失，但存在 docs/adlc/memory/chdr/ChDR-*.md 或旧版 .adlc/memory/chdr/ChDR-*.md 文件，则根据每个文件合成精简表格（ID 取自文件名；Title/Status 取自 frontmatter 或首个标题）。如果都不存在，则报告 0 ChDRs——切勿捏造行。

如果当前工作目录中没有本地记忆索引，且该目录位于工作区内（通过祖先目录中的 .gitmodules 标记检测），则改为读取工作区根目录的 docs/adlc/memory/ 索引（双重读取顺序适用：先读取 docs/adlc/memory，再回退到旧版 .adlc/memory）。

步骤 1b：读取 ChDR 草稿索引

检查 .adlc/drafts/chdr/ 中是否存在 frontmatter 含 status: proposed 或 status: discovered 的 ChDR-*.md 文件。这些是待澄清的 ChDR 草稿——frontmatter 中的 proposed/discovered 对应台账中的 Status captured，且两者都计入 Unclarified 数量。从每个文件中提取 ID / Title / Type / Status / Date。 如果目录为空或不存在，则报告 0 pending drafts。

缺失上下文

如果本次会话中 team-boot 未注入团队上下文（第一条用户消息中没有 Team Context & Decisions 部分——项目未配置或钩子失败）：用一行说明这一点，输出该部分标题，并添加来源行 0 ChDRs matched (no team context injected — run /team-setup)，然后继续处理任务，依据直接读取的 ChDR 索引。切勿将缺失的注入视为空记录集。恢复方法：运行 /team-diagnose。

第 2 步：注入 ChDR 上下文（输出约定）

在任务答案之前输出：

## ChDR Context

| ID | Title | Status | Date |
|--|--|--|--|
| ChDR-001 | Why payments retries are capped at 3 | stable | 2026-08-16 |

_Searched N ChDRs, K matched._

## Drafts Pending Review

| ID | Title | Type | Status | Date |
|----|-------|------|--------|------|
| (from .adlc/drafts/chdr/) |

_Unclarified: N ChDR drafts — run /change-clarify to review._

• 从索引中输出 ID / 标题 / 状态 / 日期（完整索引还包含 Issue、Commit、Note——任务与某一行匹配时，请阅读对应的 ChDR-*.md）。
• N = 索引行总数；K = 与当前任务相关的行数。**K 必须等于展示的表格行数。**匹配到 0 行 → 只输出章节标题和 _Searched N ChDRs, K matched._ 这一行，不要输出表格。0 行表格的表头会折叠成未渲染的单行 Markdown；切勿输出。请将章节作为 Markdown 块输出——标题、表格行和计数行各占一行。

第 3 步：建议记录变更理由

触发条件	操作
已执行或分析回退或热修复，并附有理由	ChDR → 建议使用 /change-specify
已编写关联问题跟踪器的提交	ChDR → 建议在合并后使用 /change-specify
会话中编写了带有人为撰写消息的 Git 命令、撰写了 PR 标题/正文，或编辑了 CHANGELOG	在会话结束时评估：理由不明显 → 建议使用 /change-specify；常规操作跳过（适度性门槛）
从历史记录中发现修复链	ChDR → 建议使用 /change-init（挖掘历史记录）
账本中已有 ChDR 类决策	确认建议已显示；若未显示，则重新显示

对每个检测到的决策，在可见回复中各输出一行：

_Suggested capture: <decision name> → run /change-specify._

切勿自行撰写草稿（或任何文件）——用户运行 /change-specify 时，它会写入 .adlc/drafts/chdr/ 草稿，之后由 /change-clarify 对其进行把关。

将本次会话检测到的每个 ChDR 类决策添加或更新到 Team Context & Decisions（ID | Name | Type | Rel | Status | Clarify）中——包括本次启动前已存在的决策。将每项决策同时作为任务清单待办事项；对于已存在草稿的决策，在会话结束时建议运行 /change-specify → 对应的 clarify 技能。完成代码修改任务后，添加一条末尾待办事项，持续检查 Team Context & Decisions，直到达到 Unrecorded: 0 pending · Unclarified: 0 drafts（只有通过其 clarify 技能，或用户明确交接给指定的 clarify 或 execute 技能，草稿才会从 Unclarified 中移除）。在会话结束时，提供澄清提示，列出每项尚未记录的决策（ID + capture 技能）以及 .adlc/drafts/chdr/ 中每份已记录的 ChDR 草稿（ID + clarify 技能），也包括合并后关联问题跟踪器的提交；若用户延后澄清，请将这些行标记为已交接。

失败处理

• 索引和记录均缺失 → 只输出章节标题和 _Searched 0 ChDRs, 0 matched._，不要输出表格，然后继续处理用户任务；切勿阻塞。
• 无法解析的索引行 → 跳过格式错误的行，并注明跳过数量。

危险信号

• 捏造 ChDR 行，或使 K 大于展示的表格行数。
• 注入索引，却忽略记录理由的建议——两者配对才是重点。
• 自行撰写草稿（或任何文件）——启动流程只提供建议；由 /change-specify 负责写入。
• 向上遍历父目录以查找 .adlc/。
• 未提供 SHA/URL 来源凭据就挖掘理由——/change-clarify 会拒绝缺乏来源凭据的 Decision 声明。

验证

• 已输出带有 _Searched N ChDRs, K matched._ 的 ChDR Context 表格（K = 表格行数）。
• 已将检测到的 ChDR 类决策添加为 Team Context & Decisions 行。
• 未写入任何文件；每项检测到的 ChDR 类决策都附有 _Suggested capture: … → run /change-specify._ 一行（挖掘历史记录的信号需写明 /change-init）。