retro

実行時の注意事項

• ワークフローで入力を求めて停止するよう指定されている場合は、ユーザーに直接尋ねてください。
• リポジトリ固有の指示の参照先として、AGENTS.md、TODO.md、TODOS.mdを確認してください。
• ワークフローの意図は維持しつつ、環境固有の表現は現在のツールセットに合わせて翻訳してください。

/retro — 週次エンジニアリング振り返り

コミット履歴、作業パターン、コード品質の指標を分析し、包括的なエンジニアリングの振り返りを生成します。チームを考慮し、コマンドを実行したユーザーを特定したうえで、各コントリビューターを分析し、個人ごとに称賛点と成長の機会を示します。コーディングエージェントを強力な補助として活用する、シニア IC／CTO レベルのビルダー向けに設計されています。

ユーザーが呼び出す場合

ユーザーが振り返りを求めたとき、またはretroを呼び出したときに、このスキルを使用します。

引数

• retro — デフォルト：過去7日間
• retro 24h — 過去24時間
• retro 14d — 過去14日間
• retro 30d — 過去30日間
• retro compare — 現在の期間と、同じ長さの直前の期間を比較
• retro compare 14d — 指定した期間で比較

手順

引数を解析して対象期間を決定します。引数が指定されていない場合は、デフォルトで7日間とします。git logのクエリには、d単位では--since="N days ago"、h単位では--since="N hours ago"、w単位では--since="N weeks ago"を使用します。時刻はすべて太平洋時間で報告します（タイムスタンプの変換にはTZ=America/Los_Angelesを使用）。

引数の検証： 引数が数字の後にd、h、wが続く形式、compareという単語、またはcompareの後に数字とd``h``wが続く形式のいずれにも一致しない場合は、次の使用方法を表示して終了します。

Usage: /retro [window]
  /retro              — last 7 days (default)
  /retro 24h          — last 24 hours
  /retro 14d          — last 14 days
  /retro 30d          — last 30 days
  /retro compare      — compare this period vs prior period
  /retro compare 14d  — compare with explicit window

ステップ1：生データを収集する

まず、originを取得して現在のユーザーを特定します。

git fetch origin main --quiet
# Identify who is running the retro
git config user.name
git config user.email

git config user.nameで返される名前が**「あなた」**、つまりこの振り返りを読む人です。それ以外の作成者はチームメイトです。説明ではこの点を踏まえ、「あなた」のコミットとチームメイトの貢献を区別します。

次のgitコマンドをすべて並列で実行します（互いに独立しています）。

# 1. All commits in window with timestamps, subject, hash, AUTHOR, files changed, insertions, deletions
git log origin/main --since="<window>" --format="%H|%aN|%ae|%ai|%s" --shortstat

# 2. Per-commit test vs total LOC breakdown with author
#    Each commit block starts with COMMIT:<hash>|<author>, followed by numstat lines.
#    Separate test files (matching test/|spec/|__tests__/) from production files.
git log origin/main --since="<window>" --format="COMMIT:%H|%aN" --numstat

# 3. Commit timestamps for session detection and hourly distribution (with author)
#    Use TZ=America/Los_Angeles for Pacific time conversion
TZ=America/Los_Angeles git log origin/main --since="<window>" --format="%at|%aN|%ai|%s" | sort -n

# 4. Files most frequently changed (hotspot analysis)
git log origin/main --since="<window>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn

# 5. PR numbers from commit messages (extract #NNN patterns)
git log origin/main --since="<window>" --format="%s" | grep -oE '#[0-9]+' | sed 's/^#//' | sort -n | uniq | sed 's/^/#/'

# 6. Per-author file hotspots (who touches what)
git log origin/main --since="<window>" --format="AUTHOR:%aN" --name-only

# 7. Per-author commit counts (quick summary)
git shortlog origin/main --since="<window>" -sn --no-merges

ステップ2：指標を算出する

次の指標をサマリーテーブルにまとめて表示します。

