swain-retro
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese<!-- swain-model-hint: sonnet, effort: medium -->
<!-- swain-model-hint: sonnet, effort: medium -->
Retrospectives
回顾
Captures learnings at natural completion points and persists them for future use. This skill is both auto-triggered (EPIC terminal transition hook in swain-design) and manually invocable via .
/swain-retro在自然完成节点捕获经验总结并保存以供后续使用。该技能既可自动触发（通过swain-design中的EPIC终态转换钩子），也可通过手动调用。
/swain-retroOutput modes
输出模式
| Scope | Output | Rationale |
|---|---|---|
| EPIC-scoped (auto or explicit) | | The EPIC already contains lifecycle, success criteria, and child specs — it's the single source of truth for "what we shipped and what we learned" |
| Cross-epic / time-based (manual) | Standalone retro doc in | No single artifact owns the scope — a dedicated doc is required |
| 范围 | 输出 | 设计思路 |
|---|---|---|
| 单个EPIC范围（自动或显式触发） | 在EPIC工件中追加 | EPIC已包含生命周期、成功标准及子规格说明——它是“我们交付了什么以及学到了什么”的唯一可信来源 |
| 跨EPIC/基于时间（手动触发） | 在 | 没有单个工件能覆盖该范围——需要专用文档 |
Invocation modes
调用模式
| Mode | Trigger | Context source | Output | Interactive? |
|---|---|---|---|---|
| Auto | EPIC transitions to terminal state (called by swain-design) | The EPIC and its child artifacts | Embedded in EPIC | No — fully automated |
| Interactive | EPIC transitions to terminal state during a live session | The EPIC and its child artifacts | Embedded in EPIC | Yes — reflection questions offered |
| Manual | User runs | Recent work — git log, closed tasks, transitioned artifacts | Standalone retro doc (required) | Yes |
| Scoped | | Specific artifact and its related work | Embedded in EPIC (if EPIC-scoped) or standalone | Yes |
Terminal states that trigger auto-retro: , , . The retro content adapts to the terminal state — an Abandoned EPIC's retro focuses on why work stopped and what was learned, not on success criteria.
CompleteAbandonedSuperseded| 模式 | 触发条件 | 上下文来源 | 输出 | 是否交互式 |
|---|---|---|---|---|
| 自动 | EPIC转换至终态（由swain-design调用） | EPIC及其子工件 | 嵌入EPIC中 | 否——完全自动化 |
| 交互式 | 实时会话中EPIC转换至终态 | EPIC及其子工件 | 嵌入EPIC中 | 是——提供反思问题 |
| 手动 | 用户执行 | 近期工作记录——git日志、已关闭任务、已转换状态的工件 | 独立回顾文档（必填） | 是 |
| 指定范围 | | 指定工件及其相关工作 | 嵌入EPIC中（如果是EPIC范围）或独立文档 | 是 |
触发自动回顾的终态：、、。回顾内容会适配终态——针对已中止（Abandoned）的EPIC，回顾重点会放在工作停止的原因及学到的经验，而非成功标准。
CompleteAbandonedSupersededStep 1 — Gather context
步骤1 — 收集上下文
Collect evidence of what happened during the work period.
收集工作期间的相关证据。
For EPIC-scoped retros (auto or scoped)
针对单个EPIC范围的回顾（自动或指定范围）
bash
undefinedbash
undefinedGet the EPIC and its children
获取EPIC及其子工件
bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" deps <EPIC-ID>
bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" deps <EPIC-ID>
Get closed tasks linked to child specs
获取关联到子规格说明的已关闭任务
TK_BIN="$(cd skills/swain-do/bin && pwd)"
export PATH="$TK_BIN:$PATH"
ticket-query '.status == "closed"' 2>/dev/null | grep -l "<EPIC-ID>|<SPEC-IDs>"
Also read:
- The EPIC's lifecycle table (dates, duration)
- Child SPECs' verification tables (what was proven)
- Any ADRs created during the work
- Git log for commits between EPIC activation and completion datesTK_BIN="$(cd skills/swain-do/bin && pwd)"
export PATH="$TK_BIN:$PATH"
ticket-query '.status == "closed"' 2>/dev/null | grep -l "<EPIC-ID>|<SPEC-IDs>"
同时读取：
- EPIC的生命周期表格（日期、时长）
- 子SPEC的验证表格（已验证内容）
- 工作期间创建的所有ADR
- EPIC激活至完成期间的git提交日志For manual (unscoped) retros
针对手动（无指定范围）的回顾
bash
undefinedbash
undefinedRecent git activity
近期git活动
git log --oneline --since="1 week ago" --no-merges
git log --oneline --since="1 week ago" --no-merges
Recently closed tasks
近期已关闭任务
TK_BIN="$(cd skills/swain-do/bin && pwd)"
export PATH="$TK_BIN:$PATH"
ticket-query '.status == "closed"' 2>/dev/null | head -20
TK_BIN="$(cd skills/swain-do/bin && pwd)"
export PATH="$TK_BIN:$PATH"
ticket-query '.status == "closed"' 2>/dev/null | head -20
Recently transitioned artifacts
近期状态已转换的工件
bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" status 2>/dev/null
Also check:
- Existing memory files for context on prior patterns
- Previous retro docs in `docs/swain-retro/` for recurring themesbash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" status 2>/dev/null
同时检查：
- 现有记忆文件，获取过往模式的上下文
- `docs/swain-retro/`目录下的历史回顾文档，查找重复出现的主题Step 2 — Generate or prompt reflection
步骤2 — 生成或触发反思
Auto mode (non-interactive)
自动模式（非交互式）
When invoked by swain-design during a non-interactive EPIC terminal transition (e.g., dispatched agent, batch processing), generate the retro content automatically from the gathered context:
- Synthesize what was accomplished, what changed from the original scope, and what patterns are visible in the commit/task history
- For or
AbandonedEPICs, focus on why the work stopped and what was learnedSuperseded - Proceed directly to Step 3 (memory extraction) and Step 4 (write output)
当在非交互式EPIC终态转换过程中由swain-design调用时（如调度代理、批量处理），从收集到的上下文自动生成回顾内容：
- 综合已完成的工作、与原始范围的差异，以及提交/任务历史中可见的模式
- 针对或
Abandoned的EPIC，重点放在工作停止的原因及学到的经验Superseded - 直接进入步骤3（提取记忆）和步骤4（写入输出）
Interactive mode
交互式模式
When the user is present (live session, manual invocation), present a summary and offer reflection:
当用户在场时（实时会话、手动调用），展示总结并引导反思：
Summary format
总结格式
Retro scope: {EPIC-NNN title / "recent work"} Period: {start date} — {end date} Artifacts completed: {list} Tasks closed: {count} Key commits: {notable commits}
回顾范围： {EPIC-NNN标题 / "近期工作"} 周期： {开始日期} — {结束日期} 已完成工件： {列表} 已关闭任务数： {数量} 关键提交： {重要提交记录}
Reflection questions
反思问题
Ask these one at a time, waiting for user response between each:
- What went well? What patterns or approaches worked effectively that we should repeat?
- What was surprising? Anything unexpected — blockers, shortcuts, scope changes?
- What would you change? If you could redo this work, what would you do differently?
- What patterns emerged? Any recurring themes across tasks — tooling friction, design gaps, communication patterns?
Adapt follow-up questions based on user responses. If the user gives brief answers, probe deeper. If they're expansive, move on.
逐个提出以下问题，等待用户回复后再继续下一个：
- 哪些方面做得好？ 哪些模式或方法有效，我们应该重复使用？
- 哪些情况出乎意料？ 任何意外事件——障碍、捷径、范围变更？
- 你会做出哪些改变？ 如果可以重做这项工作，你会有什么不同的做法？
- 出现了哪些模式？ 任务中反复出现的主题——工具摩擦、设计缺口、沟通模式？
根据用户回复调整后续问题。如果用户回答简短，进一步追问；如果回答详细，则继续下一个问题。
Step 3 — Distill into memory files
步骤3 — 提炼为记忆文件
After the reflection conversation, create or update memory files:
反思对话结束后，创建或更新记忆文件：
Feedback memories
反馈记忆
For behavioral patterns and process learnings that should guide future agent behavior:
markdown
---
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}Write to the project memory directory:
~/.claude/projects/<project-slug>/memory/feedback_retro_{topic}.mdThe project slug is the project path with slashes replaced by dashes (e.g., → ). These files live in Claude's memory system (not swain's state), which is intentional — retro learnings persist across all Claude Code sessions for this project.
/Users/cristos/Documents/code/swain-Users-cristos-Documents-code-swain.agents/Update index.
MEMORY.md针对应指导未来代理行为的行为模式和流程经验：
markdown
---
name: retro-{topic}
description: {经验总结的单行描述}
type: feedback
---
{模式或规则}
**原因：** {回顾中用户的解释}
**应用方式：** {该指导生效的场景}写入项目记忆目录：
~/.claude/projects/<project-slug>/memory/feedback_retro_{topic}.md项目slug是将项目路径中的斜杠替换为短横线后的名称（例如： → ）。这些文件存储在Claude的记忆系统中（而非swain的状态目录），这是有意设计的——回顾经验会在该项目的所有Claude Code会话中持续保留。
/Users/cristos/Documents/code/swain-Users-cristos-Documents-code-swain.agents/更新索引文件。
MEMORY.mdProject memories
项目记忆
For context about ongoing work patterns, team dynamics, or project-specific learnings:
markdown
---
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}针对与持续工作模式、团队动态或项目特定经验相关的上下文：
markdown
---
name: retro-{topic}
description: {单行描述}
type: project
---
{事实或观察结果}
**原因：** {回顾中的上下文}
**应用方式：** {该内容如何影响未来的建议}Rules for memory creation
记忆文件创建规则
- Only create memories the user has explicitly validated during the reflection
- Merge with existing memories when the learning extends a prior pattern
- Use absolute dates (from the retro context), not relative
- Maximum 3-5 memory files per retro — distill, don't dump
- 仅创建用户在回顾中明确确认的记忆
- 当经验总结扩展了过往模式时，合并到现有记忆文件中
- 使用绝对日期（来自回顾上下文），而非相对日期
- 每次回顾最多创建3-5个记忆文件——提炼内容，而非简单堆砌
Step 4 — Write output
步骤4 — 写入输出
Output destination depends on scope — see Output modes at the top.
输出目标取决于范围——参见顶部的输出模式。
EPIC-scoped: embed in the EPIC artifact
单个EPIC范围：嵌入EPIC工件
Append a section to the EPIC markdown file, before the table. This keeps the EPIC as the single source of truth.
## Retrospective## Lifecyclemarkdown
undefined在EPIC的markdown文件中追加章节，放在表格之前。这样可保持EPIC作为唯一可信来源的地位。
## Retrospective## Lifecyclemarkdown
undefinedRetrospective
Retrospective
Terminal state: {Complete | Abandoned | Superseded}
Period: {activation date} — {terminal date}
终态： {Complete | Abandoned | Superseded}
周期： {激活日期} — {终态日期}
Summary
总结
{What was accomplished — or for Abandoned/Superseded, what was learned and why work stopped}
{已完成的工作——针对已中止/已取代的EPIC，则为学到的经验及工作停止的原因}
Reflection
反思
{Synthesized findings — from auto-generation or interactive Q&A}
{综合结论——来自自动生成或交互式问答}
Learnings captured
已捕获的经验总结
| Memory file | Type | Summary |
|---|---|---|
| feedback_retro_x.md | feedback | ... |
| project_retro_y.md | project | ... |
undefined| 记忆文件 | 类型 | 摘要 |
|---|---|---|
| feedback_retro_x.md | feedback | ... |
| project_retro_y.md | project | ... |
undefinedCross-epic / time-based: standalone retro doc (required)
跨EPIC/基于时间：独立回顾文档（必填）
For manual retros not scoped to a single EPIC, a standalone doc is required — no single artifact owns the scope.
bash
mkdir -p docs/swain-retroFile:
docs/swain-retro/YYYY-MM-DD-{topic-slug}.mdmarkdown
undefined针对未指定单个EPIC范围的手动回顾，必须生成独立文档——没有单个工件能覆盖该范围。
bash
mkdir -p docs/swain-retro文件路径：
docs/swain-retro/YYYY-MM-DD-{topic-slug}.mdmarkdown
undefinedRetro: {title}
Retro: {标题}
Date: {YYYY-MM-DD}
Scope: {description of what's covered}
Period: {start} — {end}
日期： {YYYY-MM-DD}
范围： {覆盖内容的描述}
周期： {开始日期} — {结束日期}
Summary
总结
{Brief description of what was completed across the scope}
{范围内已完成工作的简要描述}
Artifacts
工件
| Artifact | Title | Outcome |
|---|---|---|
| ... | ... | Complete/Abandoned/... |
| 工件 | 标题 | 结果 |
|---|---|---|
| ... | ... | 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
已捕获的经验总结
| Memory file | Type | Summary |
|---|---|---|
| feedback_retro_x.md | feedback | ... |
| project_retro_y.md | project | ... |
undefined| 记忆文件 | 类型 | 摘要 |
|---|---|---|
| feedback_retro_x.md | feedback | ... |
| project_retro_y.md | project | ... |
undefinedStep 5 — Update session bookmark
步骤5 — 更新会话书签
bash
BOOKMARK="$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)"
bash "$BOOKMARK" "Completed retro for {scope} — {N} learnings captured"bash
BOOKMARK="$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)"
bash "$BOOKMARK" "Completed retro for {scope} — {N} learnings captured"Integration with swain-design
与swain-design的集成
swain-design orchestrates this skill when an EPIC transitions to any terminal state (, , ):
CompleteAbandonedSuperseded- swain-design completes the phase transition (move, status update, commit, hash stamp)
- swain-design invokes swain-retro with the EPIC ID and terminal state
- swain-retro gathers context, generates/prompts reflection, extracts memories, and embeds the section in the EPIC
## Retrospective - swain-design commits the retro content as part of (or immediately after) the transition
Interactive detection: If the session is interactive (user is present and responding), swain-retro offers the reflection questions. If non-interactive (dispatched agent, batch), it runs fully automated.
This is best-effort — if swain-retro is not available, the EPIC transition still succeeds without a retro section.
当EPIC转换至任意终态（、、）时，swain-design会编排该技能：
CompleteAbandonedSuperseded- swain-design完成阶段转换（移动文件、更新状态、提交、哈希标记）
- swain-design传入EPIC ID和终态调用swain-retro
- swain-retro收集上下文、生成/触发反思、提取记忆，并在EPIC中嵌入章节
## Retrospective - swain-design将回顾内容作为转换的一部分（或紧随其后）提交
交互式检测：如果会话是交互式的（用户在场并响应），swain-retro会提供反思问题。如果是非交互式的（调度代理、批量处理），则完全自动运行。
这是尽力而为的机制——如果swain-retro不可用，EPIC转换仍会成功，只是不会添加回顾章节。
Referencing prior retros
参考过往回顾
When running a new retro, scan both EPIC artifacts (grep for sections) and for prior retros. If patterns recur across multiple retros, call them out explicitly — recurring themes are the most valuable learnings.
## Retrospectivedocs/swain-retro/bash
undefined运行新的回顾时，扫描EPIC工件（搜索章节）和目录下的历史回顾文档。如果多个回顾中出现重复模式，需明确指出——重复出现的主题是最有价值的经验总结。
## Retrospectivedocs/swain-retro/bash
undefinedCheck standalone retro docs
检查独立回顾文档
ls docs/swain-retro/*.md 2>/dev/null | head -10
ls docs/swain-retro/*.md 2>/dev/null | head -10
Check embedded retros in EPICs
检查EPIC中嵌入的回顾
grep -rl "## Retrospective" docs/epic/ 2>/dev/null | head -10
undefinedgrep -rl "## Retrospective" docs/epic/ 2>/dev/null | head -10
undefined