cawplan-plan-track

CawPlan 計画トラック

ブートストラップ

cawplan skill check

チケット検索に関する重要なルール

cawplan tickets search では、--unique_ids／--display_ids／--parent_ids を使った完全一致検索を行う場合を除き、--time_range または --start_date と --end_date の指定が必須です。リリースの追跡では、作成時期に関係なくチケットが必要になるため、このスキルのバージョン全体を対象とした検索では常に --start_date 2000-01-01 --end_date <today> を使い、total に達するまでページを取得します。

分類の正規の情報源はラベルです。チケットがバグか機能かを判断するために、レガシーのチケット type、--type 検索オプション、または返された .type を使わないでください。カテゴリ別の検索では、最初に確認済みのプロダクトの表示可能なラベルを一覧表示し、そのカタログ内からのみ選択して、--label_ids で絞り込みます。

レスポンスの description が正規のチケットタイトルです。表示時はそのまま使用してください。翻訳、要約、短縮、句読点や空白の正規化、接頭辞の削除、括弧内のテキストの省略はしないでください。同じタイトルが表示される Markdown のエスケープは許可されます。要約は別のフィールドに記載してください。

ワークフロー

プロダクトアクセスの必須確認

プロダクト、バージョン、リリース、またはチケットに関するデータを照会する前に、products list を通じて呼び出し元がそのプロダクトを参照できることを確認してください。ユーザーが product_id を直接指定した場合や、以前の会話から取得した場合も同様です。既知の ID をアクセス可能である証拠として扱わないでください。

cawplan products list --search "<product name or product_id>"

レスポンスに対象のプロダクトが 1 つ（product_id／unique_id）含まれる場合にのみ続行してください。指定されたプロダクト名と完全一致するもの（大文字・小文字を区別せず、前後の空白を除去）を照合するか、一意な短縮形／トークン接頭辞の一致を受け入れます。似た名前の候補が複数ある場合、それらは候補にすぎず、自動的な置き換えはできません。一意に一致するアクセス可能なプロダクトがない場合は、versions、tickets、product-lines statuses、その他のプロダクトスコープのエンドポイントを呼び出さないでください。候補が返された場合は名前を列挙し、どのプロダクトを指しているのかユーザーに確認してください。候補が返されなかった場合は、指定されたプロダクトが存在しないか、呼び出し元がアクセスできないことを伝えてください。チケット数を報告したり、チケット一覧が空であるかのように示したりしないでください。API が明示的にアクセス拒否を報告した場合にのみ NO_PERMISSION を返してください。

NO_PERMISSION: You do not have access to product "CawCut Cloud".

アクセスできないプロダクトを、Open Tickets: 0 のような空の結果に置き換えないでください。チケット一覧が空であるという情報に意味があるのは、このアクセス確認に成功した後だけです。

1. プロダクト名を product_id に解決し、必須のプロダクトアクセス確認を完了します：

   cawplan products list --search "<product name>"
   

完全一致または一意な短縮形のプロダクトが見つからない場合は、候補があれば（名前 + product_id）を一覧表示し、どのプロダクトを指しているのかユーザーに確認してください。推測してはいけません。候補が返されなかった場合は、次のように伝えてください：アクセス可能な product “<name>” が見つかりませんでした。この product は存在しないか、現在アクセス権がない可能性があるため、tickets を照会できません。 一致するものが複数ある場合は、ユーザーに選択を依頼してください。確認済みレコードの product_line_id（またはネストされた product_line.unique_id。レスポンスの実際のフィールド名を確認してください）を保持します。

2. バージョン名を version_id に解決します（すでに判明している場合は省略）：

   cawplan versions list <product_id>
   

3. 進捗とリリース履歴を 1 回の呼び出しで取得します：

   cawplan versions track <product_id> <version_id>
   

   次の情報が返されます：

   • detail.data.progress — complete_percent、status_counts（COMPLETE / UNSTARTED / STARTED / TESTING / CANCELED）
   • detail.data.risk — LOW / MEDIUM / HIGH
   • detail.data.risk_reason
   • detail.data.extra.target_release — チャネル名と release_at タイムスタンプ
   • detail.data.status — NOT_STARTED / INPROGRESS / RELEASED
   • release.data — リリース履歴イベント（ステータス変更、リスク変更）