指標	値
mainへのコミット数	N
コントリビューター数	N
マージされたPR数	N
追加された行の合計	N
削除された行の合計	N
差し引きの追加LOC	N
テストLOC（追加行）	N
テストLOCの比率	N%
バージョン範囲	vX.Y.Z.W → vX.Y.Z.W
アクティブ日数	N
検出されたセッション数	N
セッション時間あたりの平均LOC	N

そのすぐ下に、作成者別ランキングを表示します。

Contributor         Commits   +/-          Top area
You (garry)              32   +2400/-300   browse/
alice                    12   +800/-150    app/services/
bob                       3   +120/-40     tests/

コミット数の降順で並べます。現在のユーザー（git config user.nameで取得）は、必ず先頭に「あなた（名前）」と表示します。

ステップ3：コミット時刻の分布

太平洋時間で、棒グラフを使った時間別ヒストグラムを表示します。

Hour  Commits  ████████████████
 00:    4      ████
 07:    5      █████
 ...

次の点を特定して明示します。

• ピーク時間帯
• 活動が少ない時間帯
• パターンが二峰性（朝／夕方）か、継続的か
• 深夜のコーディングの集中（午後10時以降）

ステップ4：作業セッションの検出

連続するコミット間の45分の間隔をしきい値として、セッションを検出します。各セッションについて、次を報告します。

• 開始／終了時刻（太平洋時間）
• コミット数
• 所要時間（分）

セッションを次のように分類します。

• 集中セッション（50分以上）
• 中程度のセッション（20～50分）
• 短時間セッション（20分未満。通常は単発のコミット）

次の値を算出します。

• アクティブなコーディング時間の合計（各セッションの所要時間の合計）
• セッションの平均時間
• アクティブ時間あたりのLOC

ステップ5：コミット種別の内訳

Conventional Commitsのプレフィックス（feat/fix/refactor/test/chore/docs）で分類し、割合を棒グラフで表示します。

feat:     20  (40%)  ████████████████████
fix:      27  (54%)  ███████████████████████████
refactor:  2  ( 4%)  ██

fixの割合が50％を超える場合は、その旨を示してください。これは「素早く出荷し、素早く修正する」パターンを示しており、レビュー漏れの可能性があります。

ステップ6：変更頻度の高いファイルの分析

変更回数が多いファイルの上位10件を表示します。次の点を明示してください。

• 5回以上変更されたファイル（変更集中箇所）
• 上位ファイルにおけるテストファイルと本番ファイルの内訳
• VERSION／CHANGELOGの変更頻度（バージョン管理の指標）

ステップ7：PRサイズの分布

コミットの差分からPRのサイズを推定し、次のカテゴリに分けます。

• 小規模（100 LOC未満）
• 中規模（100～500 LOC）
• 大規模（500～1500 LOC）
• 特大（1500 LOC以上）— ファイル数も併せて明示します

ステップ 8：フォーカススコアと今週のリリース

フォーカススコア： 変更が最も多いトップレベルディレクトリ（例：app/services/、app/views/）に触れたコミットの割合を計算します。スコアが高いほど、より集中して作業しています。低いほど、コンテキストの切り替えが多く、作業が分散しています。次の形式で報告します：「フォーカススコア：62%（app/services/）」

今週のリリース： 対象期間内でLOCが最も多いPRを1つ自動で特定します。次の内容を強調します。

• PR番号とタイトル
• 変更されたLOC
• 重要な理由（コミットメッセージと変更されたファイルから推測）

ステップ 9：チームメンバーの分析

各コントリビューター（現在のユーザーを含む）について、次の項目を計算します。

1. コミット数とLOC — コミット総数、追加行数、削除行数、差し引きLOC
2. 注力分野 — 最も多く変更したディレクトリ／ファイル（上位3件）
3. コミット種別の内訳 — 個人ごとのfeat／fix／refactor／testの内訳
4. セッションパターン — コーディングする時間帯（ピーク時間）、セッション数
5. テストへの取り組み — 個人ごとのテストLOC比率
6. 最大のリリース — 対象期間内で最も影響の大きかった個人のコミットまたはPR

