triage

トリアージ

小規模なトリアージロールのステートマシンを使って、プロジェクトのイシュートラッカー上で issue を移動します。

このリポジトリが external pull request をリクエストの窓口として扱う場合（issue-tracker 設定を参照）、トリアージの対象にはそれらも含まれます。PR は追加コードを伴う issue です。同じロール、同じ状態、同じマシンを使い、以下で「PR の場合」と記された箇所だけが異なります。トラッカーの設定に従って、裸の #42 が issue と PR のどちらを指すか解釈します。

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

> *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 は人間がマージできる状態を示します。

トリアージ済みの各 issue には、カテゴリロールがちょうど 1 つ、状態ロールがちょうど 1 つ付いている必要があります。状態ロールが競合している場合は、その旨を示し、ほかの作業を行う前にメンテナーに確認してください。

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

状態の遷移：ラベルのない issue は通常、まず needs-triage になります。その後、needs-info、ready-for-agent、ready-for-human、または wontfix に移動します。needs-info は報告者が返信した後、needs-triage に戻ります。メンテナーはいつでも上書きできます。不自然に見える遷移は、その旨を示し、続行する前に確認してください。

呼び出し

メンテナーは /triage を呼び出し、自然言語で希望を説明します。リクエストを解釈して対応してください。例：

• 「注意が必要なものをすべて表示して」
• 「#42 を確認しましょう」（issue または PR）
• 「#42 を ready-for-agent に移動して」
• 「エージェントが対応できるものはありますか？」

注意が必要な項目の表示

イシュートラッカーを検索し、古いものから優先して 3 つのバケットに分けて表示します：

1. ラベルなし：まだトリアージされていないもの。
2. needs-triage：評価中のもの。
3. 最後のトリアージメモ以降に報告者の動きがある needs-info：再評価が必要なもの。

PR が対象範囲に含まれる場合は、external PR もこれらのバケットに含め、各行に [PR] または [issue] を付けます。検出時に表示するのは external PR のみです（誰が external に該当するかはトラッカー設定で定義されます）。共同作業者による進行中の PR はトリアージ対象ではありません。このフィルターは検出時にのみ適用されます。明示的に指定された PR は、作者が誰であってもトリアージします。

各バケットの件数と、各 issue の 1 行の要約を表示します。メンテナーに選択してもらいます。

特定の issue または PR のトリアージ

1. コンテキストを収集します。 issue または PR の全内容（本文、コメント、ラベル、作者、日付。PR の場合は差分も含む）を読みます。以前のトリアージメモを確認し、解決済みの質問を再度尋ねないようにします。プロジェクトのドメイン用語集を使ってコードベースを調べ、関連する ADR に従います。コードベースを照らし合わせて 2 つの確認を行います。(a) 重複性：リクエストの言い回しだけでなく、ドメインの概念に基づいて、依頼された動作の既存実装を検索し、調査した場所を報告します。見つかった場合は、すでに実装済みの wontfix です（step 5）。(b) 過去の却下：.out-of-scope/*.md を読み、このリクエストに類似する過去の却下例があれば提示します。

2. 推奨します。 推奨するカテゴリと状態、その理由をメンテナーに伝え、リクエストに関連する簡潔なコードベースの概要（すでに実装されているかどうかを含む）を示します。指示を待ちます。

3. 主張を検証します。 問題を掘り下げる前に、その主張が正しいか確認します。バグの場合は、報告者の手順で再現します。PR の場合は、差分が主張どおりに動作することを確認します。PR をチェックアウトし、関連するテストやコマンドを実行してください。確認できたことを報告します。確認済み（コードパスを提示）、失敗、または詳細不足（needs-info とする強い根拠）のいずれかです。検証済みの情報があれば、エージェントブリーフをより確かなものにできます。

4. 掘り下げます（必要な場合）。 リクエストをさらに具体化する必要がある場合は、grilling と domain-modeling をそれぞれ指定して Skill ツールを 2 回呼び出します。段階的に掘り下げて形にし、決定事項が固まったらドメイン用語を洗練させ、GLOSSARY.md／ADR をインラインで更新します。

5. 結果を適用します：

   • ready-for-agent：エージェントブリーフのコメントを投稿します（AGENT-BRIEF.md）。
   • ready-for-human：エージェントブリーフと同じ構成を使いますが、委任できない理由（判断を要する箇所、外部アクセス、設計上の判断、手動テスト）を説明します。
   • needs-info：トリアージメモを投稿します（下記のテンプレートを参照）。
   • wontfix：close し、コメントの内容は理由によって異なります：
     • 実装済み：変更がコードベースにすでに存在します。該当箇所を示します。.out-of-scope/ には記録しないでください（この KB は却下されたリクエスト用であり、すでに実装されたもの用ではありません）。
     • 却下（バグ）：丁寧に説明してから close します。
     • 却下（機能強化）：.out-of-scope/ に記録し、コメントからリンクしてから close します（OUT-OF-SCOPE.md）。
   • needs-triage：ロールを適用します。部分的に進展があれば、コメントを投稿してもかまいません。

状態のクイック上書き

メンテナーが「#42 を ready-for-agent に移動して」と言った場合は、その指示を信頼してロールを直接適用します。実行しようとしている内容（ロールの変更、コメント、close）を確認してから、実行してください。掘り下げは省略します。掘り下げのセッションなしで 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 にトリアージメモがすでにある場合は、それを読み、未解決の質問に報告者が回答しているか確認し、続行する前に状況を更新して提示します。解決済みの質問を再度尋ねないでください。