pr-description-writer

PR 説明文作成スキル

このスキルは、整理された本番環境向けの Pull Request 説明文を Markdown 形式で作成します。

ユーザーは PR の背景（変更、バグ、機能、アーキテクチャなど）を提示します。このスキルは PR の種類を判定するか、ユーザーに確認して、適切なテンプレートを生成します。

---

PR の自動検出

何かを生成する前に、gh CLI を使用して、現在のブランチにすでにオープンな Pull Request が存在するか必ず確認します。

gh pr view --json number,title,url,body 2>/dev/null

• PR が見つかった場合は、その番号、現在のタイトル、URL、本文を確認します。オープンな PR が検出されたことをユーザーに伝え、PR の URL を表示します。
• PR が見つからない場合（コマンドがゼロ以外の終了コードを返した場合）は、この手順を省略し、通常どおり進めます。

この検出は自動で行います。確認するかどうかをユーザーに尋ねないでください。必ず確認してください。

---

PR の種類

対応している種類：

• issue
• feature
• big-feature

ユーザーが種類を指定しない場合は、どれを選ぶか尋ねてください。

---

全般的な文章作成ルール

• 英語で記述します。
• 簡潔で要点を明確にします。
• 汎用的な埋め草の文章は避けます。
• 変更内容だけでなく、理由と影響に焦点を当てます。
• 明確でプロフェッショナルな技術文書として記述します。
• マーケティング的な表現より、分かりやすい技術的な説明を優先します。

---

PR タイトルのルール

スキルは説明文より先に、必ず PR タイトルを生成します。

ルール：

• 簡潔で内容が分かるものにします。
• 意図と影響を反映し、変更内容だけにとどめません。
• 可能であれば、一般的な PR の形式を優先します。

例：

• fix(auth): prevent session reset on refresh
• feat(payments): add MercadoPago checkout support
• refactor(ui): migrate layout system to grid tokens

---

出力モード

このスキルは Markdown のみを生成します。

必ず次の内容を生成します。

• PR タイトル
• PR の説明文
• すべてを Markdown 形式で整形
• GitHub に手動でコピー＆ペーストできる状態

---

最終出力形式

# <PR Title>

<PR Description using the selected template>

---

Linear の課題／課題へのリンク

関連する課題（Linear、Jira、GitHub Issues など）があるか、必ず尋ねてください。

課題がある場合は、PR の説明文の先頭に次のセクションを追加します。

## Issue

[Issue link here]

課題がない場合は、このセクションを省略します。

---

テンプレート --- Issue

次の場合に使用します。

• バグ
• 修正
• リグレッション
• パフォーマンスの問題
• 技術的な修正

## Problem

<Explain the bug or problem clearly. What was happening? When did it occur?>

## Root Cause

<Explain the technical cause if known.>

## Solution

<Explain what was changed and why it fixes the problem.>

## Result

<Explain impact. Add demo links, videos, screenshots if available.>

---

テンプレート --- Feature（小規模／中規模）

次の場合に使用します。

• 通常の機能
• 改善
• 小規模な UX の追加
• アーキテクチャに関わらない変更

## Problem

<Explain the need, limitation, or missing capability.>

## Root Cause

<Optional. Only include if there was a technical limitation to solve.>

## Result

<Explain what the new feature enables and its impact.>

ルール：

• 機能の説明には Solution セクションを含めないでください。
• Root Cause は任意です。

---

テンプレート --- Big Feature

次の場合に使用します。

• 新しいシステム
• アーキテクチャの変更
• 大規模な UX フロー
• 新しいプラットフォーム機能
• 大規模なリファクタリング

### Summary

<High level explanation of what this PR introduces and why it matters.>

### Key Changes

- <Main change>
- <Main change>
- <Main change>

---

## Architecture Overview

### 1. Concept / Strategy

<Explain main architectural idea>

### 2. Implementation

