issue

イシュー

ユーザーの説明から tldraw/tldraw に GitHub イシューを作成し、その後ユーザーに問いかけて、イシューに取り組めるだけの意図を十分に引き出します。

イシューのタイトル、本文、種類、ラベル、トリアージの規約については、../write-issue/SKILL.md を標準のリファレンスとして使用してください。

目標は、コードベースを徹底的に調査することではありません。ユーザーの意図とコンテキストをイシューに完全に記録し、後でそれを引き継ぐ人（または何か）が必要な情報を持てるようにすることです。そのために、イシューをすぐに作成し、問題の簡単な読み戻しを書き、その後、その理解を鋭くするような質問をユーザーに投げかけます。

イシュー本文の形

本文は常に、ユーザーの元の説明をそのままの形で、人間の絵文字で注釈を付け、水平線で残りの部分と区切ったものから始まります:

🗣️: {user_description}

---

{two to five sentences that read back your understanding of the problem, expected behavior, and scope}

## Open questions

1. **{question}**
   _Awaiting answer._
2. **{question}**
   _Awaiting answer._

Confidence: {n}%, {ready_status}.

• 読み戻しの段落は、エージェントが問題をどう理解したかです。ユーザーがすばやく修正できる程度に短く、しかし意図する動作が明確になる程度に具体的である必要があります。製品志向で保ち、コードブロックや長い実装分析、行ごとの診断は含めないでください。
• デフォルトでは、イシュー本文に実装の手がかりを含めないでください。ユーザーが明示的に含めるよう求めない限り、ファイルパス、関数名、行番号、コードスニペット、考えられる原因、修正レシピは避けてください。作業を引き継ぐ人は、その技術的なコンテキストを再発見できます。
• コードの診断よりも製品の意図を優先してください。イシューには、ユーザーが何を望んでいるか、何を観察したか、どのようなスコープや動作を確認したかを記録する必要があります。ユーザーがその捉え方を確認していない限り、根本原因や修正の方向性を事実として提示しないでください。
• 各未解決の質問は、意図またはコンテキストの特定のギャップを対象とします。コードを見れば自分で答えられる質問は避けてください。
• 質問はアトミックに保ってください。ユーザーの意図に関する質問と、実装者が検証できる技術的な確認をまとめないでください。ユーザーが複合的な質問の一部にしか答えない場合、残りの部分が依然としてユーザーの意図やコンテキストを必要とするときにのみ、未解決のままにしてください。
• 実装者が検証できる不明点は、ユーザーに確認を求めるよりも省略することを優先してください。ユーザー自身のコンテキストや意図が重要である場合にのみ尋ねてください。
• 質問が本当にブロッキングである場合 — それが答えられるまでイシューにまったく取りかかれない場合 — にのみ、太字の内側で質問の前に Critical: を付けます（例: **Critical: Which package should we rename?**）。ほとんどのイシューにはこれがありません。通常のギャップを critical に誇張しないでください。
• ユーザーが答えるにつれて、_Awaiting answer._ をその回答（軽く整えたもの）に置き換えて質問のすぐ下に置き、読み戻しを修正し、必要に応じて未回答の質問を追加または削除します。
• ユーザーが critical でない質問に答えることを選ばない場合、_Awaiting answer._ を _Deferred by user; not blocking implementation._ に置き換えます。critical な質問にはこれを使用しないでください。
• 信頼度の行は、セクションではなくプレーンテキストのステータス行です。これは、イシューが取り組めるだけのユーザーのコンテキストと意図を十分に含んでいるかどうかを反映するものであり、最終的な修正への信頼度ではありません。ready to get started、still need more information、blocked on a critical question などの短いステータス表現を使用してください。

ワークフロー

1. コンテキストを収集します:
   • ユーザーの問題の説明。
   • 現在のブランチ: git branch --show-current。
   • 最近のイシュー: gh issue list --repo tldraw/tldraw --limit 5 --json number,title --jq '.[] | "#\(.number) \(.title)"'。
2. 実装の調査ではなく、軽量なトリアージチェックを行います:
   • 重複した、または密接に関連するイシューを探します。
   • リポジトリのコンテキストは、イシューの種類、ラベル、マイルストーン、および影響を受けるおおまかな領域を選ぶためにのみ使用します。
   • 悪い質問を避けるために浅いコード検索が必要な場合は行いますが、ファイルパス、関数名、行番号、コードスニペット、考えられる原因、修正方法をイシュー本文に追加しないでください。
   • リポジトリのコンテキストから自分で答えられることは、未解決の質問にしてはいけません。