4. 以下の各手順で必要となるプロダクトラインのステータスキーを解決します（単純な進捗確認を除きます。手順 5 の前に 1 回実行してください）：

   cawplan product-lines statuses <product_line_id>
   

   これにより、各ステータスの key と category（UNSTARTED / STARTED / TESTING / COMPLETE / CANCELED）が返されます。以下の手順でクライアント側の確認に使う、キーからカテゴリへのマップを作成してください。 4a. 分類ラベルを解決します（ステップ6または7を実行する場合）：

   cawplan labels list --product_id <product_id> --page_size 200 --page_num 1
   

   total までページングします。このプロダクトに限定されたカタログから返されたラベルのみを選択してください。名前やIDを決して作り出さず、従来の type にフォールバックしないでください。

   • バグの意図：behavior=BUGFIX は強い一致です。名前の強いシグナルは bug、bugs、bugfix、bug fix、defect、defects、regression、regressions です。fix、fixing、hotfix、issue、crash、incident、blocker は文脈に依存するものとして扱い、カタログとユーザーの意図から明らかにカテゴリラベルと判断できる場合にのみ選択してください。
   • 機能の意図：behavior=FEATURE は強い一致です。feature や enhancement など、意味が正確に一致する名前は、カタログと整合する場合に候補となります。
   • 照合時には大文字・小文字、空白、ハイフン、アンダースコアを正規化しますが、返されたIDと名前はそのまま保持してください。安全に一致するラベルが複数ある場合は、すべて使用してください（label_ids 内では OR）。安全に一致するラベルがない場合は、候補を示して質問してください。type は使用しないでください。

5. このバージョンのすべてのチケットを、共有する単一の全詳細データセットで取得します（チケット単位の詳細を求めていない通常の進捗確認の場合のみ省略）：

   cawplan tickets search --version_ids <version_id> --start_date 2000-01-01 --end_date <today> --page_size 100 --page_num 1
   

   page_num * page_size < total の間、ページングします。検索結果には、ここで必要となる完全なチケット形式が含まれています。具体的には、description、labels、status_display、priority、assignees、updated_at、version_id、parent_id です。ステップ5aおよび8～13では、この共有データセットをフィルタリングします。ステップ6～7では、カテゴリ選択がAPIによって適用されるよう、意図的にラベルでフィルタリングした検索を実行します。

   このセットにはサブ課題も含まれます（parent_id が設定されているもの）。以下のすべてのリスト（ステップ6～13）にサブ課題を含めてください。CRITICAL のサブ課題バグも、独立してラベル付け、優先順位付け、担当者割り当てが行われ、確認が必要な実際のチケットです。ただし、報告するチケット数（例：「未着手のチケットが31件」）が、同じバージョンに対する versions get の progress.status_counts より大きくなっても不思議ではありません。このフィールドが数えるのはトップレベルのチケットのみであり、両者は同じ集合を測定していないため、必ず一致するかのように示してはいけません。

5a. オープンチケット（ユーザーが現在のバージョンのオープンチケットを求めた場合）：ステップ5のバージョンでフィルタリングしたセットから、ステータスキーが COMPLETE または CANCELED 以外のカテゴリに対応するチケットをすべて含めます。UNSTARTED、STARTED、TESTING はすべてオープンカテゴリです。 ステータスキーのハードコードされた許可リストを使ったり、キーや表示名から終端状態を推測したりしないでください。カテゴリが TESTING の Testing というカスタムステータスはオープンチケットであり、返す必要があります。 解決されたステータス表示名／カテゴリごとに結果をグループ化します。

