propagate-design-change

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,automation_always_ask,workflow,system_overrides

已在上方解析 — 按原样使用；本次运行中，--review 会覆盖 review_mode。没有拦截规则 → 使用 .claude/docs/config-resolution.md 中的默认值。

使用提问工具提问。若没有提问工具，请为选项编号并列出，然后结束本轮，等待回复。跳过或关闭问题不算作答：请用纯文本重新提问。

传播设计变更

GDD 变更后，基于它做出的架构决策可能不再成立。此技能会找出受变更影响的每份 ADR，将 ADR 中的假设与 GDD 当前内容进行比较，并逐一引导用户审查。

示例： /propagate-design-change design/gdd/combat-system.md

提问遵循 .claude/docs/automation-modes.md（协作模式始终提问，引导模式在重大选择时提问，自主模式则记录并继续；automation_always_ask 类别始终提问：此处的 ADR 影响属于 schema_changes 和 architecture_decisions）。

层级。 使用已变更 GDD 所属系统的 workflow：若有 system_overrides 条目，则使用该条目；否则使用项目级设置。设为 minimal 的系统即使项目为 standard，也不会有 ADR。full 会检查所有 ADR；standard 会检查关键的（Foundation 层）ADR，以及所有提及已变更 GDD 的 ADR；minimal 无需检查（第 4 阶段）。

第 1 阶段：GDD 路径

在技能名称后输入的文本（去掉任何 --review <mode> 参数对）就是已变更的 GDD。此项必填。缺少时显示：“用法：/propagate-design-change design/gdd/[system].md — 请提供已变更 GDD 的路径。”路径不是文件时显示：“[path] 不存在。请检查路径后重试。”

第 2 阶段：变更内容

使用 git 查询，绝不要凭肉眼比较两份完整文档：

git diff HEAD -- design/gdd/[filename].md

若结果为空：变更可能已经提交，因此将范围扩大到上一次修改该文件的提交：git diff HEAD~1 HEAD -- design/gdd/[filename].md。

• 完全没有历史记录（git log --oneline -1 -- design/gdd/[filename].md 没有输出）：“git 中没有旧版本 — 这是新的 GDD，而非修订版。无需传播。”停止。
• 有历史记录，但两次 diff 都为空：报告“[file] 没有未提交或最近一次提交中的变更”，并询问要传播哪个修订版本。diff 为空只表示此处没有变更，并不表示没有内容受影响。

根据代码块：@@ 标头会标明每项变更所在的章节，因此变更章节列表应直接来自 diff。没有代码块的章节按定义未发生变更。只有在无法单独理解代码块时，才阅读相关章节的上下文（例如，某个数值的含义取决于它上方的规则）；并且只阅读该章节：bash .claude/scripts/md-section.sh extract design/gdd/[file].md "[Section]"。

第 3 阶段：变更摘要

## Change Summary: [GDD filename]
Date of revision: [today]

Changed sections:
- [Section]: [what changed — new rule, removed rule, formula modified, …]

Unchanged sections:
- [Section]

Key changes affecting architecture:
- [change likely to affect ADRs]

引用这些事实的其他 GDD。 如果 design/registry/entities.yaml 不存在或没有条目（在 /design-system 填充前，它只是一个空占位文件），则跳过此步骤；下方的 ADR 检查仍会执行。否则，该文件会记录哪些 GDD 依赖此系统的事实：搜索其中的 source: design/gdd/[filename]。对于此 GDD 所属的每个实体、常量或公式，如果其值被 diff 修改，则其 referenced_by: 列表会列出现在可能与之不一致的 GDD。将它们列在“需要重新检查的下游 GDD”下。

第 4 阶段：范围内的 ADR

bash .claude/scripts/adr-status.sh 会列出每个 ADR 的状态、层级和缺失章节。

• full： 每个 ADR。
• standard： 关键 ADR（layer 列显示 Foundation 或没有层级：有疑问时按关键 ADR 处理），以及任何提及已更改 GDD 的 ADR。
• minimal： 报告「minimal 工作流不进行 ADR 检查——已记录设计变更；不进行架构影响分析。」停止。

先确定分母：数量为 N。若 N 为 0：「在 docs/architecture/ 中未找到 ADR——无需检查。」停止。

哪些 ADR 引用了此 GDD。 无需通读整个 ADR：

1. 检查每个 ADR 的 GDD Requirements Addressed 章节 （bash .claude/scripts/md-section.sh extract <adr> "GDD Requirements Addressed"）， 找出提及已更改 GDD 的行；
2. 搜索 ADR 中已更改 GDD 的文件名，找出在表格行之外的正文中引用它的 ADR。

两者的并集即为受影响集合 M。

结果	含义	操作
M ≥ 1	正常。	继续。其余 N − M 个 ADR 不在本次检查范围内：切勿将它们描述为已验证且未受影响。
M = 0，且每个范围内的 ADR 都缺少 GDD Requirements Addressed（missing 列）	无法计算可追溯性。	「找到 [N] 个 ADR，但都没有 'GDD Requirements Addressed' 章节——无法计算可追溯性（这是预生产门禁阻断项）。运行 /architecture-decision retrofit [adr]。」停止。
M = 0，这些章节均存在	没有 ADR 引用此 GDD。	「没有 ADR 引用 [gdd]——无架构影响。」停止。

若 docs/architecture/requirements-traceability.md 存在，请阅读。

报告：「已检查 [N] 个 ADR。[M] 个引用 [gdd filename]（[X] 个出现在需求表中，[Y] 个仅出现在正文中）。」

第 5 阶段：影响分析

