swain-design

规范管理

在执行任何会更改状态的操作之前，请检查是否存在活动会话：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null

如果 JSON 输出中的 "status" 不是 "active"，请告知操作者：“没有活动会话 — 要使用 /swain-init 启动一个吗？”如果对方忽略此提示，则继续操作。

此技能定义了规范的产物类型、阶段和层级。详细定义和模板位于 references/（相对于此技能目录）。如果宿主仓库中有 AGENTS.md，请使其中的产物部分与此技能的参考数据保持同步。

产物类型定义

每种产物类型都有一个定义文件（生命周期阶段、约定、文件夹结构）和一个模板（frontmatter 字段、文档骨架）。请阅读你要创建或转换的产物类型的定义。

类型	内容	定义	模板
产品愿景（VISION-NNN）	产品的顶层方向——目标、受众和成功指标，适用于竞争型或个人产品。	定义	模板
倡议（INITIATIVE-NNN）	愿景下史诗的战略分组——提供用于优先级排序和决策跟踪的中层容器。	定义	模板
用户旅程（JOURNEY-NNN）	端到端用户工作流，其中的痛点会推动史诗和规范的制定。	定义	模板
史诗（EPIC-NNN）	愿景或倡议下的大型交付项——汇集相关规范，并附有成功标准。	定义	模板
Agent 规范（SPEC-NNN）	带验收标准的技术实现规范。支持 type: feature | enhancement | bug。父级史诗为可选项。	定义	模板
研究 Spike（SPIKE-NNN）	有明确问题和完成门槛的限时调查。	定义	模板
Persona（PERSONA-NNN）	为用户创建的原型档案，为旅程和规范提供参考。	定义	模板
ADR（ADR-NNN）	单项架构决策——背景、选择、备选方案和后果（Nygard 格式）。	定义	模板
Runbook（RUNBOOK-NNN）	有明确触发条件的分步操作流程（由 Agent 执行或手动执行）。	定义	模板
设计（DESIGN-NNN）	常设设计文档，涵盖交互（UI/UX）、数据架构或系统契约。通过 domain: interaction | data | system frontmatter 字段选择领域。	定义	模板
培训文档（TRAIN-NNN）	结构化学习材料（操作指南、参考资料、快速入门），用于教用户使用某项功能或工作流。通过绑定提交的 linked-artifacts 与源产物同步跟踪，以检测过时内容。	定义	模板
杂项任务（CHORE-NNN）	轻量级清理工作——规模小、范围明确且可独立执行。不交付功能代码。	定义	模板

选择合适的工件类型

当用户的请求未指定具体类型时，请根据其意图推断：

用户意图	工件	关键词
产品方向、我们存在的理由	Vision	“产品方向”、“我们应该构建什么”、“北极星”
战略方向、将相关工作归组	Initiative	“聚焦于”、“安全工作”、“将这些 Epic 归组”、“战略性”、“跟踪”
发布一项功能或交付成果	Epic	“构建 X”、“添加 Y 功能”、“实现 Z”
一个实现单元	Spec	“修复这个”、“添加一个标志”、“重构”、“小改动”、“Bug”
小型清理工作	Chore	“清理”、“整理”、“移动文件”、“重新链接”、“小修复”
研究问题	Spike	“我们是否应该”、“调查”、“比较选项”、“最佳方式是什么”
记录一项决策	ADR	“已决定”、“在……之间选择”、“为什么我们……”
创建培训或文档	Train	“操作指南”、“教程”、“参考文档”、“入门指导”、“分步讲解”、“培训材料”、“教某人”

Initiative 与 Epic 的区别——关键区别：

• Initiative：包含多个交付成果的方向。“强化安全性”是一项 Initiative，涵盖扫描、门禁和策略。由操作人员引导。
• Epic：包含多个 Spec 的交付成果。“构建扫描工具”是一项 Epic，有明确的完成标准。由 Agent 执行。
• 经验法则：如果需要 2 个以上的 Epic 来描述这项工作，它就是 Initiative。如果需要 2 个以上的 Spec，它就是 Epic。如果只有一个 Spec，就直接创建该 Spec。