6. 未解決の重大バグ（ユーザーがリリースリスク／ブロッカーについて尋ねた場合のみ。通常の進捗確認では省略）：CawPlan のチケットには「ブロッカー」という独立した優先度はありません。priority=CRITICAL を「ブロッカー」レベルとして扱います。ステップ4aで選択したバグラベルIDを使用します：

   cawplan tickets search --version_ids <version_id> --label_ids <bug-label-ids> --priority CRITICAL --start_date 2000-01-01 --end_date <today> --excluded_status_categories COMPLETE,CANCELED --page_size 100 --page_num 1
   

   total までページングした後、インラインの status_display.category が COMPLETE または CANCELED である結果を個別に除外します。

7. QA テスト段階に達していない機能（ステップ6と同じ条件）：ステップ4aで選択した機能ラベルIDを使用します：

   cawplan tickets search --version_ids <version_id> --label_ids <feature-label-ids> --status_categories UNSTARTED,STARTED --start_date 2000-01-01 --end_date <today> --page_size 100 --page_num 1
   

   total までページングした後、インラインの status_display.category が UNSTARTED または STARTED である結果のみを残します。

8. QA 準備完了／QA テスト中のチケット一覧（ユーザーが求めた場合のみ。例：「QA 準備ができているものは何ですか」「QA テスト中のものは何ですか」）：ステップ5のセットから、ラベルに関係なく、ステータスカテゴリが TESTING のものを残します。ステップ10と12ではこの一覧を再利用してください。そのためにステップ5を再度フィルタリングしないでください。

9. 縮小範囲の提案（ユーザーが明示的に、範囲を縮小する対象や遅延リスクの軽減方法を尋ねた場合のみ — 求められていないのに提案しないでください）：

   • 候補は、ステップ 5 でバージョンによって絞り込まれたセットです。この候補セット外のチケットは提案しないでください。また、返されていない優先度を推測しないでください。候補の優先度が本当に欠けている場合は、作り上げずに候補から除外してください。
   • ステータスカテゴリが UNSTARTED（作業未着手）のチケットのみ、範囲縮小の対象として提案してください。STARTED、TESTING、COMPLETE の作業は決して提案しないでください。
   • 提案は優先度の LOW を先に、次に MEDIUM の順に並べてください。優先度が HIGH または CRITICAL のチケットは、範囲縮小の対象として決して提案しないでください。
   • すべての提案の根拠は、risk_reason とステップ 5 の実際のチケット一覧に基づけてください。risk_reason にない理由を作り上げないでください。

10. QA テストを妨げている要因（尋ねられた場合のみ）：ステップ 8 の Ready-for-QA/TESTING リストにある各チケットについて、ブロック関係を確認してください。

    cawplan tickets relate list <product_id> <version_id> <ticket_id>
    

    relation_type=BLOCKED_BY の関係ごとに、ブロッカーとなっているチケットのステータスを、同じバージョンにある場合はステップ 5 のデータセットから確認してください。それ以外の場合は、cawplan tickets get <product_id> <version_id_of_that_ticket> <ticket_id> で確認してください。対象バージョン外にあるというだけで、解決済みだと仮定しないでください。ステータスカテゴリ（ステップ 4 の対応表）が COMPLETE/CANCELED ではないブロッカーのみ報告してください。テスト中のチケットごとに relate list を 1 回呼び出します。対象が多い場合は、黙って一部だけ確認するのではなく、テスト中のチケットのみを対象としていることをユーザーに伝えてください。

11. 担当者の過負荷（尋ねられた場合のみ — 「誰かに負荷が集中していますか」「高優先度の課題を抱えすぎているのは誰ですか」など）：ステップ 5 のセットから、priority が CRITICAL/HIGH で、ステータスカテゴリが COMPLETE/CANCELED ではないチケットを対象にしてください。チケットには複数の assignees を設定できます。チケットごとに合計 1 件として数えるのではなく、担当者ごとに 1 件として数えてください。assignees がないチケットも除外せず、「未割り当て」として別途報告してください。担当者のいない未完了の高優先度チケットは、それ自体を明示する価値があります。担当者ごとにグループ化し、件数の多い順に並べてください。最多件数が同じ担当者が 2 人以上いる場合は、任意に 1 人を選ばず、全員を同率トップとして報告してください。「過負荷」と見なす基準（例：「3 件以上は多すぎる」）を作り上げないでください。チームのキャパシティ基準は把握できないため、担当者ごとの実際の件数を報告し、ユーザーが判断できるようにしてください。また、「誰が」を尋ねられたときの答えとして最も有力な候補が分かるよう、ランキングのトップ（同率の場合は該当者全員）を明示してください。

