bug-report

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation

自動化モード：modes.automation を解決します（project.local.yaml → project.yaml → デフォルトは collaborative）。すべての AskUserQuestion 呼び出しと すべてのファイル書き込みは、.claude/docs/automation-modes.md に従います （collaborative は常に質問 · guided は重大な場合のみ · autonomous は記録して続行； automation_always_ask カテゴリーでは常に確認します）。

バグ報告

下書きのみです。 このスキルはレポートを production/qa/bugs/ に書き込みます。原因がエンジン、 プラグイン、または他のベンダーのコードにある場合は、Notes の下にそのベンダーの トラッカー向けの下書きを追加して、そこで停止してください。そのリポジトリの課題や プルリクエストを登録、作成、またはコメントしてはいけません。ユーザーが提出します。

フェーズ 1：引数を解析する

引数からモードを特定します。

• キーワードなし → Description Mode：提示された説明から構造化されたバグ報告を作成します
• analyze [path] → Analyze Mode：対象ファイルを読み、潜在的なバグを特定します
• verify [BUG-ID] → Verify Mode：報告された修正によって実際にバグが解決したことを確認します
• close [BUG-ID] → Close Mode：検証済みのバグを、解決記録とともにクローズ済みとしてマークします

引数が指定されていない場合は、続行する前にユーザーにバグの説明を尋ねます。

---

フェーズ 2A：Description Mode

1. 説明を解析して、重要な情報を特定します。何が壊れたのか、いつ発生したのか、再現方法、期待される動作を確認します。

2. Grep/Glob を使って関連ファイルをコードベースから検索し、影響を受けるシステムや関連しそうなファイルなどの情報を補います。

3. バグ報告の下書きを作成します。

# Bug Report

