to-tickets

チケットへの分割

計画、仕様、または会話を一連のチケットに分割します。各チケットは、縦に貫くトレーサーバレットのスライスであり、その着手を妨げるチケットを明記します。

課題トラッカーとトリアージラベルの語彙は、あらかじめ提供されているはずです。提供されていない場合は、ユーザーに /setup-matt-pocock-skills を実行するよう伝えてください。

プロセス

1. コンテキストを集める

会話のコンテキストにすでにある情報をもとに進めます。ユーザーが引数として参照情報（仕様ファイルのパス、課題番号、URL）を渡した場合は、それを取得し、本文とコメントをすべて読んでください。

2. コードベースを調べる（任意）

コードベースをまだ調べていない場合は、現在のコードの状態を把握するために調査してください。チケットのタイトルと説明では、プロジェクトのドメイン用語集の語彙を使い、変更対象の領域に関する ADR を守ってください。

実装を容易にするため、コードを事前にリファクタリングできる機会を探してください。「変更を容易にしてから、容易な変更を行う」。

3. 垂直スライスを作成する

作業をトレーサーバレットチケットに分割します。

• 各スライスは、すべてのレイヤー（スキーマ、API、UI、テスト）を通る、狭くても完全な経路を作ります。垂直に分割し、1 つのレイヤーだけを水平に切り出してはいけません
• 完了したスライスは、それだけでデモまたは検証が可能です
• 各スライスは、まっさらなコンテキストウィンドウ 1 つで扱える規模にします
• 事前のリファクタリングが必要な場合は、先に行います

各チケットにブロッカーの依存関係を付けます。着手前に完了している必要がある、他のチケットを記載してください。ブロッカーがないチケットは、すぐに着手できます。

実装者が単独で進めるため、各チケットに完了条件と中断条件を設定します。

• 完了とは：受け入れ条件がすべて満たされることです。各条件は、開始時点では満たされておらず、作業完了時には満たされていると観察できる内容にします（「テストスイートが成功する」「すべての呼び出し箇所が新しいクライアントを使用している」など）。実装者は、すべての条件が満たされるまで作業を続けます。
• 中断して確認する場合：実装者が単独では判断できない状況を 1 つだけ記載します。たとえば、「説明できない理由でテストが失敗する場合」や「移行によってデータが失われる場合」です。それ以外はすべて実装者が判断し、その判断を PR に記録します。該当する状況がなければ、「該当なし：判断して PR に記録する」と記載します。

大規模なリファクタリングは、垂直スライスの例外です。 大規模なリファクタリングとは、列名の変更や共有シンボルの型変更など、コードベース全体に影響範囲が広がる、機械的な変更を指します。一度の編集で何千もの呼び出し箇所が壊れ、垂直スライスをどのように作っても CI を成功させたままマージできません。こうした変更を無理にトレーサーバレットに分割せず、拡張—収縮の順に進めます。まず拡張として、既存の形式を残したまま新しい形式を追加し、何も壊れないようにします。次に呼び出し箇所を移行します。影響範囲に応じた単位（パッケージごと、ディレクトリごと）でバッチに分け、各バッチを拡張チケットにブロックされる個別のチケットにします。古い形式が残っているため、各バッチで CI の成功を維持します。最後に収縮として、呼び出し元がなくなったら、すべての移行バッチにブロックされるチケットで古い形式を削除します。各バッチ単独では成功を維持できない場合も、この順序は保ちますが、すべてのバッチが最終的な統合と検証のチケットにブロックされる、共有の統合ブランチを使用します。成功が約束されるのは、その統合と検証の段階だけです。

4. ユーザーに確認する

提案する分割案を番号付きリストで提示します。各チケットについて、以下を示してください。

• タイトル：簡潔で説明的な名前
• ブロックされる要因：先に完了している必要がある他のチケット（あれば）
• 実現すること：そのチケットによって機能するようになる、エンドツーエンドの動作
• 中断して確認する場合：実装者が中断すべき状況、または「なし」

ユーザーに次の点を確認します。

• 分割の粒度は適切ですか？（粗すぎる／細かすぎる）
• ブロッカーの依存関係は正しいですか？各チケットが、本当に着手の障害となるチケットだけに依存していますか？
• 統合またはさらに分割すべきチケットはありますか？

ユーザーが分割案を承認するまで、調整を続けます。

5. チケットを設定済みのトラッカーに公開する

承認済みのチケットを公開します。方法は設定されているトラッカー /setup-matt-pocock-skills によって異なります。チケットの内容はどちらの場合も同じで、ブロック関係の形式だけが変わります。

• ローカルファイル → .scratch/<feature-slug>/issues/<NN>-<slug>.md に、チケットごとに1つのファイルを書き込みます。依存関係の順に（ブロッカーを先にして）01 から番号を付けます。各ファイルの「Blocked by」には、依存先の番号またはタイトルを記載します。以下のチケットごとのファイルテンプレートを使用してください。チケットごとに1ファイルとし、複数のチケットを1つのファイルにまとめないでください。
• 実際のイシュートラッカー（GitHub、Linear、…） → ブロッカーを先にして、依存関係の順にチケットごとに1つのイシューを公開し、各チケットのブロック関係が実際の識別子を参照できるようにします。プラットフォームにネイティブのブロック関係がある場合はそれを使用し、ない場合は各チケットの「Blocked by」にブロッカーとなるイシューを設定します。元になったのが既存のイシューである場合は、各チケットをそのサブイシューにします（トラッカードキュメントに記載された操作）。特に指示がない限り、トリアージラベル ready-for-agent を適用します。チケットは、その構成上、エージェントがすぐに取得できる状態です。

フロンティアに沿って作業してください。つまり、ブロッカーがすべて完了しているチケットを進めます。依存関係が一直線のチェーンであれば、上から順に進めます。

親イシューをクローズしたり変更したりしないでください。

チケットをネイティブのサブイシューとして親の下にリンクすること（上記）は、親の「変更」にはあたりません。それが目的です。

:

作るもの： このチケットによって実現するエンドツーエンドの振る舞いを、レイヤーごとの実装リストではなく、ユーザーの視点から記述します。

Blocked by： このチケットの着手を妨げるチケットの番号またはタイトル、あるいは「None (can start immediately)」。

Status： ready-for-agent

完了の定義：

• 受け入れ条件 1
• 受け入れ条件 2

次の場合にのみ確認を求める： 実装者だけでは判断できない状況を1つ記述するか、「None: decide and note it in the PR」。

親

トラッカー上の親イシューへの参照です（元になったのが既存のイシューである場合。そうでなければ、このセクションは省略します）。

作るもの

このチケットによって実現するエンドツーエンドの振る舞いを、レイヤーごとの実装ではなく、ユーザーの視点から記述します。

完了の定義

• 受け入れ条件 1
• 受け入れ条件 2

次の場合にのみ確認を求める

実装者だけでは判断できない状況を1つ記述するか、「None: decide and note it in the PR」。

ブロック元

ブロッカーとなる各チケットへの参照、または「None (can start immediately)」。ブロッカーがネイティブのブロック関係として設定されている場合は、このセクションを省略します。

どちらの形式でも、具体的なファイルパスやコードスニペットは避けてください。すぐに古くなるためです。例外として、プロトタイプで作成されたスニペットが、文章よりも正確に判断内容を表す場合（状態機械、reducer、スキーマ、型の形など）は、インラインで記載し、プロトタイプ由来であることを簡潔に注記してください。動作するデモではなく、判断に重要な部分だけに絞ってください。