12. QA 担当者ごとの未検証件数（尋ねられた場合のみ — 「各 QA 担当者に検証が残っている件数」など）：ステップ 8 の Ready-for-QA/QA-Testing リストを再利用してください。ステップ 11 と同様に assignees ごとにグループ化し（複数担当者のチケットは担当者ごとに 1 件として数え）、担当者ごとの件数を報告してください。このリストに担当者のいないチケットがある場合は、除外したり、誰にも帰属させずに黙って処理したりせず、「未割り当て」として別途報告してください。

13. N 日以上更新されていないチケット（尋ねられた場合のみ — 「N 日間手が付けられていないものは何ですか」など）：ユーザーが N を指定していない場合は、デフォルト値を決めずに、「長い間」とはどのくらいの期間を意味するのか尋ねてください。何を古いとみなすかに普遍的な基準はありません。N が決まったら、ステップ 5 のセットからステータスカテゴリが COMPLETE/CANCELED のチケットを除外し（解決済みのチケットがその後更新されていなくても、「未修正」ではありません）、残りについて (now - updated_at) を日数で計算し、N 日を超えるものを古い順に一覧表示してください。

出力

レポートは、ユーザーが実際に依頼した内容の範囲に限定してください（単に「このリリースを追跡して」と依頼された場合は、ステップ 4～13 を実行しないでください）。

• バージョン名、ステータス、リスクレベル（MEDIUM または HIGH の場合は理由も記載）。
• 完了状況：X% complete (N done / M total)（X は整数に丸めてください）。
• チャネルごとの目標リリース日（release_at の Unix タイムスタンプを読みやすい日付に変換）。
• ステップ 5a を実行した場合：オープンチケット — ID、ラベル、優先度、担当者、description のタイトルをそのまま表示し、解決ステータスごとにグループ化してください。TESTING を含む、終端状態ではないすべてのカテゴリを含めてください。
• ブロッカー：優先度が CRITICAL または HIGH のオープンチケット。
• ステップ 6/7 を実行した場合：未解決の Critical バグと、まだ QA Testing に達していない機能をそれぞれ別のリストにし、各チケットの ID、タイトル、担当者を表示してください。
• ステップ 8 を実行した場合：Ready for QA / QA Testing のリスト — ID、ラベル、description のタイトルをそのまま表示し、担当者も記載してください。
• ステップ 9 を実行した場合：スコープ除外の提案を順位付きリストで示し、各項目にチケットと、対象となる理由を 1 行で記載してください（優先度 + ステータスカテゴリ）。risk_reason を言い換えて繰り返すのではなく、対象となる理由を記載してください。
• ステップ 10 を実行した場合：テスト中のチケットのうち、ブロックされているもの、その原因、ブロッカー自身のステータスを記載してください。または、未解決のブロッカーがあるテスト中のチケットはないと明記してください。
• ステップ 11 を実行した場合：優先度の高いオープンチケット数が多い順に担当者を順位付けしてください（最多で同数の担当者は全員まとめて記載）。「過負荷」の判定はせず、順位と件数のみを記載してください — 条件に該当するチケットに担当者がいない場合は「未割り当て」の件数も記載してください。
• ステップ 12 を実行した場合：QA 担当者ごとの検証待ち件数を記載し、担当者のいない Ready-for-QA チケットがある場合は「未割り当て」の内訳も記載してください。
• ステップ 13 を実行した場合：更新から N 日を超えるチケット（ID、タイトル、担当者、更新からの日数）を古い順に記載してください。または、N 日を超えるチケットはないと明記してください。

すべてのチケットが完了している場合は、その旨を明記してください。

参照

• references/CAWPLAN_OPEN_API.md