对 M 中的每个 ADR，使用 md-section.sh extract 阅读其 Context、Decision 和 Consequences 章节：判断决策是否仍然成立需要依据其推理，不能只看表格行。然后，对每个 ADR 列出的、来自已更改 GDD 的需求：

1. 当前 GDD 中是否仍有此需求？
2. 编写 ADR 时 GDD 的内容是什么？现在的内容又是什么？
3. 该决策是否仍然成立？

对每个 ADR 分类：

状态	含义
✅ 仍然有效	此变更未涉及该 ADR 所作的决策
⚠️ 需要审查	此变更可能产生影响；需要人工判断
🔴 很可能已被取代	此变更与该 ADR 的假设相矛盾

### ADR-NNNN: [title]
Status: [Still Valid | Needs Review | Likely Superseded]

What the ADR assumed about this GDD:
  "[quote from its GDD Requirements Addressed or Context]"

What the GDD now says:
  "[quote from the current GDD]"

Assessment:
  [whether the decision still holds, and why]

Recommended action:
  [Keep as-is | Review and update | Mark Superseded and write a new ADR]

阶段 6：影响报告，然后审核

在询问用户要采取什么操作之前，先展示完整报告：

## Design Change Impact Report
GDD: [filename]
Date: [today]
Changes detected: [N sections changed]
ADRs referencing this GDD: [M]

### Not Affected
[ADRs whose decisions still hold]

### Needs Review ([count])
[ADRs that may need updating]

### Likely Superseded ([count])
[ADRs whose assumptions the change contradicts]

技术审核。 阅读上方的 review_gate 行。skill-gates=skip （个人或精简模式）：不调用 Agent；注明 TD-CHANGE-IMPACT skipped — [Solo | Lean] mode。 skill-gates=run：将审核交给 technical-director Agent，并使用审核门槛 TD-CHANGE-IMPACT（.claude/docs/director-gates/td-change-impact.md；Agent 会自行读取该文件）。审核说明：

• 目标： 在用户采取行动前检查影响报告。
• 提供内容： 上方的完整报告：变更摘要、每项受影响的 ADR 及其分类和建议操作。
• 检查： 没有对 ADR 的影响程度评估过低；建议操作合理；没有遗漏对其他 ADR 或系统的连带影响。
• 返回： APPROVE、CONCERNS、REJECT，或指出缺失输入的 NOT ASSESSED。
• 边界： 不得编辑任何文件。

根据审核结果采取操作：

• APPROVE： 进入阶段 7。
• CONCERNS： 显示被标记的 ADR 或操作，并询问：“你想怎么继续？”选项：修订影响评估 / 接受并记录上述顾虑 / 进一步讨论。
• REJECT： 不得进入阶段 7；先重新分析影响。
• NOT ASSESSED： 这不代表审核通过（.claude/docs/director-gates.md）。指出缺少的内容，然后补上并重新审核；或者，如果用户选择在缺少该内容的情况下继续，则进入阶段 7，并在报告和最终结果行中注明 TD-CHANGE-IMPACT: NOT ASSESSED — [input]。

阶段 7：逐一解决 ADR

对于每个标记为 Needs Review 或 Likely Superseded 的 ADR，逐一询问：“ADR-NNNN （[title]）— [status]。你想怎么处理？”选项：

• 将其标记为 Superseded（我来编写新的 ADR）
• 就地更新（小幅修订）：注明要修订的内容；由用户编辑
• 保持原样（此次变更不影响此决策）
• 暂时跳过（稍后再处理）

标记为 Superseded。 询问“我可以将 [ADR file] 的 Status 设为 Superseded 吗？”用户同意后， 仅替换其 ## Status 部分的正文：

bash .claude/scripts/md-section.sh replace docs/architecture/[adr-file].md "Status" <<'EOF'
Superseded — replacement pending (see docs/architecture/change-impact-[date]-[system-slug].md)
EOF

这是此技能唯一会写入的内容。adr-status.sh 会将其识别为 Superseded，因此 /dev-story 和 /create-stories 会拦截仍指向该 ADR 的故事。新 ADR 编写完成后，会记录其替代的 ADR。不要更改 ADR 中的任何其他内容：其余内容保持不变。

阶段 8：可追溯性索引

如果 docs/architecture/requirements-traceability.md 存在，询问“我可以将已变更的需求添加到可追溯性索引中吗？”用户同意后，为每项已变更的需求添加一行：

## Superseded Requirements
| Date | GDD | Requirement | Changed To | ADRs Affected | Resolution |
|------|-----|-------------|------------|---------------|------------|
| [date] | [gdd] | [old requirement text] | [new requirement text] | ADR-NNNN | [Superseded/Updated/Valid] |

阶段 9：变更影响文档

询问“我可以将变更影响报告写入 docs/architecture/change-impact-[date]-[system-slug].md 吗？”其中包含变更摘要、影响分析、每项 ADR 所选择的处理方式，以及需要编写或更新的 ADR。

阶段 10：后续步骤

根据处理结果：

• 标记为 Superseded 的 ADR：“运行 /architecture-decision [title] 编写替代 ADR，然后再次运行 /propagate-design-change 检查覆盖情况。”
• 需要就地更新的 ADR：列出每项 ADR 中需要更改的字段。
• 受影响的 ADR 较多：“更新完成后运行 /architecture-review，检查可追溯性矩阵是否仍然完整。”

阶段 9 写入完成后，以 Verdict: COMPLETE — change impact report saved 结束；用户拒绝写入时，以 Verdict: BLOCKED — user declined the write 结束。