solo-retro

/retro

このスキルは自己完結型です。他のスキル（/review、/audit、/build）への委任や Task サブエージェントの起動は行わず、以下のフェーズに従ってください。分析はすべて直接実行します。

パイプライン実行後の振り返りです。パイプラインログを解析し、生産的なイテレーションと無駄なイテレーションを数え、繰り返し発生する失敗パターンを特定し、パイプライン実行を評価して、次回同じ失敗が起きないようスキルやスクリプトに対する具体的な修正案を提示します。

ライブコンテキスト

• ブランチ：!git branch --show-current 2>/dev/null
• 最近のコミット：!git log --oneline -10 2>/dev/null
• 変更ファイル：!git diff --name-only HEAD~5..HEAD 2>/dev/null | head -20

使用するタイミング

パイプラインの完了後（またはキャンセル後）に使用します。これはプロセス品質のチェックです。/review がコード品質をチェックするのに対し、/retro はパイプラインのプロセス品質をチェックします。

パイプラインログの有無を問わず、任意のプロジェクトで単独でも使用できます。

MCP ツール（利用可能な場合に使用）

• session_search(query) — 過去のパイプライン実行や既知の問題を検索します
• codegraph_explain(project) — プロジェクトのアーキテクチャに関するコンテキストを把握します
• codegraph_query(query) — コードグラフからプロジェクトのメタデータを検索します

MCP ツールを利用できない場合は、Glob + Grep + Read に切り替えてください。

フェーズ 1：成果物の特定

1. プロジェクトを特定します。$ARGUMENTS または CWD を使用します。

   • 引数が指定されている場合：プロジェクト名として使用します
   • それ以外の場合：CWD のベース名から取得します（例：~/projects/my-app -> my-app）

2. パイプライン状態ファイルを探します： .solo/pipelines/solo-pipeline-{project}.local.md（プロジェクト内）または ~/.solo/pipelines/solo-pipeline-{project}.local.md（グローバルなフォールバック）

   • ファイルが存在する場合：パイプラインはまだ実行中か、クリーンアップされていません。YAML フロントマターの project_root: を読み取ります
   • 存在しない場合：パイプラインは完了しています。CWD をプロジェクトルートとして使用します

3. 成果物の存在を確認します（並列読み込み）：

   • パイプラインログ：{project_root}/.solo/pipelines/pipeline.log
   • イテレーションログ：{project_root}/.solo/pipelines/iter-*.log
   • 進捗ファイル：{project_root}/.solo/pipelines/progress.md
   • 完了済み計画ディレクトリ：{project_root}/docs/plan-done/
   • アクティブな計画：{project_root}/docs/plan/

4. 分析モードを決定します：

   • パイプラインログが存在する場合：ログに基づく完全な分析を進めます（フェーズ 2～4）
   • パイプラインログが存在しない場合：フォールバックモードに切り替えます（「フォールバック分析」を参照）

5. イテレーションログを数えます（存在する場合）：ls {project_root}/.solo/pipelines/iter-*.log | wc -l

   • 次のように報告します：「{N} 件のイテレーションログが見つかりました」

フォールバック分析（パイプラインログがない場合）

パイプラインログがなくても、次の分析によって有益な情報を提供できます。

1. Git 履歴： git log --oneline --since="1 week ago" — コミット頻度、パターン、Conventional Commits 形式
2. テスト結果： CLAUDE.md または package.json で設定されている場合はテストスイートを実行します
3. ビルド状況： 設定されている場合はビルドを実行します
4. CLAUDE.md の変更： git log --oneline -- CLAUDE.md — ドキュメントの変遷
5. コード品質指標： ファイル数、TODO/FIXME の密度、デッドコードの兆候
6. プロジェクト構成： docs/、tests/、CI 設定の充実度

フェーズ 2～4 は省略し、フェーズ 5（計画との整合性）とフェーズ 6（Git とコード品質）に直接進みます。フェーズ 7 のスコアでは、利用可能なデータの比重を高めてください。

