to-tickets

チケットに分割する

計画、仕様、会話を、複数のチケットに分割します。各チケットはトレーサーバレット型の垂直スライスで、ブロックするチケットを明示します。

イシュートラッカーとトリアージラベルの用語集は、すでに提供されているはずです。提供されていない場合は、ユーザーに /setup-matt-pocock-skills を実行するよう伝えてください。

プロセス

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

会話のコンテキストにすでに含まれている情報を基に作業します。ユーザーが引数として参照情報（仕様書のパス、イシュー番号、URLなど）を渡した場合は、それを取得し、本文とコメントをすべて読みます。

2. コードベースを調べる（条件付き）

チケットの対象領域に、初めて実装する人がなじみがない場合や、チケットがスマートゾーンの境界付近にある場合は調査します。対象領域をすでに把握していて、チケットの規模が小さい場合に限り、省略します。調査の成果は、各チケットの Orientation セクションに記載する案内情報（安定した参照箇所）です。これにより、後から作業するエージェントが再調査する必要がなくなります。下記のスマートゾーンブロックを参照してください。

コードの現在の状態を把握し、プロジェクトのドメイン用語集にある用語を使い、変更対象領域の ADR を遵守します。

実装を容易にするため、コードを事前に整える機会を探します。「変更を容易にしてから、容易になった変更を行う」。

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

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

• 各スライスは、すべてのレイヤー（スキーマ、API、UI、テスト）を通る、範囲は狭くても完全な経路を切り出します。垂直スライスとし、1 つのレイヤーだけを切り出す水平スライスにはしません。
• 完了したスライスは、それ単独でデモまたは検証が可能です。
• 各スライスは、新しいコンテキストウィンドウの生の公称上限ではなく、スマートゾーン内に収まるサイズにします（下記のスマートゾーンのブロックを参照）。
• 事前のリファクタリングは先に済ませます。

スライスは、新しいセッションのスマートゾーン（新しいコンテキストウィンドウの最初のおよそ 100K～150K トークンの範囲で、エージェントがまだ鋭く推論できる領域）に収まるサイズにします。それを超えると、エージェントはダムゾーンに入り、処理は続けるものの、注意散漫になり、忘れっぽくなり、ミスをしやすくなります。計画はスマートゾーンを基準にし、公称上限を基準にしてはいけません。

新しいセッションでは、コードを 1 行書く前にコンテキスト読み込みの負担が発生します。チケットを担当するエージェントは、何も知らない状態から始めます。チケット本文、親仕様と関連イシュー、その領域の ADR と用語集、コーディング標準を読み、さらにコードベースを調べて状況を把握します。読み込みに使うトークンも、実装に使うトークンと同じくスマートゾーンの範囲に含まれます。つまり、ゾーンは予算であり、状況把握にも予算を使います。そのため、起案者が最初にすべきことは、実装担当者が読み込む情報を減らすことです。チケットの Orientation セクションに安定した参照先を記載して、状況把握に必要な情報をあらかじめ盛り込み、変更しやすいように事前リファクタリングします。事前に盛り込めない情報だけが、見積もるべき負担として残ります。

実効的な実装予算は、スマートゾーン − コンテキスト読み込みのオーバーヘッドです。実装担当者がチケットを新たに担当する際の読み込み量（起案者がすでに調査して参照先を残している場合は少なく、未調査または大規模な領域では多くなります）と、実装に必要な作業量（変更にかかる読解・記述・推論）を見積もり、読み込みと実装の合計が余裕をもってスマートゾーン内に収まるまでチケットを分割します。ダムゾーンに入った兆候を判断するのは、作業だけではなく、読み込みと作業の合計です。変更規模が小さいチケットでも、その領域の読み込みが多ければ上限を超えることがあります。判断に迷ったら、分割してください。

各チケットには、ブロッキング依存関係を記載します。つまり、着手前に完了していなければならない他のチケットです。ブロッカーがないチケットは、すぐに着手できます。

大規模なリファクタリングは、垂直スライスの例外です。大規模なリファクタリングとは、1 つの機械的な変更（カラム名の変更や、共有シンボルの型変更など）がコードベース全体に波及し、一度の編集で何千もの呼び出し箇所が壊れるため、どの垂直スライスも CI を通過した状態で取り込めないような変更です。これをトレーサー・ブレットに無理に分割せず、拡張–縮小の順序で進めます。まず拡張として、新しい形式を古い形式と並行して追加し、既存のものが壊れないようにします。次に、波及範囲に応じた単位（パッケージ単位、ディレクトリ単位）で呼び出し箇所を移行します。各バッチを独立したチケットとし、拡張チケットをブロッカーに設定します。古い形式がまだ残っているため、各バッチを通して CI はグリーンを維持できます。最後に縮小として、呼び出し元がなくなったら古い形式を削除します。このチケットは、すべての移行バッチをブロッカーにします。バッチ単独ではグリーンを維持できない場合も、この順序は保ちつつ、すべてのバッチが最終的な統合・検証チケットをブロッカーとする統合ブランチを共有します。グリーンを保証するのは、その最終チケットだけです。

