triage-board

トリアージボード

次に着手する作業を決めるボードの各項目を入力します。コーディングエージェントだけでチケットを完了できるか、どの程度緊急か、どの種類の作業か、オーナー自身の時間がどれくらい必要かを設定します。内容を読み、判断し、整合させます。すべての書き込みは preflight-mutations によって許可されます。

5つの概念を扱います。ID を決めつけず、それぞれを実際のボードに照らして解決するため、この構成のプロジェクトであればどれでも実行できます。

概念	通常の形式	不足している場合
トリアージラベル	2つのリポジトリラベル、agent-ready と need-human	以下のゲート前に、ラベルの初期設定用カードを作成します
優先度	単一選択式のボードフィールド	停止して、その名前を示します
見積もり	数値型のボードフィールド	停止して、その名前を示します
種類	ボードフィールドではなく、組織レベルのイシュータイプ	停止して、その名前を示します
リリース	対象範囲を定めるイテレーション型のボードフィールド	明示的な対象範囲を求めます

順序が重要です。対象範囲、調整、判断、許可、書き込み、整合確認の順です。調整の承認前に下した判断は破棄されます。

1. ボードと台帳の保存場所を決める

まず、どのボードなのかを確定します。これが決まらなければ、セクション1のほかの作業には進めません。 ボードはオーナーと番号の組み合わせです。プロジェクト番号はオーナーごとに振り直されるため、番号だけではアカウントごとに異なるボードを指します。引数だけでボードを特定できるのは、オーナーと番号の両方を含む場合か、両方を解析できる URL の場合だけです。引数がない場合は、実行中のリポジトリにリンクされたボードを一覧表示し、オープンなものを確認します。

• オープンなボードがちょうど1つなら、それを選び、どのボードかを伝えます。
• 2つ以上なら、それぞれの番号とタイトルを示して、どれかを尋ねます。
• 1つもなければ、オーナーとプロジェクト番号を尋ねます。ボードは組織が所有し、どのリポジトリにもリンクされていない可能性があるためです。

作業ディレクトリや以前使ったボードから推測することはありません。同じリポジトリにオープンなボードが2つあるのは一般的な状況で、例外的なケースではありません。そのため、確認を求めるのは通常の結果であり、失敗ではありません。

次に、プロジェクトのフィールド、リポジトリのラベル、組織のイシュータイプ、そして認証に使っている認証情報のログイン名を読み取り、それぞれの安定した ID を記録します。そのログイン名は定義上、依頼者ではなくトークンの主体です。そのため、所有権の境界がその主体を基準にする前に、両者が同一人物であることを確認します。ボットまたは共有認証情報の場合は、実行を中止します。実行をまたいで ID を引き継ぐことはありません。フィールドが追加されたり、選択肢の名前が変更されたりしたボードでは、キャッシュされた ID によって誤った場所に書き込まれるためです。

今すぐ ${CLAUDE_SKILL_DIR}/references/board-queries.md を読み込みます。ここには正確なクエリと、それぞれがすべてを読み取ったことを証明するアサーションが記載されています。

存在しないラベルは、何も確認せずに作成するのではなく、専用のカードを通じて作成します。 リポジトリのラベル作成は共有状態への書き込みであるため、丁寧に尋ねるだけでは認可ステップに先立って実行できません。いずれかのラベルが存在しない場合は、両方のラベル名、色、対象となるすべてのリポジトリを記載したラベル作成カードを preflight-mutations 経由で申請し、判定が ready の場合に限って作成します。その後、リポジトリのラベルを再読み込みし、取得した ID を記録します。これはセクション5のラベル編集とは別のカードです。対象がイシューではなくリポジトリであり、取り消し可能性も異なるためです。

また、ほかの作業に進む前に、台帳をどこに保存するかも決めます。preflight-mutations は、すでに認可された永続的な保存先がない複数バッチの実行をブロックし、その保存先を新たに作成することも禁止しています。依頼者が今回の実行での書き込みを許可している既存の成果物を指定するか、依頼者に確認します。ゲートを通過するためにファイルをでっち上げることはありません。