フェーズ 2：パイプラインログの解析（定量的）

pipeline.log 全体を読み込みます。各行を解析し、ログタグから構造化データを抽出します。

ログ形式： [HH:MM:SS] TAG | message

タグごとの抽出内容：

タグ	抽出する内容
START	パイプライン実行の境界 — 再起動回数（複数の START 行は再起動を示します）
STAGE	iter N/M | stage S/T: {stage_id} — ステージごとの反復回数
SIGNAL	<solo:done/> または <solo:redo/> — 完了シグナルを受け取ったステージ
INVOKE	呼び出されたスキル — スキル名を抽出し、誤った名前がないか確認します
ITER	commit: {sha} | result: {stage complete|continuing} — 反復ごとの結果
CHECK	{stage} | {path} -> FOUND|NOT FOUND — マーカーファイルの確認
FINISH	Duration: {N}m — 実行ごとの合計所要時間
MAXITER	Reached max iterations ({N}) — 反復回数の上限に達したか
QUEUE	プランの循環イベント（有効化、アーカイブ）
CIRCUIT	サーキットブレーカーが作動したか（存在する場合）
CWD	作業ディレクトリの変更
CTRL	制御シグナル（一時停止／停止／スキップ）

指標を算出します：

total_runs = count of START lines
total_iterations = count of ITER lines
productive_iters = count of ITER lines with "stage complete"
wasted_iters = total_iterations - productive_iters
waste_pct = wasted_iters / total_iterations * 100
maxiter_hits = count of MAXITER lines
plan_cycles = count of QUEUE lines with "Cycling"

per_stage = {
  stage_id: {
    attempts: count of STAGE lines for this stage,
    successes: count of ITER lines with "stage complete" for this stage,
    waste_ratio: (attempts - successes) / attempts * 100,
  }
}

フェーズ 3：Progress.md の解析（定性的）

progress.md を読み込み、エラーパターンを調べます。

1. 不明なスキルのエラー： Unknown skill: を grep し、誤っていたスキル名を抽出します
2. 空の反復： 「Last 5 lines」にエラーまたはセッションヘッダーしか表示されていない反復（実際の作業が行われていない）
3. 繰り返されるエラー： 同じエラーが連続する反復で発生している場合 -> スピンループの兆候
4. シグナルの重複： 同じ反復内に <solo:done/><solo:done/> がある場合 -> 軽微なノイズ（記録しますが、減点しません）
5. やり直しループ： build->review->redo->build のサイクルが発生した回数を数えます

見つかったエラーパターンごとに、以下を記録します。

• パターン名
• 初回発生（反復番号）
• 発生回数の合計
• 連続発生回数（最大）

フェーズ 4：反復ログの解析（サンプルベース）

すべての反復ログを読まないでください。60 件以上ある可能性があります。効率的にサンプルを抽出します。

1. パターンごとの最初の失敗反復： フェーズ 3 で見つかった各失敗パターンについて、それが最初に現れる反復ログを読み込みます

   • 読み込み時に ANSI コードを除去します：sed 's/\x1b\[[0-9;]*m//g' < iter-NNN-stage.log | head -100

2. ステージごとの最初の成功反復： 最終的に成功した各ステージについて、最初に成功した反復ログを読み込みます

   • 出力内の <solo:done/> を探します

3. 最後のレビュー反復： 最後の iter-*-review.log（判定）を読み込みます

4. サンプルログごとに抽出する内容：

   • 呼び出されたツール（tool_use ブロック数）
   • 発生したエラー（Error、error、Unknown、failed を grep）
   • シグナル出力（<solo:done/> または <solo:redo/> があるか）
   • 意味のある最初の 5 行と最後の 10 行（空行を除く）

フェーズ 5：プランとの整合性の確認

docs/plan-done/ と docs/plan/ の各トラックディレクトリについて、以下を行います。