4. ユーザーに確認する

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

• タイトル：短く、内容が分かる名前
• 依存先：先に完了している必要がある他のチケット（ある場合）
• 実現する内容：このチケットで可能になる、エンドツーエンドの動作

ユーザーに以下を尋ねます。

• 粒度は適切ですか？（大きすぎる／細かすぎる）
• 各チケットには、新たに実装に取り組む人に必要な方針が含まれていますか？（「Orientation」セクションに安定した手掛かりがあり、再調査せずに済む状態ですか？）
• すべてのチケットがスマートゾーンに収まっていますか？エージェントがダムゾーンに追い込まれるチケットはありませんか？
• ブロック関係は正しいですか？各チケットは、本当に着手を妨げるチケットだけに依存していますか？
• チケットを統合したり、さらに分割したりする必要はありますか？

ユーザーが内訳を承認するまで、調整を繰り返します。

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 トリアージラベルを付与します。チケットは、エージェントがすぐに取りかかれる状態で作成されています。

フロンティアに沿って作業します。つまり、ブロッカーがすべて完了しているチケットが対象です。依存関係が単純な直列の場合は、上から順に進めます。

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

：<チケットのタイトル>

作成するもの： レイヤーごとの実装リストではなく、ユーザーの視点から見た、このチケットで可能になるエンドツーエンドの動作。

Orientation： 新たに実装に取り組む人が、コードに手を付ける前に読む安定した手掛かり（ADR ID、用語集の用語、モジュール／パッケージ名、親イシューなど）。変わりやすいファイルパスや行番号は含めません。これにより、コンテキストを読み込む負担を減らし、実装者が再調査せずに済むようにします。

規模： Orientation を先に示します（上記の安定した手掛かり）。残りのコンテキスト読み込みと実装に必要な規模は、スマートゾーン内（セッション全体で約100K～150Kトークン）に収まる見込みです。

Blocked by： このチケットをブロックするチケットの番号とタイトル。ない場合は「なし（すぐに着手可能）」。

ステータス： ready-for-agent

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

親

トラッカー上の親イシューへの参照（元の内容が既存のイシューの場合。そうでない場合は、このセクションを省略します）。

作成するもの

レイヤーごとの実装ではなく、ユーザーの視点から見た、このチケットで可能になるエンドツーエンドの動作。

Orientation

新たに実装に取り組む人が、コードに手を付ける前に読む安定した手掛かり（ADR ID、用語集の用語、モジュール／パッケージ名、親イシューなど）。変わりやすいファイルパスや行番号は含めません。これにより、コンテキストを読み込む負担を減らし、実装者が再調査せずに済むようにします。

規模： Orientation を先に示します（上記の安定した手掛かり）。残りのコンテキスト読み込みと実装に必要な規模は、スマートゾーン内（セッション全体で約100K～150Kトークン）に収まる見込みです。

受け入れ条件

• 条件1
• 条件2

## 依存関係

• 依存するチケットへの参照、または「なし（すぐに着手できます）」を記載します。ブロッカーがネイティブのエッジとして設定されている場合は、このセクションを省略してください。

どちらの形式でも、変わりやすい参照（特定のファイルパス、行番号、dist の内部情報）は避けてください。すぐに古くなってしまいます。代わりに、ADR ID、用語集の用語、モジュール／パッケージ名、親 issue などの安定した参照先を使うことをおすすめします。これらは変更されにくく、新しい実装者が必要な情報を的確に読み込めます。例外として、プロトタイプで、文章よりも正確に決定事項を表現したスニペット（状態マシン、リデューサー、スキーマ、型の形状）が作成されている場合は、インラインで記載し、プロトタイプから作成されたことを簡潔に記してください。動作するデモではなく、決定事項を明確に示す重要な部分だけを残してください。

6. 言語

チケット本文は英語で記述してください。チケットはエージェント向けの作業項目であり、主要コンテンツではありません。チケット、サブイシュー、フォローアップに ## Chinese Summary (non-authoritative) のコメントを付けないでください。中国語の要約を付けるのは、個人リポジトリで to-spec の実行によって公開された仕様 issue など、主要コンテンツに限られます。チケットごと、または実行ごとに付けるものではありません。