台帳には候補ごとではなく、候補のフィールドごとに1行を記録します。これは、中断後に実行を再開するための記録です。候補ごとに、独立して失敗する3種類のアクションクラスにまたがって4回の書き込みが発生するため、候補ごとにステータスを1つだけ記録すると、書き込みの失敗が見えなくなるか、反映済みの見積もりが反映済み項目のみの合計から除外されてしまいます。Field は行を識別する項目であり、各行には現在値、提案値、根拠、ステータスをそれぞれ記録します。部分的な実行では、反映済みのフィールド行を保持し、保留中の行だけを再度カードにします。これは preflight-mutations が想定する再開形式です。

| Item ID | Issue | Owner | Kind | Field | Current | Proposed | Basis | Status |
|---|---|---|---|---|---|---|---|---|
| <item ID> | #<n> | <login> | leaf / umbrella | label / priority / estimate / type | <value> | <value> | <evidence> | candidate / pending / landed / failed / skipped / reconcile-required / conflicted / excluded |

除外項目も台帳の行として記録しますが、フィールドを持たない唯一の形式です。除外項目ごとに1行だけ作成し、Field: none、Current と Proposed は空欄、Basis には除外理由、Status: excluded を記録します。この形式がなければ、中断後にセクション2で必要となる理由が失われ、再開時の除外件数が初回の実行時と異なって報告されます。

ゲート。 ボードが推測ではなく明示的に指定され、実行に必要なすべての概念の ID が解決され、依頼者の身元が判明し、台帳の保存先が認可されていること。満たされていない場合は、不足しているものを示して実行を中止します。

2. 対象範囲を決める

引数がない場合は、ボードの稼働中の iterations リストに含まれるすべてのイテレーションから、依頼者が唯一の担当者になっている未完了の課題をすべて対象にします。このリストには現在進行中のイテレーションと今後のすべてのイテレーションが含まれるため、すでに着手している作業も除外せずにトリアージします。完了したイテレーションは別のリストにあり、指定した場合にのみ対象になります。引数を指定すると、対象を特定のリリース、ステータス、または明示的な番号のリストに絞り込みます。

課題と同じボードにあるプルリクエストとドラフト項目は除外します。これらには設定対象のフィールドがないためです。

依頼されなくても、ボードの所有権ポリシーを適用します。複数の担当者がいるチケット、担当者がいないチケット、所有者が曖昧なチケットは、技術的なアクセス権がどれほど広くても読み取り専用です。除外する項目はすべて、その理由とともに記録します。項目を黙って除外して集計した合計よりも、除外内容を明示した小さな合計のほうがよいためです。

ゲート。 候補集合が正確で、除外する項目すべてに理由があり、各候補が candidate の台帳行になっています。

3. 基準を確認してからプレビューする

バッチを評価する前に、一度だけ、ひとつの質問で確認します。${CLAUDE_SKILL_DIR}/references/calibration.md には、提案するデフォルト値として、見積もりの単位、尺度、丸め方と上限、範囲全体をカバーする具体例、優先度の基準、この実行にあたって依頼者が希望するプロジェクト固有の優先度調整が記載されています。

見積もりの単位はデフォルトで人間の実作業時間とし、その定義と具体例は ${CLAUDE_SKILL_DIR}/references/calibration.md に記載されています。

基準を承認することと、数値を承認することは同じではありません。そのため次に、この範囲から実際のチケットを3～5件見積もります。最小、典型、最大のチケットと、包括的なチケットがあればそれを含め、判断理由と小計を示します。候補が3件未満の場合は、依頼者に数字を見てもらうことが目的であり、件数を満たすことが目的ではないため、すべてをプレビューします。候補がない場合は、基準の確認、評価、すべての書き込みを省略し、合計をゼロとして除外リストを含むレポートを直接作成します。依頼者がプレビューを承認してから、台帳行を candidate から pending に移します。承認がなければ、依頼者が最初に目にする適用済みの数値は、すべての書き込みが完了した後になってしまいます。

単位、尺度、具体例、基準、所有権の境界、または包括的なチケットの扱いに変更があった場合、まだ書き込んでいないすべての行が無効になります。

ゲート。 依頼者が基準と、自身のチケットを使ったプレビューの両方を承認しています。

4. すべての候補を評価する

各チケットの本文全体を読み、トリアージラベル、優先度、見積もり、タイプの4つの値を記録します。

