positron-issue-creator

Positron のイシュー作成

目的

このスキルは、Positron IDE リポジトリ向けに質の高い GitHub イシューを作成する方法を説明します。以下を確実にします。

• 作成前に重複がないか十分に確認する
• 効率的なトリアージのために適切なラベルを付ける
• 完全かつ具体的な情報を記載する
• 不必要な冗長表現や埋め草を避ける
• 開発チームが対応できる内容にする
• ユーザーが手動で送信できる状態にする

このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• ユーザーがイシューの作成、起票、報告を明示的に依頼した場合
• ユーザーが、追跡すべきバグや機能リクエストについて説明した場合
• ドキュメントや改善に関するリクエストの草案を作成する場合
• ユーザーが「〜のイシューの草案を作ってくれる？」などと依頼した場合

次の場合にはこのスキルを使用しないでください。

• 受付ローテーションの業務（代わりに positron-intake-rotation を使用してください）
• 既存のイシューへの返信
• Positron の一般的な開発タスク

GitHub アクセスポリシー

読み取り操作（許可）：

• gh CLI を使った既存のイシューやディスカッションの検索
• gh CLI を使ったリポジトリのラベルの取得
• 重複確認のためのイシュー詳細の表示
• 公開リポジトリ情報の閲覧

書き込み操作（禁止）：

• gh issue create によるイシューの直接作成
• イシューへのコメント
• 既存のイシューのラベルの変更
• その他の GitHub への書き込み操作

代わりに： 手動でユーザーが送信できるよう、Markdown ファイルまたはクリップボードに貼り付けられる形式でイシューを準備します。

基本的なワークフロー

重要： このスキルでは、手動で送信するイシューを準備します。GitHub のイシューを自動作成することはありません。GitHub への送信は、引き続きユーザーが完全に管理します。

イシュー作成の依頼ごとに、次のワークフローに従ってください。

1. 必要なコンテキストをすべて収集する

草案の作成を始める前に、必要な情報がすべて揃っていることを確認します。必要に応じて、質問を重ねて情報を集めてください。

バグ報告で確認する情報：

• Positron のバージョン（［ヘルプ］>［バージョン情報］または特定のビルド番号）
• オペレーティングシステムとバージョン
• セッションの詳細（R／Python のバージョン）
• 再現手順の正確な内容
• 期待される動作と実際の動作
• エラーメッセージ（UI、［出力］パネル、または開発者コンソールから）
• 該当する場合はスクリーンショット

機能リクエストで確認する情報：

• 希望する機能の明確な説明
• ユースケース（必要な理由、解決する問題）
• 提案する動作（どのように動作すべきか）
• 関連するイシューや、他のツールでの例

情報が不足している場合は、具体的な質問をしてください。

• 「使用している Positron のバージョンを教えてください。［ヘルプ］>［バージョン情報］で確認できます」
• 「表示された正確なエラーメッセージを教えてください」
• 「期待した動作と、実際に起きた動作を教えてください」
• 「再現するための具体的な手順を教えていただけますか？」

決して推測しないでください。 不明な点があれば、推測するのではなく質問してください。

2. 重複を検索する

scripts/search_duplicates.sh を使って、既存のイシューやディスカッションを検索します。

cd /path/to/positron/.claude/skills/positron-issue-creator
./scripts/search_duplicates.sh "keywords from issue"

検索結果を慎重に確認します。

• オープンとクローズ済みの両方のイシューを確認する
• ディスカッションも確認する
• 検索語のさまざまな表現を検討する

検索結果をユーザーに提示します。

• 関連する可能性のあるイシューをすべて表示する
• 非常によく似ていると思われるものを強調する
• 重複しているかどうかをユーザーに確認する
• 該当するか判断が難しい場合は、「これは #1234 と同じイシューですか？」と明確に尋ねる

重複が見つかった場合：

• そのイシューがすでに存在することをユーザーに伝える
• 既存のイシューへのリンクを提示する
• 追跡したい場合は、コメントまたは 👍 リアクションの追加を提案する
• 新しいイシューは作成しない

