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。振り返りの内容は終了状態に応じて変わります。Abandoned の 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 — 振り返りを生成するか、質問を提示する

自動モード（非対話型）

非対話型の EPIC 終了状態への遷移時（例：ディスパッチされたエージェント、バッチ処理）に swain-design から呼び出された場合は、収集したコンテキストに基づいて振り返りの内容を自動的に生成します。

1. 達成したこと、当初の対象範囲から変更された点、コミットやタスクの履歴から見えるパターンを総合します
2. Abandoned または Superseded の EPIC では、作業を中止した理由と得られた学びに焦点を当てます
3. ステップ 3（メモリの抽出）とステップ 4（出力の書き込み）に直接進みます

対話モード

ユーザーがその場にいる場合（ライブセッション、手動呼び出し）は、要約を提示して振り返りを促します。

要約の形式

振り返りの対象： {EPIC-NNN のタイトル／「最近の作業」} 期間： {開始日} — {終了日} 完了した成果物： {一覧} クローズしたタスク： {件数} 主なコミット： {注目すべきコミット}

振り返りの質問

次の質問を1つずつ行い、それぞれの質問の後にユーザーの回答を待ってください。

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 のメモリファイルに記録します。これらは、今後のセッションに引き継ぐべきオペレーターの好みやプロジェクト固有のパターンを示すものだからです。

フィードバックメモリ

今後のエージェントの振る舞いを導く行動パターンやプロセス上の学びの場合：

---
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

プロジェクトのスラッグは、パスのスラッシュをハイフンに置き換えたものです（例：/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 によって定義されています。

各学びを分類し、適切な出力先に振り分けてください。

学びの種類	振り分け先	例
スキルに新しい振る舞いやガードレールが必要	仕様の候補 — 振り返りドキュメントの「仕様の候補」セクションに追加	「swain-release は worktree 内での実行を拒否すべき」
複数の領域にまたがるプロセス変更	ADR の候補 — 振り返りドキュメントに記載	「ディスパッチされたエージェントは 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 ファイルに ## Retrospective セクションを追加し、## Lifecycle テーブルの前に配置してください。これにより、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 にスコープが限定されない手動の振り返りでは、スコープを所有する単一の成果物がないため、スタンドアロンのドキュメントが必須です。

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 セクション）を書いた後、本文全体をスキャンし、(SPEC|EPIC|INITIATIVE|VISION|SPIKE|ADR|PERSONA|RUNBOOK|DESIGN|JOURNEY|TRAIN)-[0-9]+ に一致する、単独で記載された成果物 ID を探します。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 の値は、YAML との互換性を保つため、ID のままにします。

コンテキストを含む成果物への参照

振り返りの出力で成果物（子仕様、関連成果物、関連作業）を参照する場合は、コンテキスト行を使用します。

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 に記載されていない新機能 — エピックでリリースされた内容が README に記載されていません。
   • 古くなった約束 — エピックで削除または置き換えられた内容が、README には引き続き記載されています。
   • 動作の変更 — エピックで機能の仕組みが変更されたものの、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 との連携

swain-design は、EPIC が終端状態（Complete、Abandoned、Superseded）に遷移したときに、このスキルをオーケストレーションします。

1. swain-design がフェーズ遷移を完了します（移動、ステータス更新、コミット、ハッシュの記録）。
2. swain-design が EPIC ID と終端状態を指定して swain-retro を呼び出します。
3. swain-retro がコンテキストを収集し、振り返りを生成／促し、記憶を抽出して、## Retrospective セクションを EPIC に埋め込みます。
4. swain-design が遷移の一環として（または遷移の直後に）振り返りの内容をコミットします。

対話形式の判定： セッションが対話形式の場合（ユーザーが参加して応答している場合）、swain-retro は振り返りの質問を提示します。非対話形式の場合（ディスパッチされたエージェント、バッチ処理）は、完全に自動で実行します。

これはベストエフォートです。swain-retro が利用できない場合でも、振り返りセクションなしで EPIC の遷移は成功します。

過去の振り返りを参照する

新しい振り返りを実行するときは、EPIC の成果物（## Retrospective セクションを grep で検索）と 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