to-tickets

チケット化

承認済みの作業を、内容を絞った GitHub チケットにします。実装担当者が読むのは各チケットだけなので、タスク全体、「完了」の定義、作業を止めて確認を求めるタイミングをすべて記載する必要があります。

このスキルの実行で許可されるのは、ドラフトの作成のみです。手順 4 でユーザーがドラフトを承認するまで、GitHub には何も書き込みません。

ルール

• ユーザー、資料、リポジトリに記載されている内容だけを使用します。要件、優先度、ラベル、関連性、承認手順を作り上げないでください。
• 判断、制約、根拠、エッジケース、調査結果を、実装担当者が再調査しなくて済むだけの詳細さで引き継ぎます。具体的な制約は具体的なまま記載します。「カプセル型のボタンは使わない」は、「ありきたりな見た目を避ける」のように言い換えず、そのまま記載します。
• 確認済みのコードの場所は、作業範囲ではなく着手時の参考箇所として記載します。
• 「慎重に考える」や「徹底する」といった指示は省きます。
• ユーザーから依頼がない限り、元の課題や親課題を編集またはクローズしないでください。

1. コンテキストを収集する

資料と、チケットの内容を正確にするために必要なコードを読みます。回答によってチケットの要件、作業の分割方法、または順序が変わる場合に限り、質問してください。

ユーザーまたはローカルのリモートから対象リポジトリを HOST/OWNER/REPO として特定し、GitHub の読み取りと書き込みにはすべてそのホストを使用します。

プルリクエストのフィードバックについては、python3 "<skill-path>/scripts/fetch_review_context.py" またはコネクターを使ってスレッドを取得し、未解決のスレッドを現在のコードと照合して、まだ対応が必要な懸念だけをチケット化します。

リポジトリのラベル一覧を確認し、名前だけでなく説明と過去の使用例から意味を把握します。ユーザーまたはリポジトリに別の指示がない限り、そのリポジトリで通常使われているセットアップを備えたエージェントがチケットを実装すると想定します。

2. 重複を確認する

予定している成果ごとに、平易な言葉で検索し、オープンとクローズ済みの課題を確認します。タイトルではなく、目的と範囲を比較します。重複の可能性が高い課題は、URL と重複する内容を添えて報告します。承認なしに、既存の課題を変更または再利用しないでください。検索に失敗した場合は、検索が成功するか、ユーザーが検索なしで進めるよう指示するまで、何も作成しないでください。

3. チケットのドラフトを作成する

作業を分割する

作業全体をひとまとまりとしてレビューでき、有用な成果が 1 つ得られる場合は、1 つのチケットにまとめます。各部分を独立して完了できる場合、別の担当者が必要な場合、または実際のリスクを避けるために順番に進める必要がある場合に限り、分割します。機能のチケットには、その機能に必要なすべての層を含めます。

別のチケットがないと完了できない場合に限り、そのチケットによってブロックされると記載します。望ましい順序であることは、ブロックの理由にはなりません。呼び出し元を一度にすべて変更できないインターフェースを置き換える場合は、新しいインターフェースの追加、呼び出し元の移行、古いインターフェースの削除を順番に行うチケットを作成します。

ユーザーが調査を求めた場合に限り、調査チケットを作成します。チケットをまとめるためのトラッキング課題やエピック課題は作成せず、ユーザーまたはリポジトリの慣例で必要な場合に限り、既存の親課題にチケットを紐づけます。

人が行う作業を分ける

判断、承認、人による対応が必要な作業は、完了を明確に確認できる条件と、リポジトリで使われている人手作業用のラベルを付けて、それぞれ専用のチケットにします。エージェントが操作できるインターフェースであっても、この作業の担当者は人です。通常のプルリクエストレビューをチケットにしないでください。

• 実装に先立って必要な人の対応がある場合、実装チケットはその対応によってブロックされます。
• 完了した作業に対する人の承認は、実装チケットによってブロックされます。実装チケットの完了条件に、その承認を含めてはいけません。
• 展開前に承認が必要な場合、展開作業はその承認によってブロックされます。

各チケットを作成する

議論を追っていない開発者にも伝わるように書きます。ファイル、コマンド、API など、正確な名称を示す場合を除き、簡単で日常的な言葉を使います。

タイトル：チケットを開かなくても理解できる、成果を簡潔に表した言葉にします。たとえば「Webhook の改善」ではなく、「失敗した Webhook 配信をバックオフ付きで再試行する」とします。

本文は次の順序で記載します。

## Summary