重複が見つからなかった場合：

• イシューの草案作成に進む
• 関連するイシューがあれば、草案内で参照する

3. 適切なラベルを選択する

scripts/fetch_labels.sh を使用して、リポジトリの最新のラベルを取得します。

cd /path/to/positron/.claude/skills/positron-issue-creator
./scripts/fetch_labels.sh

次の基準でラベルを選択します。

エリアラベル（1～2 個選択）：

• area: console - コンソール／REPL の機能
• area: notebook - Jupyter ノートブックとの統合
• area: editor - テキストエディターの機能
• area: plots - プロットビューアーと可視化
• area: data-explorer - データビューアーとデータエクスプローラー
• area: connections - データベース接続
• area: help - ヘルプペインとドキュメント
• area: ui - 一般的な UI／UX の問題
• すべての選択肢を確認するには、fetch_labels.sh の全リストを確認してください

種別ラベル（1 つ選択）：

• Bug - 想定どおりに動作しないもの
• Feature Request - 新しい機能または機能強化
• Documentation - ドキュメントの改善
• Performance - 動作するものの、速度が遅すぎるもの

その他の考慮事項：

• 優先度ラベルは追加しないでください（トリアージ時に設定します）
• ステータスラベルは追加しないでください（チームが設定します）
• 問題が複数のコンポーネントにまたがる場合、複数のエリアラベルを付けてもかまいません

4. Issue の下書きを作成する

references/issue_templates.md のテンプレートを出発点として使用し、個別の Issue に合わせて調整してください。

必要に応じてテンプレートを読み込みます。

• バグ報告：バグ報告の構成を参照
• 機能リクエスト：機能リクエストの構成を参照
• 複合的なケース：適切に調整

references/writing_guidelines.md の文章作成ガイドラインに従います。

基本原則：

1. 簡潔にする - すべての語句に目的を持たせます
2. 無駄を省く - 謝罪、前置き、不要な丁寧表現は入れません
3. 具体的にする - 正確なバージョン、明確な手順、具体的な詳細を記載します
4. 要点を述べる - すぐに本題に入ります

タイトルのガイドライン：

• バグ：[Component] fails when [condition]
• 機能：Add [feature] to [component]
• 内容をすべて伝える完全な文章にします
• ひと目で内容がわかり、検索しやすいものにします

本文の構成：

1. 内容 - Issue 自体（1 文）
2. 理由 - 影響や背景（明らかでない場合は1～2文）
3. 方法 - 手順または提案する解決策（箇条書き）
4. 詳細 - システム情報、エラー、スクリーンショット（必要に応じて）

バグ報告の例：

Title: Console freezes when printing dataframes with 100k+ rows

The console becomes unresponsive when printing large dataframes.

## Steps to reproduce

1. Create dataframe: `df = pd.DataFrame({'a': range(100000)})`
2. Print it: `print(df)`
3. Console freezes, UI becomes unresponsive

## System details

- Positron 2024.10.0 Build 123
- macOS 14.5
- Python 3.11.6

## Error messages

Developer Console shows: "Maximum call stack size exceeded"

機能リクエストの例：

Title: Add keyboard shortcut to insert markdown cell in notebooks

Currently inserting markdown cells requires clicking the dropdown menu.
Keyboard shortcut would improve notebook authoring workflow.

## Proposed behavior

- Add keyboard shortcut (e.g., Cmd+M or Ctrl+M)
- Should work when focus is in notebook
- Should insert cell below current cell

## Context

Similar to Jupyter's 'M' key in command mode. Notebook workflows
frequently alternate between code and markdown cells.

避けるべきよくあるアンチパターン：

• 不要な背景説明や前置き
• 曖昧な説明（「動作しない」「ときどきクラッシュする」）
• 無関係な複数の問題をひとつにまとめる
• 謝罪や過度に丁寧な表現
• 具体的な詳細（正確なバージョン、エラーメッセージ）の欠落
• 簡潔に説明できる内容を冗長に説明すること

提示する前のレビューチェックリスト：