トリアージラベルは、ひとつの問いに答えるものです。正しい振る舞いはすでに決まっていますか。 ${CLAUDE_SKILL_DIR}/references/triage-rubric.md には、チケットの書き方がどれほど優れていても need-human とする5つの条件と、簡単に判断できる表現が記載されています。難しさは判断に関係ありません。300個のファイルに触れる面倒なチケットでも、結果が明確なら agent-ready です。一方、どの行を変更するか誰も決めていないなら、1行の修正でも need-human です。

分散処理は、デフォルトではなく件数のしきい値で決めます。 候補が約40件未満なら、インラインで読みます。それを超える場合は基準を1つのファイルに書き、約30件ずつのバッチを並列の読み手に渡し、それぞれに判定結果のみを返してもらいます。2回目の確認が必要な場合も、本文をすでに把握している同じ読み手を再利用し、本文を読み直さないようにします。

各バッチでは、渡したリストとの網羅性の差分を確認します。30件のチケットに対して29件の判定しか返さない読み手は、1件を黙って抜かしています。これを検出できるのは差分だけです。

ゲート。 すべての候補に4つの値がすべて記録され、すべてのバッチが渡されたリストを漏れなくカバーしています。

5. 書き込みを承認する

ボードとフィールドの ID、アイテム ID、現在値と提案値、所有権ポリシー、承認済みのキャリブレーションとプレビュー、可逆性、復旧計画、無効化要因、権威ある読み戻し計画を指定して、preflight-mutations を実行します。

実行ごとではなく、アクションの種類ごとに 1 枚のカードを作成します。 preflight-mutations は対象とアクションごとにカードを分けます。このスキルでは、リポジトリのラベル、ボードのフィールド値、組織のイシュータイプという 2 つのサーフェスにまたがる 3 つの異なるアクションを実行します。それぞれに専用のカードと読み戻し計画を用意します。同じ種類のアクションについては、アイテムごとではなく、バッチ全体を 1 枚のカードで扱います。

ゲート。 実行する書き込みはすべて、該当するアクション種類の、現在 ready であるカードに基づいています。

6. 書き込みを実行し、反映を確認する

承認された書き込みだけを実行し、すべての応答をログに記録したうえで、変更したフィールドをすべて権威ある情報源から再読み込みし、台帳とフィールドごとに照合します。

${CLAUDE_SKILL_DIR}/references/board-queries.md に両方の事例の根拠が記載されています。ボードの変更処理は、永続化されていなくても成功を報告することがあり、イシュー検索インデックスは更新が遅れるうえに結果が切り詰められます。そのため、終了コードが 0 でも証拠にはなりません。また、ラベルはリストではなくイシューオブジェクトを読み取って確認します。

値の形式が不正だと、一見問題のない実行の途中で 1 行だけ失敗することがあるため、ログの末尾だけでなく、書き込みログ全体を grep して失敗を確認します。

その後、各行のステータスを、実際に観測された状態に基づいて確定します。

• 読み戻しで確定できる場合は、landed、failed、または skipped。
• 読み戻しで書き込みが反映されたか確認できない場合は、reconcile-required。そのアイテムの処理を停止し、権威あるクエリで解決するまでは、再試行も failed への分類もしません。
• 読み戻しで測定後に値が変更されているとわかった場合は、conflicted。これは実行中に誰かがボードを編集したことを意味します。決して上書きしません。両方の値を報告し、依頼者に判断を委ねます。

ゲート。 実行した書き込みにはすべて、コマンド出力ではなく、実際に観測された状態に基づく上記いずれかのステータスを付けます。

7. 報告する

依頼者に次の内容を伝えます。

• トリアージラベル別、優先度別、タイプ別の件数。
• 見積もりの合計をトリアージラベル別に分けた内訳。両者は同じ意味ではないためです。need-human のチケットに割り当てられた時間は、エージェントが着手する前に消化する必要があるため、スループットを予測できるのは agent-ready の小計だけです。
• 見積もりが上限に達したチケットすべて。上限では実際の規模がわからず、通常はチケットの分割が必要なため、チケット名を挙げます。
• conflicted、reconcile-required、failed、excluded の各行すべて。
• 判断が本当に微妙だったもの。依頼者が覆せるようにします。

合計は landed の行だけから算出します。読み戻しができなかった場合は、書き込み予定の値と reconcile-required の一覧を報告し、確認済みの合計は主張しません。

すべての候補に最終ステータスが付き、報告した合計を landed の値から再現できた時点で、実行は完了です。