Initiative 下的 Spec（小型工作路径）——与某项 Initiative 的方向相关，但不足以构成 Epic 的 Bug、小型增强和杂项任务，可以通过 parent-initiative 直接附加到该 Initiative。如果小型工作形成聚类，请建议将其提升为 Epic。

更新工件元数据

当操作人员要求更新现有工件的字段时（例如，“将 VISION-001 的优先级设为 high”，“将 EPIC-017 重新设为 INITIATIVE-001 的子项”）：

1. 阅读工件的定义文件，确认字段名称和有效值
2. 直接编辑 frontmatter 字段（例如，priority-weight: high）
3. 更新 last-updated 日期
4. 运行 bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" build 以刷新图表缓存
5. 提交更改

常见更新：

• Vision、Initiative、Epic 和 Spec 上的 priority-weight——接受 high、medium 或 low。该值会逐级传递：Vision → Initiative（可覆盖）→ Epic（可覆盖）→ Spec（可覆盖）。会影响下游推荐评分以及 swain chart 中同级项的排序。
• Epic 和 Spec 上的 parent-initiative——将它们重新设为某项 Initiative 的子项。Spec 可以设置 parent-epic 或 parent-initiative，但不能同时设置两者。
• Initiative 上的 parent-vision——将其附加到某项 Vision。

当操作人员在 Vision 或 Initiative 的上下文中说“优先级”或“权重”时，指的是 frontmatter 字段 priority-weight。

创建工件

错误处理

当操作失败时（缺少父级、编号冲突、脚本错误等），请参阅 references/troubleshooting.md 中的恢复流程。不要自行变通——故障排除指南涵盖了已知的失败情况。

复杂度分级（SPEC-045）

在运行完整的编写流程之前，先将产物归入一个复杂度等级：

低复杂度（符合快速路径条件）：

• type: bug 或 type: fix 的 SPEC，且没有 parent-epic，也没有下游 depends-on 链接
• 没有 parent-epic 的 SPIKE
• 用户使用了“快速”“简单”“轻微”或“迅速”等表述的任何产物

中／高复杂度（完整流程）：

• 功能类 SPEC（type: feature）
• 任何带有 parent-epic 的 SPEC 或 SPIKE
• EPIC、INITIATIVE、愿景、旅程、ADR——始终采用完整流程
• 用户描述了重大架构决策的任何产物

符合快速路径条件时，输出：[fast-path] Skipped: specwatch scan, scope check, index update

工作流

1. 运行以下命令，确定此前缀可用的下一个编号：

   bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/next-artifact-id.sh" <PREFIX>
   

   该命令会扫描所有本地分支和工作树，以避免不同工作树会话之间发生 ID 冲突（SPEC-193）。如果脚本不可用，则改为扫描当前 HEAD 上的 docs/<type>/，但请注意，这样在工作树工作流中可能会发生冲突。