• タイトルが完全かつ具体的である
• 本文が中心的な問題から始まっている
• 再現手順が明確である（バグの場合）
• システムの詳細が含まれている（バグの場合）
• エラーメッセージが正確に引用されている
• 不要な冗長表現がない
• すべての文に価値がある
• 焦点がひとつのトピックに絞られている
• 適切なラベルが選択されている

5. 下書きをユーザーに提示する

次の内容を含む、作成した Issue の完全な下書きを表示します。

• タイトル
• 本文全体
• 提案するラベル

ユーザーに「これで問題の内容を正確に表せていますか？作成する前に変更しますか？」と尋ねます。

修正に対応します。

• ユーザーが表現の調整を希望する場合があります
• 追加の詳細を思い出す場合があります
• 別の側面を強調したい場合があります

依頼された変更を加え、更新した下書きを表示します。

6. 手動で投稿するための Issue を準備する

ユーザーが下書きを承認したら、どのように利用するかを選べるようにします。

ユーザーに尋ねます。「この Issue をどのように準備しますか？」

• オプション 1： Markdown ファイルに保存する
• オプション 2： クリップボード用に整形する（コピーできるテキストを提示）

オプション 1：Markdown ファイルに保存する

Issue の詳細をすべて含む Markdown ファイルを作成します。

# Create file with timestamp in name for uniqueness
cat > "positron-issue-$(date +%Y%m%d-%H%M%S).md" <<'EOF'
---
title: Issue title here
labels: area: console, Bug
repository: posit-dev/positron
---

Full issue body here
with multiple lines
EOF

保存後：

• ファイルのパスを表示します
• GitHub で Issue を手動で作成するようユーザーに伝えます
• 次のクイックリンクを提示します：https://github.com/posit-dev/positron/issues/new

オプション 2: クリップボード用にフォーマットする

問題をコピーできる形式で提示します:

**Title:**
Issue title here

**Labels:**
area: console, Bug

**Body:**
Full issue body here
with multiple lines

---
Create this issue at: https://github.com/posit-dev/positron/issues/new

提示した後:

• ユーザーがこのテキストをコピーすべきであることを説明する
• GitHub の新しい issue フォームに貼り付けるよう促す
• UI でラベルを手動で選択する必要があることに言及する

重要なガイドライン

重複の検出

徹底的に、ただし細かすぎないように:

• 複数のキーワードの組み合わせで検索する
• issue とディスカッションの両方を確認する
• クローズされた項目も確認する(修正済みまたは wontfix の可能性がある)

判断に迷う場合:

• 類似している可能性のある issue をユーザーに示す
• 明確に尋ねる: 「これはあなたが報告している内容と同じですか?」
• 誤って重複としてマークするよりも、新しい issue を作成する side に倒す

コンテキストの収集

決して推測したり仮定したりしない:

• バージョンが不明確な場合は、具体的に尋ねる
• 手順が曖昧な場合は、明確化を求める
• エラーメッセージが言い換えられている場合は、正確なテキストを求める

反復に対して忍耐強く:

• ユーザーがすぐにすべての情報を持っていない場合がある
• 詳細を得るために問題を再現する必要がある場合がある
• 不完全な issue を作成するよりも、複数の質問をする方が良い

文体

読み飛ばしやすさを最適化する:

• 忙しい開発者は issue を素早く理解する必要がある
• 最も重要な情報を最初に置く
• フォーマット(見出し、リスト、コードブロック)を適切に使用する

読み手の時間を尊重する:

• 「ご報告ありがとうございます」以上の不要な挨拶は不要
• 謝罪的な言葉遣いは不要
• マーケティング的な表現や熱意は不要
• ただ明確で事実に基づいた情報のみ

正確に:

• 「最新」や「最近」ではなく、正確なバージョンを使用する
• エラーメッセージを正確に引用する
• 手順を明確に番号付けする
• 解釈ではなく、実際の動作を記述する

特殊なケース

セキュリティ問題

ユーザーがセキュリティ脆弱性を説明した場合:

1. 公開 issue を作成しないこと
2. ユーザーに伝える: 「これはセキュリティ問題のようです。公開 issue を作成するのではなく、[email protected] に非公開で報告してください」
3. issue の作成を進めないこと