1. spec.md を読み込みます（存在する場合）。

   • 受け入れ条件を数えます。- [ ] と - [x] のチェックボックスの合計
   • 算出します：criteria_met = checked / total * 100

2. plan.md を読み込みます（存在する場合）。

   • タスクを数えます。- [ ] と - [x] のチェックボックスの合計
   • フェーズ数を数えます（## ヘッダー）
   • SHA 注釈（``）を確認します
   • 算出します：tasks_done = checked / total * 100

3. トラックごとの概要をまとめます：

   • トラック ID、受け入れ条件の達成率%、タスク完了率%、SHA の有無

フェーズ 6：Git とコード品質（簡易チェック）

簡易チェックのみを行います。/review を全面的に実施するものではありません。

1. コミット数と形式：

   git -C {project_root} log --oneline | wc -l
   git -C {project_root} log --oneline | head -30
   

   • Conventional Commits 形式（feat:、fix:、chore:、test:、docs:、refactor:、build:、ci:、perf:）のコミット数を数えます
   • 算出します：conventional_pct = conventional / total * 100

2. コミッター別の内訳：

   git -C {project_root} shortlog -sn --no-merges | head -10
   

3. テストの状態（テストコマンドが CLAUDE.md または package.json にある場合）：

   • テストスイートを実行し、成功数／失敗数を記録します
   • テストコマンドが見つからない場合はスキップし、「テストは設定されていません」と記録します

4. ビルドの状態（ビルドコマンドがある場合）：

   • ビルドを実行し、成功／失敗を記録します
   • ビルドコマンドが見つからない場合はスキップし、「ビルドは設定されていません」と記録します

フェーズ 6.5：コンテキスト劣化の分析

パイプラインの実行中に、コンテキストウィンドウの問題を示す兆候がないか確認します。

1. イテレーション品質の推移： 初期のイテレーションと後半のイテレーションを比較します。

   • 時間の経過とともにエラー率が上昇しましたか？（コンテキスト劣化の兆候）
   • エージェントが同じことを繰り返したり、計画を見失ったりし始めましたか？

2. 観察結果のマスキングの使用状況： プロジェクトのルートに scratch/ ディレクトリがあるか確認します。

   • あれば良好です。エージェントが大きな出力を別の場所に退避していました。
   • なければ、反復ログに100行を超えるツール出力がある場合、無駄の発生源として記録します。

3. 計画の再確認の証拠： 抽出した反復ログを確認し、エージェントがタスクの区切りで plan.md を読み直していたか確認します。

   • 計画の再確認がなく、タスクから逸脱している場合は、コンテキストエンジニアリングの不足です。

4. CLAUDE.md の肥大化： wc -c {project_root}/CLAUDE.md

   • 40,000文字超：警告 — 注意力が分散している可能性があります
   • 60,000文字超：危険 — コンテキストの予算が深刻に圧迫されています

調査結果をレポートの ## Context Health セクションに追加します。

## Context Health
- Iteration quality trend: {STABLE / DEGRADING / N/A}
- Observation masking: {USED / NOT USED / N/A}
- Plan recitation: {OBSERVED / ABSENT / N/A}
- CLAUDE.md size: {N} chars — {OK / WARN / BLOATED}

フェーズ 7：採点とレポート

${CLAUDE_PLUGIN_ROOT}/skills/retro/references/eval-dimensions.md から採点基準を読み込みます。 プラグインのルートが利用できない場合は、埋め込みの重みを使用します。

採点の重み：

• 効率（無駄の割合）：25%
• 安定性（再起動）：20%
• 適合性（基準の達成度）：20%
• 品質（テスト合格率）：15%
• コミット（Conventional Commits の割合）：5%
• ドキュメント（計画の古さ）：5%
• シグナル（クリーンなシグナル）：5%
• 速度（トラックごとの所要時間、正規化済み）：5%

注： フォールバックモード（パイプラインログがない場合）では、効率と安定性の重みを適合性、品質、コミットに再配分します。