<Folders, routing, state, patterns, infra, etc>

### 3. Components / Systems

<Main modules or domains involved>

### 4. Data / State Flow

<How data moves through the system>

### 5. Navigation / UX Flow

<If applicable>

### 6. Migration / Breaking Changes

<If applicable>

---

### Notes

<Tradeoffs, future improvements, known limitations>

---

出力の受け渡し

PR タイトルと PR の説明文を生成した後、出力をどのように受け取りたいか、必ずユーザーに尋ねてください。

現在のブランチでオープンな PR が検出された場合は、次の選択肢を提示します。

「オープンな PR を直接更新しますか、.md ファイルを生成しますか、それともここに表示しますか？」

選択肢：

• オープンな PR を更新する（PR が検出された場合に推奨）— gh pr edit を使用して、GitHub 上のタイトルと本文を直接更新します。
• チャットに表示
• .md ファイルを生成

オープンな PR が検出されなかった場合は、通常の選択肢を提示します。

「この内容を含む .md ファイルを生成しますか、それともここに表示しますか？」

選択肢：

• チャットに表示（デフォルト）
• .md ファイルを生成

---

オープンな PR の更新

ユーザーがオープンな PR の更新を希望した場合は、gh CLI を使用します。

gh pr edit <number> --title "<new title>" --body "<new body>"

ルール：

• ユーザーの明示的な確認なしに、PR を更新してはいけません。 必ず最初に AskUserQuestion で確認してください。
• <number> には、「PR の自動検出」手順で検出した PR の番号を指定します。
• <new title> には、生成した PR タイトルを指定します。
• <new body> には、生成した PR 説明文の本文（Markdown）を指定します。書式を保持するため、ヒアドキュメントを使って渡します。

gh pr edit <number> --title "<new title>" --body "$(cat <<'EOF'
<generated PR description body>
EOF
)"

• 更新が成功したら、ユーザーに完了を伝え、PR の URL を表示します。
• 更新に失敗した場合は、エラーを表示し、ユーザーが手動でコピー＆ペーストできるよう、チャットに出力を表示します。

---

Markdown ファイルのルール

ユーザーが .md ファイルをリクエストした場合：

• ファイルには次の内容を含める必要があります：
  • PR タイトルを H1 として記載
  • PR の説明本文
• Markdown 以外のテキストを追加しないでください
• ファイルはアップロードまたはコミットできる状態にしてください

---

動作ルール

このスキルを実行する際は：

1. 現在のブランチにオープンな PR があるか、gh pr view を使って事前に確認してください。これは自動で行います。確認するかどうかをユーザーに尋ねないでください。PR が見つかった場合は、PR の URL と番号をユーザーに知らせてください。

2. コンテキストから PR の種類を判定するか、ユーザーに選択してもらってください：

   • issue
   • feature
   • big-feature

3. 関連する Issue のリンクがあるか、必ず尋ねてください。

4. Issue がある場合は、先頭に Issue セクションを追加してください。

5. 次を生成してください：

   • PR タイトル
   • PR の説明（Markdown 本文）

6. 出力の受け渡し方法を尋ねてください：

   • オープンな PR が検出された場合：PR を直接更新する、チャットに表示する、または .md ファイルを生成する方法を提示してください。確認には AskUserQuestion を使用してください。
   • オープンな PR がない場合：チャットに表示するか、.md ファイルを生成する方法を提示してください。

7. ユーザーがオープンな PR の更新を選んだ場合は、生成したタイトルと本文を使って gh pr edit を実行してください。確認なしに実行してはいけません。

8. .md ファイルをリクエストされた場合は、そのままファイルとして使える Markdown の内容を生成してください。

---

品質基準

生成する PR の説明は次の要件を満たす必要があります：

• GitHub PR にコピーしてすぐ使える
• 技術的に正確
• 要点を把握しやすい
• レビュアーや将来のメンテナーにとって役立つ