3. 視覚的なバグについては、可能な場合は再現対象を特定します:
   • Examples アプリ: pnpm dev で localhost:5420。
   • tldraw.com アプリ: pnpm dev-app で localhost:3000。
   • ドキュメントサイト: pnpm dev-docs で localhost:3001。
   • ユーザーが画像を提供し、そのパスまたは URL がある場合は、GitHub イシューに埋め込むか添付します。
   • 画像がチャット内でのみ表示され、添付できない場合は、視覚的なコンテキストとして説明します。イシューに実際に画像が含まれていない限り、「スクリーンショットを添付しました」と書かないでください。
   • スクリーンショットが有用であってもローカルでは実現できず、ユーザーが提供していない場合は、未解決の質問の 1 つとしてスクリーンショットの依頼を入れてください。
4. ../write-issue/SKILL.md を使用して、イシューのタイトルと本文を書きます。本文は上記の構成に従います: そのままの説明、読み返しの段落、未解決の質問、および確信度ステータス行。
5. イシューを作成します:

gh issue create --repo tldraw/tldraw --title "..." --body "..."

6. イシューの種類 (Bug、Feature、Example、または Task) を設定します — gh issue create --type は信頼できないため、スクリプトを使用します:

skills/issue/scripts/set-issue-type.sh <issue-number> <type-name>

7. 明確に適合する場合にのみマイルストーンを割り当てます:
   • 例、ドキュメント、コメント、スターターキット、npm create tldraw には Improve developer resources。
   • GitHub Actions、レビューボット、CI/CD、自動化作業には Improve automations。
8. More Info Needed ラベルを一貫して管理します:
   • 重要な質問が未回答である場合、または確信度の行でイシューにまださらに情報が必要とされている場合にのみ追加します。
   • たとえブロッキングではない考慮事項が残っていても、イシューを開始できる状態になったら削除します。
9. ユーザーにイシューの URL、読み返し、および未解決の質問のリストを返信します。重要な質問を最初に示して、直接尋ねてください。
10. ユーザーに問いただします。各返信の後:

• イシュー本文を更新します: 該当する質問の下にユーザーの回答を書き、読み返しを修正し、確信度ステータス行を再計算し、回答によって新たな不足が明らかになったり古いものが解消されたりしたら質問を追加または削除します。
• 新しいコンテキストに照らしてイシューの枠組みを再検討します。回答によってイシューの実際の内容が変わる場合は、タイトル (gh issue edit --title)、イシューの種類 (手順 6 のスクリプト)、またはラベルを一致するように更新します — たとえば、報告されたバグが機能リクエストであることが判明した場合や、実際の問題がタイトルが示すよりも狭い場合などです。
• ユーザーがあなたの枠組みを訂正した場合、特に「actually」や「well actually」のような表現を伴う場合は、訂正された区別を中心に読み返しを書き直す合図として扱います。さらに質問する前に、古くなった前提を削除または弱めてください。

gh issue edit <issue-number> --repo tldraw/tldraw --body "..."

• ユーザーの意図とコンテキストが、作業を進められるだけ十分に読み返しと回答に含まれるまで、1ラウンドずつ続けてください。

11. 重大な質問が未回答のままになっておらず、作業を進められるだけのユーザーの意図が含まれていれば、そのissueは準備完了です。他の部分がどれほど完全であっても、重大な質問が未解決のうちは、準備完了と宣言しないでください。

• ユーザーが先送りすることを選んだ優先度の低い質問は、未解決のままでかまいません。準備完了にそれらへの回答は必要ありません。それらは _Awaiting answer._ プレースホルダーのままにせず、_Deferred by user; not blocking implementation._ としてマークしてください。
• 準備が整ったら、More Info Needed ラベルを削除し、そのissueに取りかかれることをユーザーに伝え、信頼度の行をそれに応じて設定します。例: Confidence: 84%, ready to get started. 読み返し、すべての質問、信頼度の行は、議論の記録としてissueに残してください。それらを削除しないでください。

ルール

• ユーザーへの問い合わせの前に、必ずissueを作成してください。そうすればユーザーは最初の返信からそれを追跡できます。
• ユーザーの意図やコンテキストを捉える質問だけをしてください。自分でできる作業をユーザーに押し付けないでください。
• 回答を最後にまとめてではなく、返信ごとにissueを更新してください。