レポートを {project_root}/docs/retro/{date}-retro.md に生成します：

# Pipeline Retro: {project} ({date})

## Overall Score: {N}/10

## Pipeline Efficiency

| Metric | Value | Rating |
|--------|-------|--------|
| Total iterations | {N} | |
| Productive iterations | {N} ({pct}%) | {emoji} |
| Wasted iterations | {N} ({pct}%) | {emoji} |
| Pipeline restarts | {N} | {emoji} |
| Max-iter hits | {N} | {emoji} |
| Total duration | {time} | {emoji} |
| Tracks completed | {N} | |
| Duration per track | {time/tracks} | {emoji} |

## Per-Stage Breakdown

| Stage | Attempts | Successes | Waste % | Notes |
|-------|----------|-----------|---------|-------|
| scaffold | | | | |
| setup | | | | |
| plan | | | | |
| build | | | | |
| deploy | | | | |
| review | | | | |

## Failure Patterns

### Pattern 1: {name}
- **Occurrences:** {N} iterations
- **Root cause:** {analysis}
- **Wasted:** {N} iterations
- **Fix:** {concrete suggestion with file reference}

### Pattern 2: ...

## Plan Fidelity

| Track | Criteria Met | Tasks Done | SHAs | Rating |
|-------|-------------|------------|------|--------|
| {track-id} | {N}% | {N}% | {yes/no} | {emoji} |

## Code Quality (Quick)

- **Tests:** {N} pass, {N} fail (or "not configured")
- **Build:** PASS / FAIL (or "not configured")
- **Commits:** {N} total, {pct}% conventional format

## Three-Axis Growth

| Axis | Score | Evidence |
|------|-------|----------|
| **Technical** (code, tools, architecture) | {0-10} | {what changed} |
| **Cognitive** (understanding, strategy, decisions) | {0-10} | {what improved} |
| **Process** (harness, skills, pipeline, docs) | {0-10} | {what evolved} |

If only one axis is served — note what's missing.

## Recommendations

1. **[CRITICAL]** {patch suggestion with file:line reference}
2. **[HIGH]** {improvement}
3. **[MEDIUM]** {optimization}
4. **[LOW]** {nice-to-have}

## Suggested Patches

### Patch 1: {file} — {description}

**What:** {one-line description}
**Why:** {root cause reference from Failure Patterns}

