cawplan-ux-tracking

CawPlan UX トラッキング

初期設定

cawplan skill check

背景

チケットの ux 値は NOT_REQUIRED、PENDING、READY です。UX のフォローアップが必要なのは PENDING のみです。

tickets poll ではなく、cawplan tickets search を使用してください。poll は ux を返さないためです。

どのワークフローでも --excluded_status_categories COMPLETE,CANCELED を渡してください。チケットが終了した後も、UX が PENDING のままの場合があるためです。プロダクトライン固有のステータスキーではなく、カテゴリーフィルターを使用してください。

UX クエリではウィンドウ全体を指定する必要があります。

--start_date 2000-01-01 --end_date <today>

ページネーション：page_num * page_size < total の間、page_num を増やしてください。完了の判断には total を使用します。ホスト型エージェントでは各ページが個別のツール呼び出しとなり（シェルループや jq は使えません）、1 ターンの呼び出し回数はおよそ 16 回です。--page_size 100 を使用し、ページ数が収まらない場合は部分的な結果を報告してください（references/QUERY_RESILIENCE.md を参照）。

件数のみ（「優先度／バージョン別に、UX 対応が必要なチケットは何件か」）：ページを取得して数える代わりに、同じフィルターを指定した cawplan tickets stats と --group_by priority（または version、assignee）を使用してください。

フォローアップとエラー：references/QUERY_RESILIENCE.md に従ってください。「では CRITICAL と HIGH だけ」のようなフォローアップでは、前のプロダクト／バージョンの範囲を維持し、新しいフィルターのみを追加してください。コンテキスト内で ID を確認できる場合は再利用し、確認できない場合は前の回答から範囲名をもう一度解決してください。範囲を省略してはいけません。また、プロダクト名を --product_ids に渡してはいけません。コマンドが拒否された場合やページの取得に失敗した場合は、確認できた内容を部分的な結果として報告し、コマンドやエラーテキストをユーザーに表示しないでください。

入力の振り分け

入力	フロー
特定のプロダクト＋バージョン（「このバージョンで UX フォローアップが必要なチケット」）	A — バージョン範囲
特定のプロダクトで、バージョン指定なし。優先度やチームを条件としない	A — バージョン範囲。ただし、特定のバージョンを指すのか、プロダクトの全バージョンを指すのかをユーザーに確認します。「全バージョン」の場合は、--product_ids を指定し、--version_ids を指定せずにワークフロー A のステップ 2 を実行します。バージョン指定がないという理由だけで優先度フィルターを追加してはいけません（それはワークフロー B のフィルターであり、ここでは適用されません）。
特定バージョンの指定がない高優先度のチケット、または明示的な複数バージョン横断	B — 優先度範囲
チーム／プロダクトライン（「UX が未提供のチームの一覧」）	C — チーム範囲
プロダクトの UX メンバーのデザイン完了状況（「CawCut Cloud UX Team の今週の UX 完了状況をまとめて」）	D — プロダクト UX 完了状況

ワークフロー A — バージョン範囲

1. プロダクトとバージョンを解決します（cawplan-plan-track のステップ 1～2 と同じパターン）。

   cawplan products list --search <product-name-word>
   cawplan versions list <product_id>
   

   検索テキストは引用符で囲まず、1 つのトークンとして渡してください（--search CawPlan。--search "CawPlan" は不可）。ホスト型エージェントでは、引用符で囲まれた値が拒否されます。スペースを含む名前の場合は、特徴的な単語を 1 つ検索し、結果から完全な名前を照合してください。 指定されたプロダクトは、アクセス可能な名前と完全に一致するもの（空白をトリミングした後、大文字と小文字を区別しない）、一意に一致する短縮形／トークンの接頭辞、またはユーザーが明示的に確認した候補である必要があります。一意に特定できない場合は、チケットを一覧表示したり照会したりする前に候補を提示し、どのプロダクトを指しているかユーザーに確認してください。最も名前が近いプロダクトを使ってはいけません。

2. 取得します。

   cawplan tickets search --version_ids <version_id> --ux PENDING --excluded_status_categories COMPLETE,CANCELED --start_date 2000-01-01 --end_date <today> --page_size 100 --page_num 1
   

   上記のページネーションに従い、すべてのページを取得してください。

   「このプロダクトの全バージョン」の場合（入力の振り分けを参照）、--version_ids を省略し、代わりに --product_ids <product_id> を使用してください。それ以外はこのステップの内容を変更せず、バージョン指定がないという理由だけで優先度フィルターを追加しないでください。

ワークフロー B — 優先度範囲

1. ユーザーがプロダクト／バージョンを指定した場合は、ワークフロー A と同じ方法で解決し、--product_ids／--version_ids を追加します。指定していない場合は、プロダクトに絞り込むのか、アクセス可能なすべての範囲を検索するのかを確認してください。「すべて」と黙って決めつけてはいけません。
2. 取得します。

   cawplan tickets search --priority CRITICAL,HIGH --ux PENDING --excluded_status_categories COMPLETE,CANCELED --start_date 2000-01-01 --end_date <today> --page_size 100 --page_num 1 [--product_ids <id>] [--version_ids <id>]
   

   上記のページネーションに従ってすべてのページを取得し、CRITICAL → HIGH の順に並べ替えてください。

