pr-retro

このスキルは、メトリクスの整合性要件を伴う、読み取り中心の分析ワークフローです。

譲れないルール：

1. ブランチがフィーチャーブランチであり、ベースとの差分となるコミットが実際に存在することを確認します。
2. メトリクスは推測せず、必ず git データから算出します。
3. メトリクスの確認とセルフレビューをすべて完了してから、最終判定を下します。
4. コードと git の状態は読み取り専用にします。許可される書き込みは JSON スナップショットのみです。
5. 詳細なメトリクステーブル、スキャンパターン、JSON スキーマは、呼び出しごとに本文へ含めず、参照ファイルに置きます。

PR レトロスペクティブ

入力

• $request：--quick や --base <branch> などの任意のフラグまたは指示

目的

信頼できるブランチのレトロスペクティブを作成し、以下を行います。

• ブランチの実際の差分を測定する
• コントリビューターとホットスポットを特定する
• PR 前に残りがちな成果物をスキャンする
• 明示的なシグナルに基づいてマージ準備状況を評価する
• 必要に応じて .history/pr-retros/ に JSON スナップショットを保存する

ステップ 0：モードとブランチの範囲を確定する

以下を確認します。

• 標準モードか --quick か
• カスタムのベースブランチが指定されているか
• 現在のブランチ名
• ブランチがフィーチャーブランチか
• ベースとの差分となるコミットが存在するか

以下の場合は早期に終了します。

• main、master、または develop 上にいる
• ベースとの差分となるコミットがない

ベースブランチの解決ルールとモードの動作については、references/retro-metrics.md を使用します。

成功基準：レトロスペクティブのモードとレビューのベースが明確で、分析対象となる実際のブランチデータが存在すること。

ステップ 1：ブランチの生データを収集する

レトロスペクティブに必要な生の git データを収集します。

• 作成者とタイムスタンプを含むコミット一覧
• コミットごとの統計情報
• 機械可読形式の numstat
• 差分全体の統計情報
• ブランチの分岐情報

ルール：

• 説明文や推論より、生の git 出力を優先します
• 収集したデータから算出できないメトリクスがある場合は、その旨を明記します
• このステップを省略して、いきなり最終判定に進んではいけません

成功基準：以降のすべてのメトリクスを、収集したブランチデータから算出できること。

ステップ 2：ブランチのメトリクスを算出する

生データに基づき、ブランチの主要なメトリクスを算出します。

• コミット総数
• コントリビューター
• 変更ファイル数
• 追加行数
• 削除行数
• 差し引き LOC
• テスト LOC の比率
• PR の規模クラス
• ブランチの経過日数
• ベースとの差分
• 集中度スコア
• セッション数とタイムライン

--quick モードの場合は、ダッシュボード用メトリクスと最終判定の入力値を算出した時点で終了します。

以下については、references/retro-metrics.md を読み込みます。

• メトリクスの計算式
• PR の規模区分
• 集中度スコアのルール
• セッション検出ルール

成功基準：表示するすべてのメトリクスが、具体的な git データから算出されていること。

ステップ 3：コントリビューター、ホットスポット、衛生状態を分析する

ブランチの健全性を把握します。

• コントリビューターの内訳
• コミットタイプの分布
• ホットスポットとなるファイル
• WIP／fixup や内容の弱いコミットメッセージなどの衛生状態を示すシグナル

ルール：

• コミットの作成者への帰属は、ローカルの git 設定ではなくコミットデータに基づいて判断します
• Conventional Commits への準拠は、道徳的な評価ではなくメトリクスとして扱います
• ホットスポット分析はリスクの集中箇所を説明するために使い、それ自体でバグを示すものと解釈してはいけません

成功基準：誰が何を変更したか、またブランチの変更がどこに集中しているかを説明できていること。

ステップ 4：セルフレビューのスキャンを実行する

references/retro-metrics.md を使用して、ブランチの差分を以下の項目についてスキャンします。

• ハードコードされたシークレット
• .only テストマーカー
• コンフリクトマーカー
• デバッグ用ステートメント
• TODO または FIXME の残存物
• コメントアウトされたコード
• サイズの大きなファイルの追加
• バイナリファイル
• 注目すべき設定変更

ルール：

• 実際のシークレット値を出力に含めてはいけません
• BLOCK、WARN、INFO を区別します
• これは完全なセキュリティ監査ではありません。マージ準備状況を判断するための根拠として使用します

成功基準：マージ準備状況に影響するブランチの衛生上の問題を、レトロスペクティブに記録できていること。

ステップ 5：マージ可能性の判定

設定されたシグナルを評価します。

• 衛生状態
• サイズ
• テスト比率
• 焦点
• セルフレビューでの検出事項
• ドリフト

そのうえで、次のいずれかを出力します。

• GREEN
• YELLOW
• RED

GREEN ではないシグナルごとに推奨事項を生成します。

判定ルールとシグナルのしきい値については、references/retro-metrics.md を読み込みます。

成功基準：判定が文書化されたシグナルのルールに従っており、メトリクスから説明できること。

ステップ 6：出力をレンダリングしてスナップショットを保存する

ダッシュボードの概要は必ずレンダリングします。

標準モードでは、さらに次の項目もレンダリングします。

• 貢献者
• コミット種別の内訳
• ホットスポット
• セルフレビューでの検出事項
• 時間配分
• 推奨事項

標準モードでは、JSON スナップショットを次の場所に保存します。

• .history/pr-retros/<branch-slug>.json

--quick モードでは、スナップショットの保存を省略します。

次の項目については、references/retro-metrics.md を使用します。

• 出力セクション
• JSON スキーマ
• ブランチスラッグのルール

成功基準：振り返りの出力に矛盾がなく、適切な場合にのみスナップショットが書き込まれること。

ガードレール

• メトリクスを捏造しないでください。
• コードや git の状態を変更しないでください。
• disable-model-invocation を追加しないでください。このスキルは、ユーザーがブランチ分析を依頼したときに呼び出せる状態を維持してください。
• paths: を追加しないでください。これは汎用ワークフロースキルです。
• メトリクスの表、シグナルのしきい値、JSON スキーマを SKILL.md 内に記載しないでください。
• ブロッキングする検出事項がある場合、判定を GREEN にしないでください。

参照資料を読み込むタイミング

• references/retro-metrics.md メトリクスの計算式、シグナルのしきい値、セルフレビューのスキャンパターン、出力レイアウト、JSON スナップショットのスキーマに使用します。

出力契約

次の項目を報告します。

1. ブランチとベース
2. ダッシュボードの主要なメトリクス
3. 全体判定とシグナルごとのステータス
4. 注目すべき検出事項と推奨事項
5. 保存した場合はスナップショットのパス、またはクイックモードで省略したことの明示