\```diff
- old line
+ new line
\```

評価ガイド（以下の絵文字を使用）：

• GREEN = 優秀
• YELLOW = 許容範囲
• RED = 要対応

フェーズ 8：対話形式でのパッチ適用

レポートの生成後：

1. 概要をユーザーに提示します：総合スコア、主な失敗パターン3件、主な推奨事項3件

2. 提案されたパッチごとに（ある場合）、AskUserQuestion を使用します：

   • 質問：「{file} にパッチを適用しますか？ {one-line description}」
   • 選択肢：「適用」／「スキップ」／「先に差分を表示」

3. 「先に差分を表示」の場合： 差分全体を表示してから、もう一度尋ねます（適用／スキップ）

4. 「適用」の場合： Edit ツールを使用して変更を直接適用します

5. すべてのパッチの処理後：

   • パッチを適用した場合：fix(retro): {description} でのコミットを提案します
   • 自動コミットはしないでください。コマンドの提案だけを行います

フェーズ 9：CLAUDE.md の改訂

パッチの適用後、今後のエージェントにとって簡潔で役立つ内容になるよう、プロジェクトの CLAUDE.md を改訂します。

手順：

1. **CLAUDE.md を読み込み、**サイズを確認します：wc -c CLAUDE.md
2. 今回の振り返りから得られた知見を追加します：
   • 次回避けるべき、記憶しておく価値のあるパイプラインの失敗パターン
   • 新しいワークフロールールやプロセスの改善
   • 更新されたコマンドやツールの変更
   • パイプラインの実行中に浮上したアーキテクチャ上の決定事項
3. 40,000文字を超えている場合は、思い切って削ります：
   • 完了したフェーズやマイルストーンの履歴を、それぞれ1行にまとめます
   • 冗長な説明を削り、簡潔で実行可能なメモだけを残します
   • 重複する情報（同じ内容を複数のセクションで説明しているもの）を削除します
   • 過去の移行に関するメモや、古いデバッグのコンテキストを削除します
   • コードから明らかな例や、スキル／ドキュメントファイルで説明されている例を削除します
   • 解決済みの問題に関する古いトラブルシューティングを削除します
4. 結果が40,000文字以下であることを確認します。 まだ超えている場合は、実用性の最も低い内容を削ります
5. 更新した CLAUDE.md を書き込み、「Last updated」の日付を更新します

優先順位（残す -> 削る）：

1. 必ず残す： 技術スタック、ディレクトリ構造、すべきこと／してはいけないことのルール、一般的なコマンド、アーキテクチャ上の決定事項
2. 残す： ワークフローの手順、継続中の問題のトラブルシューティング、主要なファイルへの参照
3. 簡潔にする： フェーズの履歴（各1行）、詳細な例、ツール／MCP の一覧
4. 最初に削る： 過去のメモ、冗長な説明、重複する内容、解決済みの問題

ルール：

• Do/Don't セクションを削除しないでください。重要なガードレールです。
• セクションの全体的な構成と順序を維持してください。
• すべての行に意味を持たせてください。「将来のエージェントが作業するうえで、これは必要か？」と問いかけてください。
• 更新をコミットしてください：git add CLAUDE.md && git commit -m "docs: revise CLAUDE.md (post-retro)"

フェーズ 10：ファクトリー批評（任意）

このフェーズは ${CLAUDE_PLUGIN_ROOT} が利用可能な場合（つまり、solo-factory がインストールされている場合）にのみ実行してください。 ファクトリーのコンテキストなしで単独のスキルとして実行している場合はスキップしてください。

プロジェクトのパイプラインを評価した後、視点を変えて、今回の成果を生み出したファクトリーそのもの（スキル、スクリプト、パイプラインのロジック）を評価してください。厳しく批評してください。

評価する項目：

1. 今回のパイプライン実行で呼び出されたスキルを読む（pipeline.log の INVOKE 行を確認）：

   • 各スキル：${CLAUDE_PLUGIN_ROOT}/skills/{stage}/SKILL.md
   • そのスキルには、このプロジェクトのニーズに合った指示がありましたか？
   • 含まれるべきコンテキストが欠けていませんでしたか？

2. パイプラインスクリプトのシグナル処理とステージのロジックを読む：

   • ${CLAUDE_PLUGIN_ROOT}/scripts/solo-dev.sh
   • 構造上の問題（ステージの順序が誤っている、再実行が欠けている、redo が壊れている）はありましたか？

3. フェーズ 3 の失敗パターンと照合する：

   • 失敗ごとに、根本原因はスキル、スクリプト、プロジェクトのどこにありましたか？
   • 無駄を生じさせたスキルは、ファクトリーの欠陥です。

ファクトリーを採点する（プロジェクトではなく）：

Factory Score: {N}/10

Skill quality:
- {skill}: {score}/10 — {why}
- {skill}: {score}/10 — {why}

Pipeline reliability: {N}/10 — {why}

Missing capabilities:
- {what the factory couldn't do that it should have}

Top factory defects:
1. {defect} → {which file to fix} → {concrete fix}
2. {defect} → {which file to fix} → {concrete fix}

ハーネスの進化 — より大きな視点で考える

ファクトリーを採点したら、さらに視点を広げてハーネス（エージェントを導くシステム全体：CLAUDE.md、docs/、リンター、スキル、テンプレート）について考えてください。次の点を確認してください。

1. コンテキストエンジニアリング： エージェントはリポジトリ内の情報だけで必要なものをすべて得られましたか？ それとも、知識が不足していたり、散在していたり、古くなっていたりして苦労しましたか？

   • ドキュメントが不足している場合は、docs/ または CLAUDE.md に追加してください
   • ドキュメントが古い場合は、doc-gardening の対象として記録してください
   • 暗黙知になっている知識は、明文化してください

2. アーキテクチャ上の制約： エージェントはモジュール境界を破ったり、一貫性のないパターンを生み出したり、規約を無視したりしましたか？

   • 境界違反が繰り返される場合は、リンターまたは構造テストが必要です
   • パターンに一貫性がない場合は、CLAUDE.md に原則を定める必要があります
   • データ形式の誤りがある場合は、境界で解析を強制する必要があります

3. 判断の記録： 今後のエージェントが再利用すべき有効な方法は何でしたか？ 避けるべき失敗は何でしたか？

   • 良いパターンは、先例として docs または CLAUDE.md に記録してください
   • 悪いパターンは、アンチパターンまたは lint ルールとして明文化してください
   • 「明日、別のエージェントが同じ問題に直面したら、何を見つけられるべきか？」と考えてください

4. スキルの不足： 指示を改善すべきスキルはどれですか？ 新たに作成すべきスキルはありますか？

   • 無駄を生じさせたスキルは、具体的な SKILL.md の修正案を示してください
   • 能力が不足している場合は、進化ログに新しいスキルの案を記載してください

進化ログに記録する：

{project_root}/docs/evolution.md に調査結果を追記してください（ファイルが存在しない場合は作成してください）。~/.solo/evolution.md が存在する場合は、プロジェクト横断の追跡用にそちらにも追記してください。

## {YYYY-MM-DD} | {project} | Factory Score: {N}/10

Pipeline: {stages run} | Iters: {total} | Waste: {pct}%

### Defects
- **{severity}** | {skill/script}: {description}
  - Fix: {concrete file:change}

### Harness Gaps
- **Context:** {what knowledge was missing or stale for the agent}
- **Constraints:** {what boundary violations or inconsistencies occurred}
- **Precedents:** {patterns worth capturing for future agents — good or bad}

### Missing
- {capability the factory lacked}

### What worked well
- {skill/pattern that performed efficiently}

ルール：

• 率直に評価してください。スキルに問題があれば、そう明言してください
• すべての欠陥に、具体的な修正案（ファイルと変更内容）を示してください
• 有効な点も記録してください。良いパターンを後退させないでください
• 記述は簡潔にしてください。このファイルには今後も内容が蓄積されます

シグナル出力

出力シグナル： <solo:done/>

重要： /retro は常に <solo:done/> を出力します。redo は必要ありません。パイプラインがどれほどひどい結果であっても、retro 自体は必ず完了します。

エッジケース

• pipeline.log も git 履歴もない場合： 明確なメッセージを表示して中止します — 「パイプラインログも git 履歴も見つかりません。分析するものがありません。」
• pipeline.log はないが git 履歴がある場合： フォールバックモードに切り替えます（フォールバック分析を参照）
• pipeline.log が空の場合： 「パイプラインログが空です — イテレーションが始まる前にパイプラインがキャンセルされたのでしょうか？」と報告します
• イテレーションログがない場合： フェーズ 4 のサンプリングをスキップし、レポートに記載します
• plan-done がない場合： フェーズ 5 をスキップし、「完了したプランが見つかりません」と記載します
• テスト／ビルドコマンドがない場合： フェーズ 6 でそれらのチェックをスキップし、レポートに記載します
• パイプラインがまだ実行中の場合： ユーザーに警告します — 「状態ファイルが存在します。パイプラインはまだ実行中の可能性があります。一部のデータを対象にレトロスペクティブを実行します。」

参照ファイル

• ${CLAUDE_PLUGIN_ROOT}/skills/retro/references/eval-dimensions.md — 評価基準（8 軸、重み）
• ${CLAUDE_PLUGIN_ROOT}/skills/retro/references/failure-catalog.md — 既知の失敗パターンと修正方法