## Summary
**Title**: [Concise, descriptive title]
**ID**: BUG-[NNNN]
**Severity**: [S1-Critical / S2-High / S3-Medium / S4-Low]
**Priority**: [P1-Fix this sprint / P2-Fix soon / P3-Backlog / P4-Won't fix]
**Status**: Open
**Reported**: [Date]
**Reporter**: [the reporter's name as the user gives it, else `—`; never an email address or account ID taken from the session]

## Classification
- **Category**: [Gameplay / UI / Audio / Visual / Performance / Crash / Network]
- **System**: [Which game system is affected — when the bug spans systems, the one whose code must change; the others go under Related systems]
- **Frequency**: [Always / Often (>50%) / Sometimes (10-50%) / Rare (<10%)]
- **Regression**: [Yes/No/Unknown -- was this working before?]

## Environment
- **Build**: [Version or commit hash]
- **Platform**: [OS, hardware if relevant]
- **Scene/Level**: [Where in the game]
- **Game State**: [Relevant state -- inventory, quest progress, etc.]

## Reproduction Steps
**Preconditions**: [Required state before starting]

1. [Exact step 1]
2. [Exact step 2]
3. [Exact step 3]

**Expected Result**: [What should happen]
**Actual Result**: [What actually happens]

## Technical Context
- **Likely affected files**: [List of files based on codebase search]
- **Related systems**: [What other systems might be involved]
- **Possible root cause**: [If identifiable from the description]

## Evidence
- **Logs**: [Relevant log output if available]
- **Visual**: [Description of visual evidence]

## Related Issues
- [Links to related bugs or design documents]

## Notes
[Any additional context or observations]

Severity と Priority のラベルには、/bug-triage の S と P の番号および名前を使います。これは、このファイルから解析されます。P4-Won't fix は P4 — Won't fix / Deferred（受容済みのリスク）を指し、要望リストではありません。いずれかの段階を変更する場合は、 .claude/skills/bug-triage/SKILL.md も変更してください。

---

フェーズ 2B：Analyze Mode

1. 引数で指定された対象ファイルを読み込みます。

2. 潜在的なバグを特定します。null 参照、オフバイワンエラー、競合状態、未処理のエッジケース、リソースリーク、不正な状態遷移などです。

3. 潜在的なバグごとに、上記のテンプレートを使ってバグ報告を作成します。発生しそうなトリガーのシナリオと推奨する修正を記入します。

---

フェーズ 2C：検証モード

番号でバグファイルを検索します。ここでもクローズモードでも、Glob production/qa/bugs/BUG-*.md を使い、ゼロ埋めの桁数にかかわらず、番号が [BUG-ID] と一致するファイルを選びます。スラッグ付きの古い3桁のファイルも番号で見つかります。一致するものがなければ、そこで停止します：「production/qa/bugs/ にバグ [BUG-ID] はありません。」判定：BLOCKED — 該当するバグがありません。

そのファイルを読みます。再現手順と期待される結果を抽出します。

1. 再現手順を再実行する — Grep/Glob を使って、根本原因となったコードパスが説明どおりにまだ存在するか確認します。修正によって削除または変更されている場合は、その変更を記録します。
2. 関連テストを実行する — バグのシステムにエンジンのテストルート内のテストファイル（Godot は tests/、Unity は Assets/Tests/、Unreal は Source/<Module>/Private/Tests/ — .claude/docs/directory-structure.md）がある場合は、Bash で project.yaml の commands.test を使って実行します。ランナーで指定できる場合は、影響を受けるスイートに対象を絞ります。エンジンに必要なフラグが抜けるため、記憶を頼りにランナーのコマンドを組み立ててはいけません（gdUnit4 は --remote-debug tcp://127.0.0.1:0 がないとハングします）。合格／不合格を報告します。commands.test が未設定の場合は、テストを実行していないことを示します。未設定のキー名を記載し、ステップ 3 に進みます。
3. 回帰を確認する — バグの原因となったパターンが新たにコードベースに出現していないか grep します。
4. 手動検証 — 関連テストが実行されなかった場合（バグをカバーするテストがない — qa.level によりテストが免除される通常のケース、commands.test が未設定、または実行が完了しなかった場合）、あるいは自動テストでは見た目を確認できない Visual または UI カテゴリのバグの場合は、AskUserQuestion で質問します：「修正を含むビルドで、再現手順を実際に試しましたか？どのビルドですか？」 — [No longer occurs] / [Still occurs] / [Not played yet]。 回答とビルドを、ユーザーの回答どおりに記録します。コードパスが変更されていても、それをユーザーの回答として扱ってはいけません。 サブエージェントとして実行していますか？ qa-lead はこのスキルを事前に読み込みますが、サブエージェントは AskUserQuestion を使用できません。返信の最後に質問と3つの選択肢を短いリストで記載し、まだ判定を出さないでください。呼び出し元がユーザーに質問し、回答を受けてから判定します。

検証判定を出します。

• VERIFIED FIXED — 該当するすべての確認でバグが解消されています。関連テストが実行されて合格し、ステップ 4 で質問した場合は、ユーザーが対象ビルドを明示して [No longer occurs] と回答している必要があります。テストを実行していない場合、実際に試したことのみが検証となり、手動検証として [user], manual, build [X] の形式で記録します。コードパスの変更だけでは、合格とはみなしません
• STILL PRESENT — 関連テストのバグ事例が失敗した、またはユーザーが [Still occurs] と回答した場合。修正で問題は解決していません
• CANNOT VERIFY — ステップ 4 に [Not played yet] と回答した場合：不足している内容、または実行できなかった内容（関連テストがない、commands.test が未設定、実行が完了しなかった、Visual または UI のバグ）を示し、再現手順を実際に試せば確認できることを伝えます。試した後、もう一度 /bug-report verify [BUG-ID] を実行してください

次のように尋ねます：「production/qa/bugs/[bug file] の Status を Verified Fixed / Still Present / Cannot Verify に更新してもよいですか？」— 上記で見つけたファイル名を、ゼロ埋めやスラッグにかかわらず指定します。Status とともに、その下に **Verified by**: 行を追加します。内容は [test file(s)] — ran and passed、または手動検証の場合は [user], manual, build [X] とします。

STILL PRESENT の場合：バグを再オープンし、Status を Open に戻して、/hotfix [BUG-ID] の再実行を提案します。

---

フェーズ 2D：クローズモード

verify モードと同様に、番号を使ってバグファイルを検索します。クローズする前に、Status が Verified Fixed であることを確認します。Status がそれ以外の場合は停止し、次のように伝えます。「バグ [ID] をクローズするには、Status が Verified Fixed である必要があります。先に /bug-report verify [BUG-ID] を実行してください。」

以下のクローズ記録と Status の変更内容を提示し、次のように尋ねます。「production/qa/bugs/[bug file] を更新して、Closed としてマークしてもよろしいですか？」はいと回答されるまで、何も書き込みません。いいえの場合は停止します。バグは Verified Fixed のままです。

はいの場合、クローズ記録をバグファイルに追記します。

## Closure Record
**Closed**: [date]
**Resolution**: Fixed — [one-line description of what was changed]
**Fix commit / PR**: [if known]
**Verified by**: [the verify record's `**Verified by**:` line — the test that ran and passed, or "[user], manual, build [X]"]
**Closed by**: [user]
**Regression test**: [test file path, or "Manual verification" when verify recorded a manual play]
**Status**: Closed

次に、最上位の **Status**: フィールドを **Status**: Closed に更新します。

クローズ後、production/qa/bug-triage-*.md を確認します。バグが未解決のトリアージレポートに記載されている場合は、次のように伝えます。「バグ [ID] はトリアージレポートに記載されています。未解決バグ数を更新するには、/bug-triage を実行してください。」

---

フェーズ 3：レポートの保存

完成したバグレポートをユーザーに提示します。

確認を求める前に ID を割り当てます。production/qa/bugs/BUG-*.md を Glob で検索し、最も大きい番号に 1 を加え、4 桁のゼロ埋め形式にします（該当ファイルがない場合は BUG-0001）。1 回の実行で複数のレポートを作成する場合（analyze モード）は、そこから連続した ID を各レポートに割り当てます。同じ ID を複数回使用してはいけません。

次のように尋ねます。「production/qa/bugs/BUG-[NNNN].md に書き込んでもよろしいですか？」複数のレポートの場合は、1 回で確認し、すべてのファイル名を示します。「production/qa/bugs/BUG-[NNNN].md、production/qa/bugs/BUG-[NNNN+1].md、…に書き込んでもよろしいですか？」

はいの場合、必要に応じてディレクトリを作成し、ファイルを書き込みます。判定：完了 — バグレポートを登録しました。

いいえの場合、ここで停止します。判定：ブロック — ユーザーが書き込みを拒否しました。

---

フェーズ 4：次のステップ

保存後、モードに応じて提案します。

登録後（Description／Analyze モード）：

• /bug-triage を実行し、既存の未解決バグと合わせて優先順位を付ける
• S1 または S2 の場合：緊急修正ワークフローとして /hotfix [BUG-ID] を実行する

バグの修正後（開発者が修正済みであることを確認した場合）：

• /bug-report verify [BUG-ID] を実行し、クローズする前に修正が実際に機能することを確認する
• 検証せずにバグをクローズしてはいけません。検証できない修正は、引き続き Open です

verify の結果が CANNOT VERIFY の場合：

• 修正を含むビルドで再現手順を実行し、その後、再度 /bug-report verify [BUG-ID] を実行して質問に回答する

verify の結果が VERIFIED FIXED の場合：

• /bug-report close [BUG-ID] を実行し、クローズ記録を書き込んで Status を更新する
• /bug-triage を実行して未解決バグ数を更新し、アクティブリストから削除する