bug-fix-brief

バグ修正概要（BFB）

概要

このスキルは、根本原因、再現手順、修正案、チェックリストを含む、すべてのバグ修正を統一的に記録する構造化ドキュメントであるバグ修正概要（BFB）を docs/bfb/ に生成します。

使用するタイミング

• ユーザーが BFB の作成を依頼したとき
• ユーザーがバグ修正を構造化された形式で記録したいとき
• バグの根本原因を特定した後、修正を実装する前

トリガー：「BFB を作成」「バグを記録」「バグ修正概要」「修正を記録」

手順

フェーズ 1：情報を収集する

既存の番号を確認します：

ls docs/bfb/ 2>/dev/null || echo "Directory does not exist"

ユーザーに次の情報を尋ねます：

• BFB 番号（または次の連番を提案）
• 簡潔なタイトル（3～5 語、ケバブケース）
• Issue のリンク（例：#1287）
• 環境（Prod／Stg／Dev）＋バージョン
• 実際の動作と期待される動作
• 原因となったファイル／関数／行番号

フェーズ 2：テンプレートを生成する

BFB のテンプレート全体を記入します：

## BFB-XXX: [Title]

**Reference:** [Issue link]
**Environment:** [Env] `vX.Y.Z`
**Date:** YYYY-MM-DD

---

### 1. Bug
- **Observed:** [wrong behavior]
- **Expected:** [correct behavior]

### 2. Repro

1. ...
2. ... → [エラー／出力]

### 3. Cause
`path/file.ext` — `function()` @ line N
[Why it happens, max 3 lines]

### 4. Decision
| Option | Fix | Choice |
|--------|-----|--------|
| A | [desc] | ✅/❌ |
| B | [desc] | ✅/❌ |

**Rationale:** [why]

### 5. Fix
- [ ] [change 1]
- [ ] [test]
- [ ] [verify repro]

### 6. Notes
[recurring patterns, links, warnings]

フェーズ 3：確認を求める

生成した BFB を表示し、AskUserQuestion を使って次の選択肢を提示します：

• 「BFB を作成」
• 「作成前に編集」
• 「キャンセル」

フェーズ 4：ディスクに書き込む

承認を得た後に限り：

mkdir -p docs/bfb

docs/bfb/BFB-XXX-title.md に書き込みます

例

入力：「ログイン時のメールアドレス null クラッシュの BFB を作成」

最終出力：

## BFB-042: Login crash with null email

**Reference:** #1287
**Environment:** Prod `v2.4.1`
**Date:** 2026-05-02

---

### 1. Bug
- **Observed:** App crashes if email field is empty
- **Expected:** Error message "Email required"

### 2. Repro

1. ログイン画面を開く
2. メールアドレスを入力せずに「Login」をタップする → AuthManager.kt:34 で NullPointerException

### 3. Cause
`AuthManager.kt` — `validateEmail()` @ line 34
Missing null check on email.trim()

### 4. Decision
| Option | Fix | Choice |
|--------|-----|--------|
| A | Add safe call `?.` | ✅ |
| B | Refactor with Result type | ❌ |

**Rationale:** Option A is minimal, zero impact.

### 5. Fix
- [ ] Add `email?.trim()?.isNotEmpty() == true`
- [ ] Test `validateEmail_null_returnsFalse()`
- [ ] Verify repro

### 6. Notes
- Check other forms for missing null checks

ベストプラクティス

1. 連番を使用する：BFB-001、BFB-002 のように、番号を飛ばさない
2. 簡潔なタイトル：3～5 語とし、ファイル名にはケバブケースを使用する
3. 根本原因：正確なファイル、関数、行番号を記載する
4. 2 つ以上の修正案：メリット／デメリットと根拠を示す
5. 検証可能なチェックリスト：各項目をテスト可能にする

制約と警告

• 確認が必須：書き込む前に必ず確認を求めます
• 原因は最大 3 行：簡潔にまとめます
• ディレクトリ docs/bfb/：存在しない場合は作成します