現在のユーザー（「あなた」）の場合： このセクションでは、最も詳しく分析します。個人の振り返りの内容をすべて含めます。セッション分析、時間帯のパターン、フォーカススコアなどです。一人称で表現します。「あなたのピーク時間は……」「あなたの最大のリリースは……」

各チームメイトの場合： 何に取り組んだか、その作業パターンと合わせて2〜3文で説明します。その後、次の内容を記載します。

• 称賛（具体的な内容を1〜2点）：実際のコミットを根拠にします。「よく頑張りました」ではなく、何が良かったのかを具体的に述べます。例：「認証ミドルウェア全体の書き換えを、テストカバレッジ45%で、集中した3セッションのうちにリリースしました」「すべてのPRが200 LOC未満で、細かく分割する姿勢が徹底されています」
• 成長の機会（具体的な内容を1点）：批判ではなく、次のレベルに進むための提案として述べます。実際のデータを根拠にします。例：「今週のテスト比率は12%でした。決済モジュールがさらに複雑になる前にテストカバレッジを追加すると効果的です」「同じファイルに対するfixコミットが5件あるため、最初のPRにレビューを追加していれば改善できたかもしれません」

コントリビューターが1人だけの場合（個人リポジトリ）： チームの内訳は省略し、これまでどおり個人の振り返りを行います。

Co-Authored-Byトレーラーがある場合： コミットメッセージ内のCo-Authored-By:行を解析します。主著者とともに、これらの著者にもコミットの貢献を計上します。AIの共著者（例：[email protected]）も記録しますが、チームメンバーには含めません。代わりに「AI支援コミット」を別の指標として追跡します。

ステップ 10：週ごとの傾向（対象期間が14日以上の場合）

対象期間が14日以上の場合は、週ごとに分けて次の傾向を表示します。

• 週ごとのコミット数（合計および著者別）
• 週ごとのLOC
• 週ごとのテスト比率
• 週ごとのfix比率
• 週ごとのセッション数

ステップ 11：連続記録の追跡

今日からさかのぼり、origin/mainへのコミットが1件以上ある連続日数を数えます。チーム全体と個人の両方の連続記録を追跡します。

# Team streak: all unique commit dates (Pacific time) — no hard cutoff
TZ=America/Los_Angeles git log origin/main --format="%ad" --date=format:"%Y-%m-%d" | sort -u

# Personal streak: only the current user's commits
TZ=America/Los_Angeles git log origin/main --author="<user_name>" --format="%ad" --date=format:"%Y-%m-%d" | sort -u

今日からさかのぼって、コミットが1件以上ある日が何日連続しているかを数えます。履歴全体を照会するため、どれほど長い連続記録も正確に報告できます。次の両方を表示します。

• 「チームの連続リリース日数：47日」
• 「あなたの連続リリース日数：32日」

ステップ 12：履歴の読み込みと比較

新しいスナップショットを保存する前に、過去の振り返り履歴があるか確認します。