ドキュメントの問題

機能リクエストとして扱いますが、以下に焦点を当てます:

• どのドキュメントが欠けているか、または誤っているか
• ユーザーがこの情報をどこで探すか
• 改善の提案

Documentation タイプでラベル付けします。

パフォーマンスの問題

バグレポートテンプレートを使用しますが、以下を強調します:

• どの操作が遅いか
• 期待される時間と比較してどのくらいかかるか
• ハードウェアを含むシステムの詳細
• データサイズまたは複雑さ

Performance タイプでラベル付けします。

複数の関連する issue

ユーザーが関連するが別個の複数の issue を説明した場合:

1. それぞれの別個の issue を特定する
2. ユーザーに説明する: 「これは3つの別個の issue のようです。それぞれ個別に作成するお手伝いをします。」
3. 一度に1つずつ issue を作成する
4. 関連している場合は、issue 本文で相互参照する

スクリプトリファレンス

scripts/fetch_labels.sh

分類のためにリポジトリのすべてのラベルを取得します。

使用法:

./scripts/fetch_labels.sh          # Human-readable output
./scripts/fetch_labels.sh --json   # JSON output for parsing

scripts/search_duplicates.sh

重複の可能性がある issue とディスカッションを検索します。

使用法:

./scripts/search_duplicates.sh "search terms"
./scripts/search_duplicates.sh "search terms" --limit 30

戻り値:

• 一致する issue(オープンおよびクローズ)
• 関連するディスカッション
• 確認用の直接リンク

リファレンス

issue を起草する際に、以下のリファレンスドキュメントを読み込みます:

• references/issue_templates.md - バグ、機能、ハイブリッド issue のテンプレート
• references/writing_guidelines.md - 詳細な執筆ガイダンス、アンチパターン、例

避けるべきよくある間違い

1. 重複した issue の作成 - 常に最初に検索し、結果をユーザーに示す
2. 不完全な情報 - すべての詳細が揃うまで質問する
3. 冗長な文章 - 無駄をすべて削ぎ落とし、直接的かつ具体的に
4. 曖昧なタイトル - タイトルは全体像を伝えるべき
5. 1つに複数の issue - 別個の焦点を絞った issue に分割する
6. コンテキストの仮定 - 不明確な詳細はユーザーに確認する
7. ラベルの省略 - 常に適切なラベルを取得して適用する
8. ユーザーの承認なしに準備する - ファイルを準備する前に、常に下書きを示して確認を得る

成功基準

問題のドラフトが成功したと判断できる条件：

• 重複がない（またはユーザーが別の問題であることを確認している）
• 必要な情報がすべて含まれている
• 問題の内容が簡潔で、余計な情報がない
• タイトルが問題を正確に要約している
• 適切なラベルが特定されている
• ユーザーがドラフトを承認している
• ユーザーの希望する形式（Markdown ファイルまたはクリップボードのテキスト）で問題が用意されている
• GitHub に手動で送信するための手順がユーザーに明確に伝わっている

ワークフローの概要

1. Gather Context
   ↓
   Ask specific questions until all info available
   ↓
2. Search Duplicates
   ↓
   Run scripts/search_duplicates.sh
   ↓
   Show results to user, confirm not duplicate
   ↓
3. Select Labels
   ↓
   Run scripts/fetch_labels.sh
   ↓
   Choose appropriate area and type labels
   ↓
4. Draft Issue
   ↓
   Use templates from references/
   ↓
   Follow writing guidelines (terse, specific, direct)
   ↓
5. Present Draft
   ↓
   Show complete draft to user
   ↓
   Iterate based on feedback
   ↓
6. Prepare for Submission
   ↓
   Offer markdown file or clipboard format
   ↓
   Save to file OR format for copying
   ↓
   Provide GitHub link and submission instructions

目標は、報告者の意図と開発チームの時間の両方を尊重した、明確で実行可能な問題のドラフトを作成することです。GitHub への最終的な送信は、すべてユーザーが管理します。