ワークフロー C — チームの範囲

1. チーム名を product_line_id に解決します。cawplan-product-report のチームワークフローと同じ方法で、cawplan product-lines list --page_size 100 を実行し、クライアント側で名前を照合します。空白を取り除いた後、大文字と小文字を区別しない完全一致、一意の短縮形／トークン接頭辞の一致、または候補に対するユーザーの明示的な確認を必須とします。複数の一致がある場合は、どれかを特定するよう尋ねます。一意の名前一致がない場合は、最も近い候補を推測するのではなく、候補を一覧表示して、どのチームを指しているか尋ねます。
2. 次を取得します：

   cawplan tickets search --product_line_ids <product_line_id> --ux PENDING --excluded_status_categories COMPLETE,CANCELED --start_date 2000-01-01 --end_date <today> --page_size 100 --page_num 1
   

   上記のページネーションの説明に従って最後までページを取得し、その後 CRITICAL → HIGH → MEDIUM → LOW の順に並べ替えます。

ワークフロー D — プロダクト UX の完了

ここでいう UX チームは、プロダクトで設定された members.designers のメンバー一覧を指し、CawPlan のプロダクトラインではありません。プロダクトが指定されていない場合は、どのプロダクトの UX メンバーを報告するか尋ねます。

1. プロダクトを解決し、ワークフロー A と同じプロダクトアクセス確認を完了します：

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

   一致したプロダクトの members.designers[] のメンバー一覧を読み込み、user_id の値と表示名を収集します。Designer がいない場合は、プロダクトに UX メンバー一覧が設定されていないことを報告して終了します。メンバーシップはプロダクト単位です。ワークスペース全体を対象にキーワード検索するのではなく、ここで取得したメンバー一覧を使用します。ユーザーが期間を指定しない場合に限り、日付範囲を今週に設定します。

2. 期間内にメンバーが行った UX の変更を、一括呼び出しで漏れなく取得します（期間は最大 90 日です。これを超える場合は分割します）：

   cawplan tickets changes --product_ids <product_id> --fields ux --actor_ids <designer_user_ids_csv> --start_date <window_start> --end_date <window_end>
   

   new が READY のイベントだけを残します。各イベントの actor は履歴上のアクター、at は変更時刻です。レスポンスの tickets マップには、出力用の表示 ID、タイトル、バージョンが含まれます。Ticket の現在の ux が READY であること、Designer に割り当てられていること、または Designer 以外の人が ux フィールドを変更したことを理由に、その Ticket をカウントしないでください。結果が truncated の場合は、報告前に --cursor を使用して続行するか、期間を分割します。

   フォールバック（tickets changes が利用できない場合のみ。references/QUERY_RESILIENCE.md を参照）： 次のコマンドで候補を取得します。

   cawplan tickets search --product_ids <product_id> --ux PENDING,READY --start_date 2000-01-01 --end_date <today> --updated_start_date <window_start> --updated_end_date <today> --page_size 100 --page_num 1
   

   最後までページを取得します（終了ステータスによる除外はしません。Ticket は READY になった後にクローズされたり、PENDING に戻されたりする場合があります。updated_at は候補の絞り込みにのみ使用します）。その後、すべての候補について cawplan tickets history <product_id> <version_id> <ticket_id> を取得し、期間内の created_at を持ち、user_id がメンバー一覧に含まれ、changed_fields.ux が READY に変更された UPDATED エントリー（READY という文字列、または new: READY を含むオブジェクト）だけを残します。処理に時間がかかる方法を使用したことを伝え、すべての候補を確認できなかった場合は部分的な結果を報告します。

3. Ticket ごとに重複を排除し、期間内で最新の UX-Ready イベントを残します。残った Ticket を、そのイベントのアクター（actor.user_id / actor.display_name。フォールバックでは履歴エントリーの user_id / user_display_name）ごとにグループ化します。このアクターが、UX 作業を完了したプロダクトメンバー一覧上の Designer です。Ticket の報告者や通常の担当者から Designer を推定したり、その人物をグループ化またはカウントしたりしないでください。

出力

• 条件に一致するチケットを 1 行ずつ表示します。表示 ID、タイトル、タイプ、優先度、プロダクト／バージョン、担当者を記載します。
• ワークフロー B/C：上記のとおり、優先度の高い順に並べます。
• 検索期間と、終了カテゴリが除外されていることを明記します。
• 一致するものがない場合は、その旨を明確に伝えます。説明なしに空の表を返さないでください。
• ページ、バッチ、確認を完了できなかった場合は、表の前に確認できた内容と確認できなかった内容を記載します（references/QUERY_RESILIENCE.md を参照）。回答は references/QUERY_RESILIENCE.md §5 のルールに従い、CLI コマンド、内部フィールド名、推論の説明を含めないでください。
• ワークフロー D では、設定済みの Designer ごとに UX-Ready チケット数と Ticket の一覧（表示 ID、タイトル、プロダクト／バージョン、UX-Ready のタイムスタンプ）を示します。指定された期間、UX メンバー一覧の取得に使用したプロダクト、および履歴で確認された ux → READY イベントに基づくカウントであることを明記します。

References

• references/CAWPLAN_OPEN_API.md
• references/QUERY_RESILIENCE.md