triage

トリアージ

プロジェクトのイシュートラッカー上で、トリアージ担当の小さなステートマシンを使ってイシューを進めます。

このリポジトリで外部プルリクエストを依頼の窓口として扱う場合（イシュートラッカーの設定を参照）、トリアージの対象には外部プルリクエストも含まれます。PR はコードが添付されたイシューとして、以下で「PR の場合」と記された差分を除き、同じ担当、同じ状態、同じステートマシンを使います。単独の #42 は、トラッカーの設定に従ってイシューまたは PR として解決します。

トリアージ中にイシュートラッカーへ投稿するすべてのコメントやイシューは、必ず次の免責事項から始めてください。

> *This was generated by AI during triage.*

参考ドキュメント

• AGENT-BRIEF.md：長く使えるエージェントブリーフの書き方
• OUT-OF-SCOPE.md：.out-of-scope/ ナレッジベースの仕組み

担当

カテゴリ担当は2種類です。

• bug：何かが壊れています
• enhancement：新機能または改善です

状態担当は5種類です。

• needs-triage：メンテナーによる評価が必要です
• needs-info：報告者からの追加情報を待っています
• ready-for-agent：仕様が完全に定まり、AFK エージェントが対応できます
• ready-for-human：人間による実装が必要です
• wontfix：対応しません

PR の場合、同じ状態は添付されたコードを基準に読み替えます。ready-for-agent はブリーフが添付されており、エージェントが差分の次のステップに進むべき状態です。ready-for-human は、人間がマージできる状態です。

トリアージ済みのイシューには、カテゴリ担当をちょうど1つ、状態担当もちょうど1つ付けてください。状態担当が競合している場合は、その旨を伝え、ほかの作業を始める前にメンテナーに確認してください。

これらは正式な担当名です。イシュートラッカーで実際に使用するラベル文字列は異なる場合があります。対応関係は提示されているはずです。提示されていない場合は、ユーザーに /setup-matt-pocock-skills を実行するよう伝えてください。

状態遷移：ラベルのないイシューは通常、まず needs-triage に移行します。そこから needs-info、ready-for-agent、ready-for-human、wontfix のいずれかに移行します。needs-info は、報告者から返信があった時点で needs-triage に戻ります。メンテナーはいつでも状態を上書きできます。不自然に見える状態遷移があれば、その旨を伝え、実行前に確認してください。

呼び出し

メンテナーは /triage を呼び出し、自然な言葉で希望する作業を説明します。依頼を解釈して対応してください。例：

• 「対応が必要なものを表示して」
• 「#42 を見てみよう」（イシューまたは PR）
• 「#42 を ready-for-agent に移して」
• 「エージェントが着手できるものはどれ？」

対応が必要な項目の表示

イシュートラッカーを検索し、3つのグループに分けて古い順に表示します。

1. ラベルなし：トリアージが一度も行われていません。
2. needs-triage：評価中です。
3. トリアージのメモ以降に報告者の活動があった needs-info：再評価が必要です。

PR が対象に含まれる場合は、外部 PR も各グループに含め、各行に [PR] または [issue] を付けてください。検出対象となるのは外部 PR のみです（誰を外部とみなすかはトラッカーの設定で定義されています）。そのため、コラボレーターによる進行中の PR はトリアージ対象ではありません。このフィルターは検出時のみ適用されます。明示的に指定された PR は、投稿者にかかわらず必ずトリアージしてください。

件数と、項目ごとの1行の概要を表示します。次に行う項目はメンテナーに選んでもらってください。

特定の Issue または PR をトリアージする

1. コンテキストを収集します。 Issue または PR の全内容（本文、コメント、ラベル、作成者、日付。PR の場合は差分も）を読みます。以前のトリアージメモを確認し、解決済みの質問を再度尋ねないようにします。プロジェクトのドメイン用語集を使ってコードベースを調べ、該当領域の ADR を順守します。コードベースに対して次の 2 つの確認を行います。（a）重複：依頼の文言だけでなく、ドメイン概念を手がかりに、依頼された動作がすでに実装されていないか検索し、調べた場所を報告します。見つかった場合は、すでに実装済みの wontfix です（ステップ 5）。（b）過去の却下：.out-of-scope/*.md を読み、この依頼に類似するものがあれば提示します。

2. 推奨を提示します。 分類と対応方針を、理由とともにメンテナーに伝えます。また、依頼に関連するコードベースの概要（すでに実装されているかどうかを含む）も簡潔に示します。指示を待ちます。

3. 主張を検証します。 詳細な質問をする前に、主張が正しいか確認します。バグの場合は、報告者の手順に従って再現します。PR の場合は、差分が主張どおりの動作をするか確認します。チェックアウトし、関連するテストまたはコマンドを実行します。結果を、確認済み（コードパスを含む）、失敗、または詳細不足（needs-info の強い根拠）のいずれかとして報告します。検証済みであることは、エージェント向けブリーフの説得力を大きく高めます。

4. 詳細を確認します（必要な場合）。 依頼を具体化する必要がある場合は、Skill ツールを「grilling」と「domain-modeling」で 2 回呼び出し、質問を 1 回に 1 ラウンドずつ行って内容を練り上げます。ドメイン用語を明確にし、決定事項が固まり次第、GLOSSARY.md／ADR をその場で更新します。

5. 結果を適用します。

   • ready-for-agent：エージェント向けブリーフのコメントを投稿します（AGENT-BRIEF.md）。
   • ready-for-human：エージェント向けブリーフと同じ構成にしますが、委任できない理由（判断を要する事項、外部アクセス、設計上の決定、手動テスト）を記載します。
   • needs-info：トリアージメモを投稿します（以下のテンプレート）。
   • wontfix の場合は、理由に応じたコメントを添えて Issue をクローズします。
     • すでに実装済み：変更はすでにコードベースに存在します。その場所を示します。.out-of-scope/ には書き込まないでください。このナレッジベースは、却下した依頼向けであり、実装済みの機能向けではありません。
     • 却下（バグ）：丁寧に説明してからクローズします。
     • 却下（機能追加）：.out-of-scope/ に記録し、コメントからリンクしてからクローズします（OUT-OF-SCOPE.md）。
   • needs-triage：担当ロールを適用します。進捗が一部ある場合は、コメントを投稿してもかまいません。

状態のクイック上書き

メンテナーから「move #42 to ready-for-agent」と指示された場合は、その指示を信頼して担当ロールを直接適用します。実行前に、これから行うこと（ロールの変更、コメント、クローズ）を確認してから実行します。詳細確認は省略します。詳細確認のセッションを行わずに ready-for-agent に移行する場合は、エージェント向けブリーフを作成するかどうか尋ねます。

Needs-info テンプレート

## Triage Notes

**What we've established so far:**

- point 1
- point 2

**What we still need from you (@reporter):**

- question 1
- question 2

「ここまでに確定したこと」の下に、詳細確認を通じて解決した内容をすべて記録し、作業内容が失われないようにします。質問は具体的で、対応可能なものにします。「詳細を教えてください」のような質問は避けます。

前回のセッションの再開

Issue または PR に以前のトリアージメモがある場合は、それを読み、報告者が未解決の質問に回答しているか確認してから、最新の状況を提示し、続行します。解決済みの質問は再度尋ねないでください。