ls -t .context/retros/*.json 2>/dev/null

過去の振り返りがある場合： Readツールを使って最新のものを読み込みます。主要な指標の差分を計算し、前回の振り返りとの傾向セクションに含めます。

                    Last        Now         Delta
Test ratio:         22%    →    41%         ↑19pp
Sessions:           10     →    14          ↑4
LOC/hour:           200    →    350         ↑75%
Fix ratio:          54%    →    30%         ↓24pp (improving)
Commits:            32     →    47          ↑47%
Deep sessions:      3      →    5           ↑2

過去の振り返りがない場合： 比較セクションを省略し、「初回の振り返りを記録しました。来週もう一度実行すると、傾向を確認できます。」を追加します。

ステップ 13：振り返り履歴の保存

連続記録を含むすべての指標を計算し、比較用に過去の履歴を読み込んだ後、JSONスナップショットを保存します。

mkdir -p .context/retros

今日の次の連番を決定します（$(date +%Y-%m-%d)を実際の日付に置き換えます）。

# Count existing retros for today to get next sequence number
today=$(TZ=America/Los_Angeles date +%Y-%m-%d)
existing=$(ls .context/retros/${today}-*.json 2>/dev/null | wc -l | tr -d ' ')
next=$((existing + 1))
# Save as .context/retros/${today}-${next}.json

Writeツールを使い、次のスキーマでJSONファイルを保存します。

{
  "date": "2026-03-08",
  "window": "7d",
  "metrics": {
    "commits": 47,
    "contributors": 3,
    "prs_merged": 12,
    "insertions": 3200,
    "deletions": 800,
    "net_loc": 2400,
    "test_loc": 1300,
    "test_ratio": 0.41,
    "active_days": 6,
    "sessions": 14,
    "deep_sessions": 5,
    "avg_session_minutes": 42,
    "loc_per_session_hour": 350,
    "feat_pct": 0.40,
    "fix_pct": 0.30,
    "peak_hour": 22,
    "ai_assisted_commits": 32
  },
  "authors": {
    "Garry Tan": { "commits": 32, "insertions": 2400, "deletions": 300, "test_ratio": 0.41, "top_area": "browse/" },
    "Alice": { "commits": 12, "insertions": 800, "deletions": 150, "test_ratio": 0.35, "top_area": "app/services/" }
  },
  "version_range": ["1.16.0.0", "1.16.1.0"],
  "streak_days": 47,
  "tweetable": "Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm"
}

ステップ 14：文章の作成

次の構成で出力します。

---

ツイート向け要約（最初の行。他のすべてより前に記載）：

Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d

エンジニアリングの振り返り：［期間］

サマリーテーブル

（ステップ 2 より）

前回の振り返りとの傾向比較

（ステップ 11 より。保存前に読み込みます。初回の振り返りでは省略）

時間とセッションの傾向

（ステップ 3～4 より）

チーム全体の傾向が何を意味するかを解説します。

• 最も生産性が高い時間帯と、その要因
• セッションが時間の経過とともに長くなっているか、短くなっているか
• 1 日あたりのアクティブなコーディング時間の推定値（チーム全体の合計）
• 注目すべき傾向：チームメンバーは同じ時間帯にコーディングしていますか。それとも交代制ですか？

リリース速度

（ステップ 5～7 より）

以下を取り上げて解説します。

• コミット種別の内訳と、そこから分かること
• PR の規模を適切に保てているか（PR は小さいままですか？）
• 修正連鎖の検出（同じサブシステムでの修正コミットの連続）
• バージョン更新の適切さ

コード品質の指標

• テスト LOC 比率の推移
• ホットスポット分析（同じファイルで変更が頻発していませんか？）
• 分割すべき XL PR の有無

集中度とハイライト

（ステップ 8 より）

• 集中度スコアとその解釈
• 今週の最優秀リリースの紹介

あなたの1週間（個人の詳細分析）

（ステップ 9 より。現在のユーザーのみ）

このセクションは、ユーザーが最も重視する部分です。以下を含めてください。

• 個人のコミット数、LOC、テスト比率
• セッションの傾向とピーク時間
• 注力した分野
• 最大のリリース
• うまくできたこと（コミットに基づく具体例を 2～3 件）
• 次に伸ばせること（具体的で実行可能な提案を 1～2 件）

チームの内訳

（ステップ 9 より。各チームメイトについて。個人リポジトリの場合は省略）

各チームメイトについて（コミット数の多い順に）セクションを作成します。

［名前］

• リリースしたもの：貢献内容、注力した分野、コミットの傾向について 2～3 文で説明します。
• 称賛：実際のコミットに基づき、本人がうまくできた具体的な点を 1～2 件挙げます。率直に、1 対 1 で実際に伝えるような内容にしてください。例：
  • 「認証モジュール全体を、レビューしやすい小規模な PR 3 件で整理しました。分割のお手本です」
  • 「新しいエンドポイントごとに、正常系だけでなく統合テストも追加しました」
  • 「ダッシュボードの読み込みに 2 秒かかる原因だった N+1 クエリを修正しました」
• 成長の機会：建設的で具体的な提案を 1 件挙げます。批判ではなく、成長への投資として伝えてください。例：
  • 「決済モジュールのテストカバレッジは 8％です。次の機能が追加される前に、ここへ投資する価値があります」
  • 「5 件の PR のうち 3 件が 800 LOC 超でした。分割すれば、問題を早期に発見でき、レビューもしやすくなります」
  • 「コミットはすべて午前 1～4 時に行われています。長期的にコード品質を保つには、持続可能なペースが大切です」

AI との協働に関する注記： Co-Authored-By の AI トレーラー（例：Codex、Copilot）を含むコミットが多い場合は、AI 支援を受けたコミットの割合をチーム指標として記載します。評価を加えず、「N％のコミットが AI 支援を受けていました」のように中立的に伝えてください。

チームの主な成果 3 件

期間内にチーム全体でリリースした、最もインパクトの大きいものを 3 件特定します。それぞれについて以下を記載します。

• 何をリリースしたか
• 誰がリリースしたか
• 重要な理由（製品やアーキテクチャへの影響）

改善すること 3 件

実際のコミットに基づく、具体的で実行可能な内容にします。個人とチームの両方の提案を含めます。「さらに良くするために、チームは……できます」のように表現してください。

来週の習慣 3 つ

小さく、実践的で、現実的な内容にします。どれも取り入れるのに 5 分未満で済むものにしてください。少なくとも 1 つはチームに関する内容にします（例：「お互いの PR を当日中にレビューする」）。

週ごとの傾向

（該当する場合、ステップ 10 より）

---

比較モード

ユーザーが retro compare（または retro compare 14d）を実行した場合：

1. --since="7 days ago" を使用して、現在の期間（デフォルトは 7 日間）の指標を計算します。
2. --since と --until の両方を使用して、直前の同じ長さの期間の指標を計算し、期間の重複を避けます（例：7 日間の期間では --since="14 days ago" --until="7 days ago"）。
3. 差分と矢印を含む、横並びの比較テーブルを表示します。
4. 最も大きな改善点と後退点を強調する簡潔な解説を書きます。
5. 現在の期間のスナップショットのみを .context/retros/ に保存します（通常の振り返り実行と同じです）。前の期間の指標は保存しないでください。

トーン

• 励ましを忘れず、率直に伝えます。過度に気を遣う必要はありません。
• 具体的に伝え、実際のコミットやコードを必ず根拠にします。
• ありきたりな称賛（「よくやりました！」など）は避け、何が良かったのか、その理由も明確に伝えます。
• 改善点は批判ではなく、さらなる成長につながる提案として伝えます。
• 称賛は、1対1の場で実際に伝えるような言葉にします。具体的で、努力に見合っており、心からのものにしてください。
• 成長に向けた提案は、投資のアドバイスのように伝えます。「失敗した」ではなく、「これに取り組む価値があるのは、……だからです」という形にします。
• チームメンバー同士を否定的に比較してはいけません。各メンバーのセクションは、それぞれ独立した内容にします。
• 出力全体は約3000～4500語を目安にします（チームのセクションに応じて、少し長くなっても構いません）。
• データには Markdown の表やコードブロックを使い、説明には文章を使います。
• 会話に直接出力します。ファイルシステムには書き込まないでください（例外は .context/retros/ の JSON スナップショットのみです）。

重要なルール

• 説明文はすべて、会話内でユーザーに直接伝えます。書き込むファイルは .context/retros/ の JSON スナップショットのみです。
• すべての Git クエリには origin/main を使います（古くなっている可能性のあるローカルの main は使わないでください）。
• 表示するすべてのタイムスタンプを太平洋時間に変換します（TZ=America/Los_Angeles を使用）。
• 対象期間のコミット数が 0 の場合は、その旨を伝え、期間を変更するよう提案します。
• LOC／時間は 50 単位で四捨五入します。
• マージコミットを PR の境界として扱います。
• リポジトリのドキュメントやその他のドキュメントは読まないでください。このスキルは自己完結しています。
• 初回実行時（過去の振り返りがない場合）は、比較セクションを適切に省略します。