triage-issue

Issue のトリアージ

報告された問題を調査して根本原因を特定し、TDD による修正計画を含む GitHub issue を作成します。ほとんどの作業を自動で進めるワークフローです。ユーザーへの質問は最小限に抑えてください。

プロセス

1. 問題を把握する

ユーザーから問題の簡単な説明を聞きます。まだ説明がない場合は、質問を 1 つだけします。「どのような問題が発生していますか？」

この段階では、追加の質問をしないでください。すぐに調査を開始します。

2. 調査と診断

subagent_type=Explore を指定して Agent ツールを使い、コードベースを詳しく調査します。次の点を特定してください。

• どこで バグが発生するか（エントリーポイント、UI、API レスポンス）
• どの コードパスが関係するか（処理の流れを追跡）
• なぜ 失敗するか（症状だけでなく根本原因）
• どのような 関連コードがあるか（類似パターン、テスト、隣接するモジュール）

次を確認します。

• 関連するソースファイルとその依存関係
• 既存のテスト（テスト済みの内容と不足している内容）
• 影響を受けるファイルの最近の変更（関連ファイルに対する git log）
• コードパス内のエラー処理
• コードベース内の他の場所にある、正しく動作する類似パターン

3. 修正方法を特定する

調査結果に基づいて、次の点を判断します。

• 根本原因を修正するために必要な最小限の変更
• 影響を受けるモジュール／インターフェース
• テストで検証する必要がある動作
• 回帰、機能不足、設計上の問題のいずれに当たるか

4. TDD 修正計画を設計する

RED-GREEN サイクルを具体的な順序で列挙します。各サイクルは、垂直スライス 1 つ分です。

• RED：壊れている、または不足している動作を捉える具体的なテストを説明します
• GREEN：そのテストを通すための最小限のコード変更を説明します

ルール：

• テストでは実装の詳細ではなく、公開インターフェースを通じて動作を検証します
• 一度にテストは 1 つずつ進め、垂直スライスで実施します（最初にすべてのテストを書いてから、すべてのコードを書く方法は不可）
• 各テストは、内部のリファクタリング後も有効である必要があります
• 必要に応じて最後にリファクタリングの手順を加えます
• 永続性：コードベースが大幅に変更されても有効な修正案だけを提示します。内部構造ではなく、動作と契約を説明します。テストでは内部状態ではなく、観察可能な結果（API レスポンス、UI の状態、ユーザーに見える効果）を検証します。良い提案は仕様のように読めます。悪い提案は差分のように読めます。

5. GitHub issue を作成する

以下のテンプレートを使い、gh issue create で GitHub issue を作成します。作成前にユーザーへレビューを求めないでください。そのまま作成し、URL を共有します。

問題

バグや問題について、次の内容を含む明確な説明を記載します。

• 何が起きているか（実際の動作）
• どうなるべきか（期待される動作）
• 再現方法（該当する場合）

根本原因の分析

調査で判明した内容を説明します。

• 関係するコードパス
• 現在のコードが失敗する理由
• 影響を与えているその他の要因

現在のコード配置に依存する具体的なファイルパス、行番号、実装の詳細は記載しないでください。モジュール、動作、契約を説明します。大規模なリファクタリングの後も役立つ issue にしてください。

TDD 修正計画

RED-GREEN サイクルを番号付きで列挙します。

1. RED：[期待される動作を説明するテストを作成] GREEN：[テストを通すための最小限の変更]

2. RED：[次の動作を説明するテストを作成] GREEN：[テストを通すための最小限の変更]

...

REFACTOR：[すべてのテストが通った後に必要な整理]

受け入れ条件

• 条件 1
• 条件 2
• 追加したテストがすべて通る
• 既存のテストも引き続き通る

issue の作成後、issue の URL と根本原因の 1 行の要約を出力します。