swain-retro

回顾

继续之前，请检查是否存在活动会话，并确定要使用哪个证据来源：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
session_check=$(bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null)
session_status=$(echo "$session_check" | jq -r '.status // "none"')

if [ "$session_status" = "active" ]; then
  echo "Using active session evidence"
else
  echo "No active session — falling back to git log evidence"
  git_evidence=$(git log --oneline -20 2>/dev/null)
  echo "Recent commits:"
  echo "$git_evidence"
fi

如果没有活动会话，请以 git log 为主要证据来源继续进行回顾。请在 docs/swain-retro/ 中创建独立的回顾文档，而不是将内容嵌入某个工件。请根据未限定范围的上下文调整反思问题。

在自然完成节点捕获经验教训，并将其保存以供将来使用。此技能既可自动触发（swain-design 中的 EPIC 终止状态转换钩子），也可通过 /swain-retro 手动调用。

输出模式

范围	输出	原因
EPIC 范围内（自动或显式）	在 EPIC 工件末尾追加 ## Retrospective 部分	EPIC 已包含生命周期、成功标准和子规格——它是“我们交付了什么以及学到了什么”的唯一事实来源
跨 EPIC / 按时间范围（手动）	在 docs/swain-retro/ 中创建独立的回顾文档	没有单一工件涵盖此范围——因此需要专门的文档

调用模式

模式	触发条件	上下文来源	输出	是否交互？
自动	EPIC 转换为终止状态（由 swain-design 调用）	EPIC 及其子工件	嵌入 EPIC	否——完全自动
交互式	实时会话中 EPIC 转换为终止状态	EPIC 及其子工件	嵌入 EPIC	是——提供反思问题
手动	用户运行 /swain-retro 或 /swain retro	近期工作——git log、已关闭任务、已转换状态的工件	独立回顾文档（必需）	是
限定范围	/swain-retro EPIC-NNN 或 /swain-retro SPEC-NNN	特定工件及相关工作	嵌入 EPIC（若为 EPIC 范围内）或独立文档	是

终止状态指会触发自动回顾的状态：Complete、Abandoned、Superseded。回顾内容会根据终止状态调整——对于已放弃的 EPIC，回顾重点是工作停止的原因和所得经验，而非成功标准。

步骤 1 — 收集上下文

收集工作期间发生情况的证据。

EPIC 范围内的回顾（自动或限定范围）

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
# Get the EPIC and its children
bash "$REPO_ROOT/.agents/bin/chart.sh" deps <EPIC-ID>

# Session log — the primary evidence source for retros (ADR-015)
# Contains decisions, pivots, rationale, and operator feedback
cat .agents/session.json 2>/dev/null | grep -i "<EPIC-ID>\|<SPEC-IDs>"

还需阅读：

• EPIC 的生命周期表（日期、持续时间）
• 子 SPEC 的验证表（已验证的内容）
• 工作期间创建的任何 ADR
• EPIC 激活日期至完成日期之间的 Git 日志

注意（ADR-015）： 不要将工单（tk / .tickets/）用作回顾证据。工单是临时的执行辅助材料——它们记录任务状态，而不是决策或理由。会话日志（.agents/session.json JSONL）记录了实际对话：尝试了什么、发生了哪些转向、原因是什么，以及操作人员说了什么。请根据会话日志和 Git 历史构建回顾内容。

手动（未限定范围）回顾

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
# Recent git activity
git log --oneline --since="1 week ago" --no-merges

# Session log — primary evidence source (ADR-015)
cat .agents/session.json 2>/dev/null | tail -100

# Recently transitioned artifacts
bash "$REPO_ROOT/.agents/bin/chart.sh" status 2>/dev/null

还需检查：

• 现有记忆文件，了解以往模式的背景
• docs/swain-retro/ 中之前的回顾文档，查找反复出现的主题

步骤 2 — 生成或引导反思

自动模式（非交互式）

当 swain-design 在非交互式 EPIC 终止状态转换期间调用时（例如，分派 Agent、批处理），请根据收集到的上下文自动生成回顾内容：

1. 综合总结已完成的工作、相较于原始范围的变化，以及提交记录／任务历史中显现的模式
2. 对于状态为 Abandoned 或 Superseded 的 EPIC，重点说明工作停止的原因和所得经验
3. 直接进入步骤 3（提取记忆）和步骤 4（写入输出）

交互模式

用户在场时（实时会话、手动调用），请先展示摘要并提供反思环节：

摘要格式

回顾范围： {EPIC-NNN 标题 / “近期工作”} 时段： {开始日期} — {结束日期} 已完成的工件： {列表} 已关闭的任务： {数量} 关键提交： {重要提交}

反思问题

每次只提一个问题，每个问题之间等待用户回答：

