triage-issue

イシューのトリアージ

報告された問題を調査し、根本原因を特定して、TDD に基づく修正計画を添えた GitLab または GitHub のイシューを作成します。これは基本的にユーザーの手を煩わせないワークフローです。ユーザーへの質問は最小限にしてください。

前提条件

• gh（GitHub CLI）：プロジェクトが GitHub を使用している場合に必要です。https://cli.github.com または brew install gh からインストールしてください
• glab（GitLab CLI）：プロジェクトが GitLab を使用している場合に必要です。https://gitlab.com/gitlab-org/cli または brew install glab からインストールしてください

このスキルを使用するタイミング

次の場合にこのスキルを有効にしてください。

• ユーザーからバグや予期しない動作の報告があった
• ユーザーが「トリアージ」または「このイシューを調査して」と言った
• 問題に遭遇した後、イシューを登録したいとユーザーが希望している
• 根本原因を理解し、修正を計画したいとユーザーが希望している
• 調査を含むバグ報告の作成をユーザーが依頼している

プロセス

1. 問題を把握する

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

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

2. 調査して診断する

コードベースを詳しく調査します。目標は次の点を特定することです。

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

次を確認します。

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

3. 修正方針を特定する

調査に基づき、次の点を判断します。

• 根本原因を修正するために必要な最小限の変更
• 影響を受けるモジュールやインターフェース
• テストで検証すべき動作
• これがリグレッションなのか、機能不足なのか、設計上の欠陥なのか

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

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

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

ルール：

• テストでは実装の詳細ではなく、公開インターフェースを通じて動作を検証する
• テストは一度にひとつずつ、垂直スライスで進める（先にすべてのテストを作成し、その後にすべてのコードを実装するのではありません）
• 各テストは、内部をリファクタリングしても有効であり続ける必要がある
• 必要に応じて、最後にリファクタリングのステップを含める
• 長期的な堅牢性：コードベースが大幅に変更されても有効な修正のみを提案してください。内部構造ではなく、動作と契約を説明してください。テストでは内部状態ではなく、観測可能な結果（API レスポンス、UI の状態、ユーザーに見える効果）を検証します。良い提案は仕様のように読めます。悪い提案は差分のように読めます。

5. プラットフォームを検出する

イシューを作成する前に、プロジェクトが GitLab と GitHub のどちらを使用しているか検出します。

1. GitLab の兆候を確認する：
   • リポジトリのルートに .gitlab-ci.yml ファイルがある
   • Git のリモート URL に gitlab が含まれている（例：git remote -v）
2. GitHub の兆候を確認する：
   • リポジトリのルートに .github/ ディレクトリがある
   • Git のリモート URL に github.com が含まれている（例：git remote -v）
3. 判定できない場合： 両方が検出された場合、またはどちらも検出されなかった場合は、「このプロジェクトでは GitLab と GitHub の両方が使われているようです（または、どちらを使っているか特定できませんでした）。どちらのプラットフォームにイシューを作成しますか？」とユーザーに尋ねます。

6. イシューを作成する

検出したプラットフォームでイシューを作成します。作成前にユーザーへ確認を求めず、そのまま作成して URL を共有してください。

GitHub の場合

以下のイシューテンプレートを使って gh issue create を実行します。

GitLab の場合

GitLab CLI（glab issue create）または CLI 経由の GitLab API を使います。project_id（group/project のような URL エンコードされたパス、または数値 ID）が必要です。不明な場合は、Git のリモート URL から特定してください。

イシューテンプレート

両方のプラットフォームでこのテンプレートを使用します（Markdown 形式は GitLab と GitHub のどちらにも対応しています）。

## Problem

A clear description of the bug or issue, including:
- What happens (actual behavior)
- What should happen (expected behavior)
- How to reproduce (if applicable)

## Root Cause Analysis

Describe what you found during investigation:
- The code path involved
- Why the current code fails
- Any contributing factors

Do NOT include specific file paths, line numbers, or implementation details that couple to current code layout. Describe modules, behaviors, and contracts instead. The issue should remain useful even after major refactors.

## TDD Fix Plan

A numbered list of RED-GREEN cycles:

1. **RED**: Write a test that [describes expected behavior]
   **GREEN**: [Minimal change to make it pass]

2. **RED**: Write a test that [describes next behavior]
   **GREEN**: [Minimal change to make it pass]

...

**REFACTOR**: [Any cleanup needed after all tests pass]

## Related Issues

[Link to any existing issues that reported this bug or are related. Use `#<number>` for same-project references, or full URLs for cross-project references. If this was reported in an issue tracker, link to the original report here.]

## Acceptance Criteria

- [ ] Root cause is fixed, not just the symptom
- [ ] All new tests pass
- [ ] Existing tests still pass
- [ ] [Additional criteria specific to this bug]

プラットフォーム固有の注意事項

GitHub:

• bug、triage、またはプロジェクト固有のラベルを使用します
• gh issue create コマンドは、--title、--body、--label フラグをサポートしています
• 関連する課題には #<number> の構文でリンクします
• 課題を修正する PR は、PR の説明に「Fixes #XX」と記載して参照します

GitLab:

• bug、priority::high、status::triage などのスコープ付きラベルを使用します
• 同じプロジェクトの関連する課題には #<number>、別のプロジェクトの課題には group/project#<number> を使ってリンクします
• 課題を修正する MR は、MR の説明に「Closes #XX」と記載して参照します
• セルフホスト版の GitLab インスタンスを利用できる場合は、すべての参照にその URL を使用します

7. 報告

課題を作成した後：

1. 課題の URL を出力します
2. 根本原因を1行で要約して出力します
3. このバグが既存の課題で最初に報告されていた場合は、新しいトリアージ課題からその課題にリンクしたことを記載します

重要なルール

• まず調査し、質問は後にします。 ユーザーに何度も質問しないでください。自分でコードベースを調べ、本当に行き詰まった場合にのみユーザーに質問してください。
• 課題の説明にファイルパスを記載しないでください。 リファクタリング後、ファイルパスは古くなります。代わりに、モジュール、動作、契約について説明してください。コードベースが変化した後も有用な課題にしてください。
• 修正計画は TDD に基づくものに限ります。 すべての修正を RED-GREEN サイクルの手順として説明してください。「バグを修正する」といった曖昧な指示は避けてください。
• 正確さよりも耐久性を重視します。 良い課題は動作仕様として読めます。悪い課題は、現在のコードとの差分のように読めます。
• 既存の課題にリンクします。 ユーザーが既存の課題番号に言及した場合、または調査中に関連する課題を見つけた場合は、必ず「Related Issues」セクションでリンクしてください。
• 根本原因ごとに課題を1つ作成します。 調査の結果、互いに独立した複数のバグが判明した場合は、それぞれ別の課題を作成してください。