Bug Fix Brief

Bug Fix Brief (BFB)

Overview

This skill generates a Bug Fix Brief (BFB): a structured document in docs/bfb/ that uniformly captures every bug fix with root cause, repro steps, fix options, and checklist.

When to Use

• User asks to create a BFB
• User wants to document a bug fix in a structured way
• After identifying the root cause of a bug and before implementing the fix

Trigger: "create BFB", "document bug", "bug fix brief", "document fix"

Instructions

Phase 1: Gather Information

Check existing numbering:

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

Ask the user for:

• BFB number (or propose next sequential)
• Concise title (3-5 words, kebab-case)
• Issue link (e.g. #1287)
• Environment (Prod/Stg/Dev) + version
• Observed vs expected behavior
• File/function/line of the cause

Phase 2: Generate Template

Complete the full BFB template:

## 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. ... → [error/output]

### 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]

Phase 3: Ask Confirmation

Show the generated BFB and ask with AskUserQuestion:

• "Create the BFB"
• "Edit before creating"
• "Cancel"

Phase 4: Write to Disk

Only after approval:

mkdir -p docs/bfb

Write to docs/bfb/BFB-XXX-title.md

Examples

Input: "create BFB for login email null crash"

Final output:

## 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. Open login screen
2. Tap "Login" without entering email → NullPointerException @ AuthManager.kt:34

### 3. Cause`AuthManager.kt` — `validateEmail()` @ line 34Missing 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

Best Practices

1. Sequential numbering: BFB-001, BFB-002, no gaps
2. Concise title: 3-5 words, kebab-case in filename
3. Root cause: exact file, function, line
4. 2+ fix options: with pros/cons and rationale
5. Verifiable checklist: each item must be testable

Constraints and Warnings

• Confirmation required: Always ask before writing
• Max 3 lines for cause: Stay concise
• Directory docs/bfb/: Create if it does not exist