1. 哪些进展顺利？ 哪些模式或方法行之有效，值得重复采用？
2. 有哪些意外？ 是否遇到了意料之外的阻碍、捷径或范围变更？
3. 你会做哪些调整？ 如果可以重做这项工作，你会有哪些不同的做法？
4. 出现了哪些模式？ 各项任务中是否反复出现某些主题，例如工具摩擦、设计缺口或沟通模式？

根据用户的回答调整后续问题。如果用户回答简短，就深入追问；如果回答详尽，就继续下一个问题。

第 3 步 — 提炼经验

反思对话结束后，保存总结出的经验——但保存位置取决于当前项目是 swain 本身，还是使用 swain 的消费项目。

判断上下文

# Check if the current repo IS swain (the tool itself)
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
if git remote get-url origin 2>/dev/null | grep -q "cristoslc/swain"; then
  echo "SWAIN_REPO"
else
  echo "CONSUMER_PROJECT"
fi

在消费项目中：写入记忆

消费项目的经验应写入 Claude 记忆文件，因为这些经验体现了操作人员的偏好和项目特定模式，应在后续会话中保留。

反馈记忆

对于应指导 Agent 后续行为的行为模式和流程经验：

---
name: retro-{topic}
description: {one-line description of the learning}
type: feedback
---

{The pattern or rule}