Two to four sentences: what needs to change, why, and who is affected. A reader who stops here should know what the ticket asks for.

## Current behavior

What happens today, or the research findings for new work. Keep verified facts apart from guesses.

## Desired outcome

The behavior when the work is done. State confirmed requirements as requirements and optional ideas as tradeoffs. Do not prescribe implementation the source has not decided.

## Acceptance criteria

Plain bullets that together mean done, so the implementer works until all hold and then stops. Include required end states, such as deleted code or no remaining callers, and the full scope, such as "every payment endpoint". Name a test suite or command only when it is the evidence that matters. No implementation steps, generic "tests pass" lines, or checkboxes.

For visual changes, state what must be true on screen, such as "the nav collapses into the menu below 768 px wide with no horizontal scroll". Do not require screenshots or other files on the pull request; the implementer shares screenshots with the user in chat.

## Stop and ask

Situations specific to this ticket where continuing needs a decision the ticket does not make, such as finding a caller outside this repository.

## Execution requirements

Tools, access, or fixtures beyond the repository's usual setup.

## Risks and non-goals

What could break, and what this ticket deliberately does not do.

## Context

Links to the source discussion and related issues, and code locations to start from.

「Summary」、「Desired outcome」、「Acceptance criteria」は必ず含めます。それ以外は、実質的な内容がある場合にのみ含めます。「None」と記載するセクションは作成しないでください。

受け入れ条件ごとに、誰がどのような証拠で検証できるかを決めます。利用できるツールに合わせて証拠の基準を下げてはいけません。環境に機能がない場合は、作業を人間の担当にする理由ではなく、報告すべきギャップです。

ラベルを選ぶ

既存のラベルのみを使用し、リポジトリの慣例で認められている場合に限り、優先度ラベルやワークフローラベルを追加します。必要なラベルがない場合は付けず、その旨を伝えます。blocked ラベルは決して使用しないでください。

チケットの内容だけで、対象環境のエージェントが人間の作業を挟まずに完了・検証でき、適用されることがすでに判明している停止条件もない場合は、ready-for-agent を適用します。「Stop and ask」セクションには、発生した場合に判断が必要となる状況を記載しますが、それによってチケットが未準備になるわけではありません。調査、判断、人間が担当するチケットには、このラベルを決して適用しないでください。ブロック関係はチケット内の作業手順ではないため、その関係がある間も準備が整ったチケットにはラベルを付けたままにします。

4. 承認を得る

リポジトリ、各チケットの正確なタイトルと本文、ラベルとその簡潔な理由（ready-for-agent の理由を含む）、関係、および重複の調査結果を提示します。これらの草案についてユーザーの承認を待ちます。チケットの作成依頼、計画そのものへの承認、またはいくつかのスキルを続けて実行する指示は、承認とはみなしません。変更のない同じ一式を再開する場合、承認は引き継がれます。重要な変更がある場合は、改めて承認を得る必要があります。

5. 公開する

書き込みを行う前に、リポジトリのオープンな Issue を検索し、承認済みの各タイトルについて、この一式ですでに作成した Issue があれば再利用します。チケットを二重に作成してはいけません。また、手順をやり直すために Issue を削除、再オープン、上書きしてはいけません。

すべての書き込みに gh を使用します。承認されたすべてのラベルが存在することを確認します。存在しないラベルがある場合は、作成したり別のラベルで代用したりせず、ユーザーに確認します。関係の設定には両方の Issue 番号が必要なため、次の3段階で進めます。

1. gh issue create --body-file ですべての Issue を作成します。ブロッカーを、ブロックされるチケットより先に作成します。
2. 各 Issue に、承認されたラベルだけを追加します。
3. データベース ID を解決して検証する同梱のヘルパーを使い、承認された各関係を追加します。
   • 親：python3 "<skill-path>/scripts/set_issue_relationship.py" --repo HOST/OWNER/REPO --parent PARENT --sub-issue CHILD
   • ブロック関係：python3 "<skill-path>/scripts/set_issue_relationship.py" --repo HOST/OWNER/REPO --blocked BLOCKED --blocked-by BLOCKER

両方の番号は、指定されたリポジトリに属している必要があります。リポジトリをまたぐ関係には、各 Issue のデータベース ID を指定して gh api を使用します。関係の設定に失敗した場合、ラベルや本文中のリンクで代用してはいけません。

6. 報告する

すべての Issue、ラベル、関係を読み戻して確認します。Issue の URL と関係の状態を報告します。未完了のものがある場合は、完了した内容、残っている作業、正確なエラーを伝えます。