What is pr-onboarding?

The PR Onboarding skill automates the generation of high-quality, structured Pull Request descriptions that act as a 'contract of change.' By analyzing code diffs and design intent, it ensures reproducibility of understanding, identifies potential failure modes, and clarifies the blast radius of changes, significantly reducing technical debt and accelerating the code review process.

When should I use pr-onboarding?

pr-onboarding is useful in the following scenarios: • Automating the creation of comprehensive PR descriptions that include the 'Why' (design intent), 'What' (behavioral changes), and 'Alternatives' to save developer time. • Performing impact analysis (Blast Radius) to identify how code changes affect dependencies, external interfaces, and backward compatibility. • Defining 'Invariants' and 'Failure Modes' to provide reviewers and incident responders with clear signals on how the system might break and how to monitor it. • Streamlining the review workflow by highlighting specific files for focus and providing structured evidence of testing and verification. • Maintaining documentation consistency by identifying necessary updates to technical docs (DocDD) based on the current code changes.

name	pr-onboarding
description	\|

PR Onboarding

PR作成時に「説明」ではなく「変更の契約」を記述し、理解負債の蓄積を防ぐ。

目的

PRオンボーディングの目的は、以下3つを同時に成立させること:

理解の再現性: 他者が同じ理解に到達できる
反証可能性: 正しさの根拠（テスト・観測・仕様）が提示され、間違いなら突ける
運用可能性: 壊れたときに検知でき、戻せる（戻せないなら明記）

合格条件（PR Onboarding Done）

PR本文（＋リンク先）を読むだけで、レビューアが以下を答えられる状態:

#	項目	内容
1	What	何が変わったか
2	Why	なぜそう変えたか（代替案含む）
3	Invariants	何を壊してはいけないか
4	Blast Radius	どこに影響するか（境界・波及）
5	Failure Modes	どう壊れうるか
6	Evidence	どう確かめたか（検証・根拠）
7	Rollback	どう戻すか（または戻せない条件）

ワークフロー

1. 契約確立 → 2. 変更理解 → 3. 意図抽出 → 4. 境界特定 → 5. 不変条件 → 6. 失敗モード → 7. 検証証拠化 → 8. リリース戦略 → 9. レビュー誘導 → 10. DocDD同期 → 11. 不確実性管理

入力（AIに渡すもの）

PR差分（diff）と変更ファイル一覧
関連チケット/設計ID（あれば）
テスト結果（CIログ or 実行コマンド）
DocDDの正本リンク（あれば）

Step 1: オンボーディング契約の確立

PR本文が長文化・散逸しないよう、"出力の契約"を確立。

出力:

PR本文に載せる項目（中核6〜8項目）
詳細はリンクに逃がす方針（1〜2画面制限）

Step 2: 変更の意味理解

行数差分ではなく、振る舞い・責務・契約の変化を抽出。

出力:

変更の中心（トップ3）
"振る舞いが変わった点"と"変わっていない点"

Step 3: 目的・意図の抽出

Why（設計意図）を、作文ではなく意思決定の記録として残す。

出力:

目的（Goal）
採用理由（Reason）
捨てた代替案（Alternative）と棄却理由

Step 4: 境界と波及（Blast Radius）の特定

出力:

影響範囲（呼び出し元/先、データ、外部I/F）
互換性（後方互換が壊れる条件、移行の必要性）

Step 5: 不変条件の抽出と明文化

出力:

Must stay true（最大3つ）
破ったときの症状

Step 6: 失敗モード分析

出力:

壊れ方トップ3（起きやすい/致命的/気づきにくい）
各壊れ方に検知手段を紐づけ

Step 7: 検証の証拠化

出力:

実施した検証（自動/手動）
再現手順（必要なら）
根拠リンク

Step 8: リリース戦略

出力:

ロールアウト手順
ロールバック手順
ロールバック不能条件（あれば）

Step 9: レビュー誘導

出力:

レビュー観点
重点ファイル（最大3〜5）
議論すべき論点

Step 10: DocDD同期

出力:

参照した正本へのリンク
更新が必要なドキュメントの指摘
更新内容の差分案

Step 11: 不確実性管理

出力:

未確定事項リスト（最大5）
解消手段
マージ条件 or フォローアップの区別

ガードレール（絶対禁止事項）

根拠なしの断言: もっともらしい説明ほど危険
未実施の検証の捏造: 信用を一撃で破壊する（最重要）
長文化で安心させる: 読み手の注意を散らし重要点が埋もれる
影響範囲の過小評価: 特にデータ、権限、外部I/F、並行性
"問題ないはず"の楽観: 不確実なら不確実として扱い検証へ落とす

詳細は references/guardrails.md を参照。

スキル詳細

各ステップの詳細な実行方法と品質ゲートは references/skills-catalog.md を参照。

評価ルーブリック

PRオンボーディングの品質評価基準は references/evaluation-rubric.md を参照。

PR本文テンプレート（出力例）

## Summary
[変更の中心を1〜3文で]

## Why
- **Goal**: [目的]
- **Reason**: [採用理由]
- **Alternatives**: [検討した代替案と棄却理由]

## What Changed
- [振る舞いが変わった点1]
- [振る舞いが変わった点2]

## Blast Radius
- **Affected**: [影響範囲]
- **Compatibility**: [互換性への影響]

## Invariants (Must Stay True)
| 条件 | 根拠 | 破ったときの症状 |
|------|------|-----------------|
| [条件1] | [コード/テスト] | [症状] |

## Failure Modes
| 種類 | パターン | 検知手段 |
|------|---------|---------|
| 起きやすい | [説明] | [テスト/ログ] |
| 致命的 | [説明] | [テスト/ログ] |
| 気づきにくい | [説明] | [テスト/ログ] |

## Evidence
- [x] 自動テスト: `npm test` 全パス
- [x] 手動検証: [手順]
- 根拠: [リンク]

## Rollout & Rollback
- **Rollout**: [手順]
- **Rollback**: [手順]
- **Cannot rollback if**: [条件があれば]

## Review Focus
- [ ] [重点ファイル1]: [観点]
- [ ] [重点ファイル2]: [観点]

## Unknowns
| 項目 | 解消手段 | ブロッカー? |
|------|---------|-----------|
| [未確定事項] | [手段] | Yes/No |

## Related
- Issue: #XXX
- Docs: [リンク]

pr-onboarding

When & Why to Use This Skill

Use Cases