**Why:** {User's explanation from the retro}
**How to apply:** {When this guidance kicks in}

写入项目记忆目录：

~/.claude/projects/<project-slug>/memory/feedback_retro_{topic}.md

项目 slug 是将项目路径中的斜杠替换为短横线后得到的字符串（例如，/Users/cristos/Documents/code/myapp → -Users-cristos-Documents-code-myapp）。这些文件存储在 Claude 的记忆系统中（而非 swain 的 .agents/ 状态中）；这是有意为之——回顾总结的经验会在该项目的所有 Claude Code 会话中保留。

更新 MEMORY.md 索引。

项目记忆

对于有关持续工作模式、团队动态或项目特定经验的上下文：

---
name: retro-{topic}
description: {one-line description}
type: project
---

{The fact or observation}

**Why:** {Context from the retro}
**How to apply:** {How this shapes future suggestions}

创建记忆的规则

• 仅创建用户在反思过程中明确确认过的记忆
• 如果新的经验拓展了已有模式，则与现有记忆合并
• 使用绝对日期（来自回顾总结的上下文），而非相对日期
• 每次回顾最多创建 3–5 个记忆文件——提炼内容，不要一股脑塞进去

在 swain 仓库中：提出制品，不写入记忆

如果回顾总结是在 swain 本身中进行的，那么意味着行为变更、新能力或流程修复的经验不是记忆，而是工作项。swain 的行为由技能、规范和 ADR 编码，而不是由操作人员记忆文件编码。

对每条经验分类，并将其导向相应的输出：

经验类型	去向	示例
某项技能需要新增行为或防护措施	SPEC 候选项——添加到回顾文档的「SPEC candidates」章节	「swain-release 应拒绝在工作树中运行」
需要跨领域的流程变更	ADR 候选项——记入回顾文档	「派发的 Agent 绝不能使用 reset --hard」
一项新能力或计划	EPIC 候选项——记入回顾文档	「会话日志需要按命令进行取证」
现有技能中的错误	通过 gh issue create 创建 GitHub issue	「swain-sync 无法保留符号链接」
操作人员偏好或项目上下文	记忆（与消费项目相同）	「操作人员更倾向于将重构内容合并到一个 PR 中」

对于制品候选项，在回顾文档输出中添加 ## SPEC candidates 章节（或 ## ADR candidates、## EPIC candidates 章节）。每条内容都应包含足够的上下文，以便之后起草相应制品：

## SPEC candidates

1. **{Title}** — {one-line description of what needs to change and why}
2. ...

回顾总结期间不要创建规范/史诗/ADR——这是 swain-design 的工作。回顾总结记录的是经验；由操作人员决定接下来要构建什么。仅当经验确实涉及操作人员偏好或项目上下文时才写入记忆（即上表的最后一行）。

第 4 步 — 写入输出

输出目标取决于范围——请参阅顶部的输出模式。

EPIC 范围：嵌入 EPIC 制品

在 EPIC Markdown 文件中、## Lifecycle 表格之前，追加一个 ## Retrospective 章节。这样可以让 EPIC 成为唯一事实来源。

## Retrospective

**Terminal state:** {Complete | Abandoned | Superseded}
**Period:** {activation date} — {terminal date}
**Related artifacts:** {SPEC-NNN}, {SPEC-NNN}, ...

### Summary

{What was accomplished — or for Abandoned/Superseded, what was learned and why work stopped}

### Reflection

{Synthesized findings — from auto-generation or interactive Q&A}

### Learnings captured



| Item | Type | Summary |
|------|------|---------|
| ... | memory / SPEC candidate / issue | ... |

按照第 4.5 步，为「Related artifacts」中的制品 ID 添加超链接。

跨 Epic／基于时间：独立复盘文档（必需）

对于未限定在单个 EPIC 范围内的手动复盘，必须使用独立文档——没有单个工件涵盖其范围。

mkdir -p docs/swain-retro

文件：docs/swain-retro/YYYY-MM-DD-{topic-slug}.md

---
title: "Retro: {title}"
artifact: RETRO-{YYYY-MM-DD}-{topic-slug}
track: standing
status: Active
created: {YYYY-MM-DD}
last-updated: {YYYY-MM-DD}
scope: "{description of what's covered}"
period: "{start} — {end}"
linked-artifacts:
  - {ARTIFACT-ID-1}
  - {ARTIFACT-ID-2}
---

# Retro: {title}

## Summary

{Brief description of what was completed across the scope}

## Artifacts

| Artifact | Title | Outcome |
|----------|-------|---------|
| ... | ... | Complete/Abandoned/... |

## Reflection

### What went well
{User's responses, synthesized}

### What was surprising
{User's responses, synthesized}

### What would change
{User's responses, synthesized}

### Patterns observed
{User's responses, synthesized}

## Learnings captured



| Item | Type | Summary |
|------|------|---------|
| ... | memory / SPEC candidate / issue | ... |

步骤 4.5 — 为工件引用添加超链接

写完复盘内容（独立文档或嵌入的 EPIC 章节）后，扫描正文中的所有裸工件 ID 引用，匹配 (SPEC|EPIC|INITIATIVE|VISION|SPIKE|ADR|PERSONA|RUNBOOK|DESIGN|JOURNEY|TRAIN)-[0-9]+。对于尚未位于 Markdown 链接或代码围栏中的每个裸 ID，解析并替换：

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

将裸 ID 替换为 [ARTIFACT-ID](relative-path)。如果脚本返回非零值或输出为空（未找到工件），则保留裸 ID。Frontmatter 中的 related-artifacts 值保持为纯 ID（确保 YAML 兼容性）。

带上下文的工件引用

在复盘内容中引用工件（子规格、相关工件、关联工作）时，使用上下文行：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/artifact-context.sh" <ID> 2>/dev/null

如果该工具不可用，则使用 <ID> — <title>。

步骤 4.7 — README 偏差检查（SPEC-210）

反思完成后、结束复盘前，检查 README 是否仍与项目一致。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
[ -f "$REPO_ROOT/README.md" ] && echo "has_readme" || echo "no_readme"

如果 README.md 存在：

1. 阅读 README.md，并提取有关项目用途和运作方式的描述。
2. 将这些描述与复盘范围内发生变更的工件进行比较（参见步骤 1 中的上下文）。
3. 列出偏差发现：
   • README 未提及的新功能 — Epic 已交付某项功能，但 README 未提及。
   • 过时的承诺 — Epic 删除或替换了 README 仍在描述的内容。
   • 行为变更 — Epic 改变了某项功能的运作方式，但 README 仍展示旧方式。

向操作人员展示发现。他们可以修正 README、修正工件，或推迟处理。

在自动模式下，将偏差发现添加到 ## Reflection 章节。在交互模式下，在反思问题之后、写入输出之前展示。

如果没有偏差，则跳过——不要添加“没有偏差”的说明。

推迟处理的发现应放在复盘内容的 ### README drift 子章节中，以便持续可见。

步骤 5 — 更新会话书签

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-bookmark.sh" "Completed retro for {scope} — {N} learnings captured"

与 swain-design 的集成

当 EPIC 转入任何终止状态（Complete、Abandoned、Superseded）时，swain-design 会编排此技能：

1. swain-design 完成阶段转换（移动、状态更新、提交、哈希标记）
2. swain-design 使用 EPIC ID 和终止状态调用 swain-retro
3. swain-retro 收集上下文、生成／提示反思、提取记忆，并将 ## Retrospective 章节嵌入 EPIC
4. swain-design 将复盘内容作为转换的一部分（或紧接转换之后）提交

交互检测： 如果会话为交互式（用户在场并作出回应），swain-retro 会提供反思问题。如果为非交互式（已调度的 Agent、批处理），则会全自动运行。

这是尽力而为的流程——如果 swain-retro 不可用，EPIC 转换仍会成功，只是不包含复盘章节。

引用之前的复盘

进行新的复盘时，同时扫描 EPIC 工件（搜索 ## Retrospective 章节）和 docs/swain-retro/ 中的既有复盘。如果多个复盘中反复出现相同模式，请明确指出——反复出现的主题是最有价值的经验。

# Check standalone retro docs
ls docs/swain-retro/*.md 2>/dev/null | head -10

# Check embedded retros in EPICs
grep -rl "## Retrospective" docs/epic/ 2>/dev/null | head -10