2. 对于 VISION 工件： 起草前，询问用户这是竞争性产品还是个人产品。答案决定应包含哪些模板章节，并影响后续的整个分解过程。有关各产品类型的详情，请参阅 vision 定义。 2a. 对于 DESIGN 工件： 首先询问此设计涵盖哪个领域：interaction（UI/UX — 屏幕、流程、状态）、data（数据架构 — 实体、架构、流程、不变量）或 system（系统契约 — API 边界、行为保证、集成接口）。如果不明确，默认使用 interaction。然后询问 Design Intent 的内容 — 背景（用一句话说明设计的目的）、目标（希望实现的体验或保证）、约束（可供审查的边界）以及非目标（明确决定不做的事项）。此章节为一次性内容：创建时确定，不会随着可变章节的演进而更新。使用 DESIGN 模板中的领域专属章节。
3. 从上方查找表中读取工件的定义文件和模板。
4. 在正确的阶段子目录中创建工件。如果阶段目录尚不存在，则使用 mkdir -p 创建。确切的目录结构请参阅定义文件。
5. 根据工件类型的要求填写 frontmatter 字段（参见模板）。将 authored-by 设为从系统提示中解析出的模型身份（例如 GLM-5.1）。如果创建工件时涉及子 Agent，请列出所有模型及其角色 — 例如，GLM-5.1 (supervisor), Kimi-K2.5 (subagent)。如果无法获取模型身份，则使用 AI Assistant 作为备用值。
6. 使用相应的阶段和当前日期初始化生命周期表，并遵循以下规则：
   • 用户要求 → Active：如果用户明确要求创建此工件（例如“关于 X 的新 SPIKE”“为 Y 编写规格说明”），则直接在 Active 阶段创建。用户已决定要开展这项工作 — Proposed 没有额外价值。
   • Agent 建议 → Proposed：如果 Agent 主动创建工件（例如，用户要求创建 EPIC 时建议创建一个 SPIKE，或将 Vision 分解为子 Epics），则在 Proposed 阶段创建。用户尚未明确同意 — Proposed 表示“这是我的建议，请确认”。
   • 会话中已充分编写 → 后续阶段：如果工件在对话期间已充分编写，也可以直接在后续阶段创建（参见跳过阶段）。 6.5. 为正文中未加链接的工件 ID 引用添加超链接 — 写完工件正文后，扫描结束的 --- frontmatter 分隔线下方的所有文本，查找符合 (SPEC|EPIC|INITIATIVE|VISION|SPIKE|ADR|PERSONA|RUNBOOK|DESIGN|JOURNEY|TRAIN|CHORE)-[0-9]+ 模式的未加链接的工件 ID 引用。对于每个符合以下条件的未加链接 ID：
   • 未包含在 Markdown 链接（[...](...)）中，并且
   • 未包含在代码围栏（``` 块）或行内代码（`反引号`）中， 使用以下方法进行解析：

   bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/resolve-artifact-link.sh" <ARTIFACT-ID> <SOURCE-FILE>
   

   将裸 ID 替换为 [ARTIFACT-ID](relative-path)。如果脚本返回非零退出码或输出为空（未找到工件），则保留裸 ID，不要使操作失败。Frontmatter 值必须保持为纯 ID（以兼容 YAML）；只有正文文本会添加超链接。
7. 验证父级引用是否存在（例如，新 Agent Spec 引用的 Epic 必须已存在）。 7.5. 同类型重叠检查 — （仅适用于常驻轨道类型：DESIGN、Persona、Runbook） 扫描 docs/<type>/Active/，查找同类型的现有 Active 工件。出现以下情况时标记为重叠：
   • 新工件的 linked-artifacts 引用了另一个同类型工件——这是直接取代的信号。
   • 新工件的作用范围章节（DESIGN 的 Interaction Surface、Runbook 的 Trigger、Persona 的 Role）描述的范围与现有 Active 工件重叠，或涵盖其范围。 如果检测到重叠，询问操作者：“此工件与 <EXISTING-ID>（<title>）重叠。新工件是否取代它？”如果是，则在同一操作中将现有工件转为 Superseded（设置 superseded-by、更新状态、移至 Superseded/ 目录并添加生命周期条目）。
8. ADR 合规检查 — 运行 bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/adr-check.sh" <artifact-path>。继续操作前，与用户一起审查所有发现。 8a. 对齐检查 — （快速通道层级跳过此项） 运行 bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" scope <artifact-id>，并根据 references/alignment-checking.md 进行评估。报告阻塞性发现（MISALIGNED）；对提示性发现（SCOPE_LEAK、GOAL_DRIFT）予以说明，但不将其作为操作的前置条件。向操作者展示范围链或祖先关系时，对每个节点使用 artifact-context.sh，同时显示通俗易懂的名称和 ID。如果不可用，则回退为仅显示裸 ID。 8b. 未锚定检查 — 验证父级引用后，检查新工件是否能通过父级边关联到 Vision。如果不能，则警告：⚠ No Vision ancestry — this artifact will appear as Unanchored in swain chart。提供关联到现有 Initiative 或 Epic 的选项。不要阻止创建。
9. 操作后扫描 — （快速通道层级跳过此项） 运行 bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/specwatch.sh" scan。现在此流程还会运行 design-check.sh。提交前修复所有过期引用或设计偏差问题。
10. 索引刷新步骤 — （快速通道层级跳过此项；在会话结束时通过 rebuild-index.sh 批量刷新） 更新 list-<type>.md（参见 索引维护）。

Superpowers 集成

安装 superpowers 后，以下链条为必需流程——必须调用相应技能，不得跳过或直接在当前步骤中完成工作：

1. **创建 Vision、Initiative 或 Persona 工件之前：**调用 brainstorming 技能进行苏格拉底式探索。传入工件背景（目标、受众、约束条件）。将头脑风暴的输出整理为 swain 工件格式，并添加正确的 frontmatter 和生命周期表。

2. **开始新功能工作时（头脑风暴 → 工件 → 实施）：**头脑风暴用于探索想法并生成设计文档。头脑风暴的最终步骤是调用 swain-design 创建正式工件（Epic + 规格）。然后，对于每个即将进入实施阶段的 SPEC，按规格调用 writing-plans。writing-plans 保存计划文件后，调用 swain-do 导入计划。链条为：头脑风暴 → swain-design → 按规格调用 writing-plans → swain-do。

2b. **已有 SPEC 即将进入实施阶段时（无需头脑风暴）：**根据 SPEC 的验收标准和范围调用 writing-plans。writing-plans 保存计划文件后，调用 swain-do 导入计划。

3. **从 Testing 转换为 Implemented 时：**调用 requesting-code-review，检查规格合规性和代码质量（如果有可用的审查技能）。

检测：ls .agents/skills/brainstorming/SKILL.md .claude/skills/brainstorming/SKILL.md 2>/dev/null——如果至少有一个路径存在，则表示 superpowers 可用。在本次会话中缓存检测结果。

阅读 references/superpowers-integration.md，了解精简 SPEC 格式和完整路由详情。所有集成都属于可选项——即使没有 superpowers，swain 也能完整运行。

阶段转换

阶段是路标，不是强制关卡——工件可以跳过阶段向前推进。阅读 references/phase-transitions.md，了解跳过阶段的规则、转换工作流（验证 → 移动 → 提交 → 哈希标记）、验证／审查关卡和完成规则。

Supersession specwatch-ignore 维护

任何工件转换为 Superseded 时——无论是通过阶段转换工作流（phase-transitions.md 中的步骤 5a），还是在创建工件时（检测到同类型重叠）——都要将 glob 模式追加到 .agents/specwatch-ignore，以排除因该 Supersession 产生的有意反向引用。这样可以避免 specwatch 将来源链接标记为警告。

1. 如果 .agents/specwatch-ignore 不存在，则创建它。
2. 追加以下路径的模式：(a) 被取代的工件路径，(b) 取代它的工件路径，(c) 同一操作中创建且引用了被取代工件的任何 ADR。
3. 每个条目都要添加注释：# <OLD-ID> superseded by <NEW-ID> (<YYYY-MM-DD>)。
4. 去重：跳过文件中已存在的模式。

# INITIATIVE-001 superseded by INITIATIVE-013 (2026-03-19)
docs/initiative/Superseded/(INITIATIVE-001)*
docs/initiative/Active/(INITIATIVE-013)*

此步骤在更新反向引用（步骤 5b）和运行 specwatch 扫描之前执行（创建工作流中的步骤 9，phase-transitions.md 中的步骤 8），以确保扫描结果干净。

被取代后的反向引用更新

完成 specwatch-ignore 维护（步骤 5a）后，更新 frontmatter 中引用了被取代工件的所有非终态工件（linked-artifacts、depends-on-artifacts、addresses）。完整流程请参见 phase-transitions.md 中的步骤 5b。要点如下：

• 更新前检查是否一致 — 取代通常会改变范围。阅读引用工件的上下文，并与后继工件进行比较。如果这种关联不适用于后继工件，请标记给操作人员，而不是默默地改指向。
• 去重 — 如果列表中已包含后继工件，请移除旧条目，而不是添加重复项。
• 提交消息溯源 — 记录变更内容（例如，“update EPIC-031 linked-artifacts: INITIATIVE-001 → INITIATIVE-013”），以便 git 历史保留原始引用。
• 取代工件自身的溯源链接指向 specwatch-ignore，不要改写。

DESIGN 生命周期钩子

这些钩子适用于阶段转换期间的 DESIGN 工件：

创建 DESIGN 时：

• 验证所有 sourcecode-refs 路径在 HEAD 上均存在（如果其中有已填入的路径）。在完成创建前，对失效路径发出警告。

从 Proposed 转换为 Active 时：

• 对 DESIGN 运行 design-check.sh — 所有引用都必须为 CURRENT。
• 如果有任何引用为 STALE 或 BROKEN，在完成转换前警告操作人员。不要默默地带着过时的引用继续操作。

从 Active 转换为 Superseded 时：

• 新的（取代旧 DESIGN 的）DESIGN 应继承旧 DESIGN 的 sourcecode-refs，并通过 --repin 更新为新的固定版本。

决策保护钩子

这些钩子属于 Agent 级行为指引 — 不由脚本强制执行，而由遵循此技能文件的 Agent 执行。

SPEC 转入 Implementation： 当 SPEC 转入 Implementation，且关联了 DESIGN（通过任一方的 linked-artifacts 或 artifact-refs）时：

• 展示 DESIGN 的设计意图部分（目标、约束、非目标），以便了解一致性。将其呈现给操作人员，确保实现不超出设计边界。

SPEC 完成： 当 SPEC 完成，且其实现修改了 DESIGN 的 sourcecode-refs 所跟踪的文件时：

• 将变更文件（来自 SPEC 的提交）与活跃 DESIGN 的 sourcecode-refs 进行交叉比对。
• 如果发现重叠：提醒操作人员更新 DESIGN，并通过 design-check.sh --repin 重新固定版本。

一致性逐级检查： 当 Epic 的 artifact-refs 中有指向 DESIGN 且 rel: [aligned] 的条目时：

• 创建或修改子 SPEC 时，根据 DESIGN 的约束和非目标检查范围。
• 遍历路径：SPEC → 父级 EPIC → 带有 rel: [aligned] 的 artifact-refs → DESIGN → 设计意图。
• 只报告违规情况 — 对齐的 SPEC 不作提示。

设计与代码的偏移： 当 DESIGN 的可变部分发生修改，但 sourcecode-refs 的 blob 未发生变化时：

• 提示：“DESIGN-NNN 已演进，但跟踪的代码尚未跟上。”提醒操作人员进行核对和协调。

偏移解决（SPEC-307）

创建、编辑 SPEC 或转换其阶段时 — 如果 SPEC 有父级（EPIC、Initiative 或 Vision）— 执行偏移解决。阅读 SPEC 和父级。如果 SPEC 的范围、验收标准或约束偏离父级的目标或成功标准，则采取修正措施：重新使子级对齐（编辑 SPEC），或更新父级。

修正方向依据信号和内容判断：统计此前针对该父级作出的偏移决策数量（越多意味着父级可能已过时），并评估哪个方向能带来更好的结果。应用修正后，将结果呈现给操作人员审核：接受、修改或还原。所有结果都通过 swain-session-state.sh record-decision 记录为偏移决策。

README 更新提醒

将 Vision、Design、Journey 或 Persona 转入新阶段时，如果此次转换会改变项目面向公众的表述，则发出轻量提醒：

README.md 可能需要更新，以反映此变更。

这只是提示，不会阻止操作——操作者可以忽略。

触发条件——以下情况应发出提醒：

• Vision 转入 Active（新方向）或 Abandoned（放弃的方向）
• Design 转入 Active（新的交互模型、数据架构或系统契约）或 Superseded（被替代）
• Journey 转入 Active（新的用户流程）或 Abandoned（弃用的路径）
• Persona 转入 Active（新的受众群体）或 Abandoned（放弃的受众群体）

头脑风暴上下文——如果项目有 README 但没有制品，或制品树较单薄（Active Vision、Design、Journey 或 Persona 的总数少于 3 个），则在项目中运行 brainstorming skill 时，应以 README 作为苏格拉底式探索的起点。README 中的主张、受众和行为描述将为头脑风暴对话提供起点，而不是从零开始。

头脑风暴上下文的检测方式：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
ACTIVE_COUNT=$(find "$REPO_ROOT/docs" -path "*/Active/*" -name "*.md" 2>/dev/null | grep -cE "(VISION|DESIGN|JOURNEY|PERSONA)" || echo "0")
HAS_README=$( [ -f "$REPO_ROOT/README.md" ] && echo "yes" || echo "no" )

如果 HAS_README=yes 且 ACTIVE_COUNT < 3，则将 README 内容作为主要上下文传递给头脑风暴。

Trove 集成

在研究阶段转换期间（Spike Proposed -> Active、ADR Proposed -> Active、创建 Vision/Epic），检查是否存在现有 trove，并提出关联或创建 trove。完整的 hook、trove 扫描和反向链接维护流程，请阅读 references/trove-integration.md。

执行跟踪交接

开始实施 SPEC 时，调用 swain-do。有关四级跟踪模型、swain-do: required frontmatter 字段、意图触发条件和协调制品拆解，请阅读 references/execution-tracking-handoff.md。

GitHub Issues 集成

SPEC 通过 source-issue frontmatter 字段关联到 GitHub Issues。在关联 SPEC 的阶段转换期间，发布评论或关闭 issue。有关晋升工作流、转换 hook 和后端抽象，请阅读 references/github-issues-integration.md。

状态概览

对于项目整体状态、进展或“下一步做什么？”等查询，请转交 swain-session skill（它会汇总 swain chart、tk、git 和 GitHub issues）。对于特定制品的图查询，请使用 bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh"——参见 references/specgraph-guide.md。默认输出为以 Vision 为根节点的层级树；不同的决策场景可使用各种视图（ready、recommend、debt、unanchored 等）筛选和标注该树。

审计制品

用户要求审计时，请阅读 references/auditing.md，了解完整的两阶段流程（预扫描 + 并行审计 Agent，包括 ADR 合规性检查）。还应执行 未锚定检查：运行 bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" unanchored，并将所有没有 Vision 祖先的制品作为领域级发现，与对齐和 ADR 合规性结果一并报告。

实施计划

实施计划衔接声明式规格与执行跟踪。开始实施时，请阅读 references/implementation-plans.md，了解 TDD 方法、superpowers 集成、计划工作流和备用流程。

场景建模

场景建模是通过 git 分支进行的定点影响分析。操作人员提出问题；Agent 负责所有操作。操作人员不会接触 git。

目标是在磁盘上进行实际编辑，以便 git diff 显示影响——变更的制品、调整的路线图和代码引用。操作人员唯一需要做的就是审查影响，并说“接受”或“拒绝”。

这是 swain-design 中纯粹由大模型执行的流程。不需要单独的技能、脚本或新的 CLI 标志。

触发短语

当操作人员说出以下任一内容时，启动场景建模：

• “如果 ADR-X 处于 Active 状态会怎样”
• “如果我们当初选择了 Y 而不是 Z 会怎样”
• “比较在不同 ADR 假设下的树”
• “场景：<描述>”
• “显示从 A 切换到 B 的影响”

流程

1. 确认意图。 简短地向操作人员确认反事实假设：“你想看看如果 ADR-046 的状态是 Active 而不是 Superseded，制品树会是什么样吗？”

2. 创建分支。

   git checkout -b scenario/<kebab-case-name>
   

   根据问题推导分支名称（例如，scenario/adr-046-active、scenario/pre-helm-refactor）。

3. 确定编辑范围。 从指定的 ADR 或决策沿着取代关系图进行遍历。对于每个受状态切换影响的制品，追踪：

   • 取代它的制品（也需要切换状态）。
   • 与 ADR 配对的设计（例如，ADR-048 ↔ DESIGN-033）。
   • 在 linked-artifacts、depends-on-artifacts 或 addresses 数组中引用了状态切换制品的计划和史诗路线图。

   使用 swain chart 输出和图缓存解析引用。

4. 应用编辑。 在场景分支上编辑 frontmatter：

   • 切换主要 ADR 及其配对设计的 status。
   • 更新计划／史诗 frontmatter 数组中的反向引用（linked-artifacts 等）。
   • 不要编辑正文——仅编辑 frontmatter 字段。
   • 不要创建或删除制品文件。

5. 验证。 在分支上运行 swain chart。确认树能够解析，且没有损坏的引用。向操作人员展示替代树。

6. 呈现影响。 运行并总结：

   git diff trunk...HEAD --stat
   git diff trunk...HEAD -- docs/ | grep -oP 'sourcecode-refs:\K[^\n]+'
   

   向操作人员展示：变更的制品数量、发生调整的计划／史诗路线图，以及引用的源代码路径。

7. 提供操作选项：

   • 接受： 合并到主干并提交。
   • 并排比较： 添加一个主干 worktree，在两个 worktree 中运行 swain chart，并展示差异。
   • 拒绝： 删除分支。

操作人员反馈循环

如果操作人员说“也切换 DESIGN-034”或“不要动 INITIATIVE-005”，则调整编辑范围并重新验证。迭代通过对话进行——操作人员引导，Agent 执行。

清理

Agent 负责处理两种结果：

• 接受： git checkout trunk && git merge scenario/<name>，提交并推送。
• 拒绝： git branch -D scenario/<name>。

示例

操作人员：“如果 ADR-046 当初被保留会怎样？”

1. 创建分支：git checkout -b scenario/adr-046-active
2. 编辑范围：将 ADR-046 切换为 Active，将 ADR-048 切换为 Superseded，将 DESIGN-032 切换为 Active，将 DESIGN-033 切换为 Superseded。更新 INITIATIVE-018 路线图，将 DESIGN-033 替换为 DESIGN-032。
3. 验证：swain chart — 通过。
4. 影响：变更了 4 个制品，调整了 1 个计划路线图，引用了 2 个源代码路径。

---

参考资料

当工作流步骤引用以下文件时，请查阅：

• 制品关系： references/relationship-model.md — 类型层次结构和交叉引用的 ER 图
• 生命周期表格格式： references/lifecycle-format.md — 提交哈希标记约定
• 索引维护： references/index-maintenance.md — list-<type>.md 刷新规则
• 工具： 脚本位于 scripts/（相对于此技能目录）。详情请参阅 references/specwatch-guide.md、references/specgraph-guide.md 和 references/adr-check-guide.md。

会话书签

状态更改操作完成后，更新书签：bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/swain-bookmark.sh" "<action> <artifact-ids>" --files <paths>