Back to Details

bug-fix-brief

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bug Fix Brief (BFB)

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.
本技能可生成Bug Fix Brief（BFB）：一种存储在
docs/bfb/
目录下的结构化文档，用于统一记录每一项Bug修复的根本原因、复现步骤、修复方案选项及检查清单。

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"
  • 用户要求创建BFB
  • 用户希望以结构化方式记录Bug修复过程
  • 确定Bug根本原因后、实施修复之前
触发词： "create BFB", "document bug", "bug fix brief", "document fix"

Instructions

操作步骤

Phase 1: Gather Information

阶段1：收集信息

Check existing numbering:
bash
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
检查现有编号：
bash
ls docs/bfb/ 2>/dev/null || echo "Directory does not exist"
向用户询问以下信息：
  • BFB编号（或建议下一个连续编号）
  • 简洁标题（3-5个单词，采用kebab-case格式）
  • 问题链接（例如 #1287）
  • 环境（生产/预发布/开发）+ 版本号
  • 实际表现与预期表现
  • 问题根源所在的文件/函数/行号

Phase 2: Generate Template

阶段2：生成模板

Complete the full BFB template:
markdown
undefined
完成完整的BFB模板：
markdown
undefined

BFB-XXX: [Title]

BFB-XXX: [Title]

Reference: [Issue link] Environment: [Env] 
vX.Y.Z
Date: YYYY-MM-DD
参考链接： [Issue link] 环境： [Env] 
vX.Y.Z
日期： YYYY-MM-DD

1. Bug

1. Bug详情

  • Observed: [wrong behavior]
  • Expected: [correct behavior]
  • 实际表现： [错误行为描述]
  • 预期表现： [正确行为描述]

2. Repro

2. 复现步骤

1. ...
2. ...
→ [error/output]
1. ...
2. ...
→ [错误信息/输出结果]

3. Cause

3. 根本原因

path/file.ext
— 
function()
@ line N [Why it happens, max 3 lines]
path/file.ext
— 
function()
@ line N [问题产生原因，最多3行]

4. Decision

4. 修复决策

OptionFixChoice
A[desc]✅/❌
B[desc]✅/❌
Rationale: [why]
选项修复方案选择
A[描述]✅/❌
B[描述]✅/❌
决策理由： [选择原因]

5. Fix

5. 修复检查清单

  • [change 1]
  • [test]
  • [verify repro]
  • [修改内容1]
  • [测试项]
  • [验证复现步骤]

6. Notes

6. 备注

[recurring patterns, links, warnings]
undefined
[重复出现的模式、相关链接、注意事项]
undefined

Phase 3: Ask Confirmation

阶段3：请求确认

Show the generated BFB and ask with AskUserQuestion:
  • "Create the BFB"
  • "Edit before creating"
  • "Cancel"
展示生成的BFB内容，并通过AskUserQuestion询问用户：
  • "创建该BFB"
  • "编辑后再创建"
  • "取消"

Phase 4: Write to Disk

阶段4：写入磁盘

Only after approval:
bash
mkdir -p docs/bfb
Write to 
docs/bfb/BFB-XXX-title.md
仅在获得用户批准后执行：
bash
mkdir -p docs/bfb
将内容写入
docs/bfb/BFB-XXX-title.md
文件

Examples

示例

Input: "create BFB for login email null crash"
Final output:
markdown
undefined
输入： "create BFB for login email null crash"
最终输出：
markdown
undefined

BFB-042: Login crash with null email

BFB-042: Login crash with null email

Reference: #1287 Environment: Prod 
v2.4.1
Date: 2026-05-02
参考链接： #1287 环境： Prod 
v2.4.1
日期： 2026-05-02

1. Bug

1. Bug详情

  • Observed: App crashes if email field is empty
  • Expected: Error message "Email required"
  • 实际表现： 若邮箱字段为空，应用程序崩溃
  • 预期表现： 显示错误提示"Email required"

2. Repro

2. 复现步骤

1. Open login screen
2. Tap "Login" without entering email
→ NullPointerException @ AuthManager.kt:34
1. 打开登录界面
2. 未输入邮箱即点击"Login"
→ NullPointerException @ AuthManager.kt:34

3. Cause

3. 根本原因

AuthManager.kt
— 
validateEmail()
@ line 34 Missing null check on email.trim()
AuthManager.kt
— 
validateEmail()
@ line 34 缺少对email.trim()的空值检查

4. Decision

4. 修复决策

OptionFixChoice
AAdd safe call 
?.
✅
BRefactor with Result type❌
Rationale: Option A is minimal, zero impact.
选项修复方案选择
A添加安全调用
?.
✅
B使用Result类型重构❌
决策理由： 选项A改动最小，无其他影响。

5. Fix

5. 修复检查清单

  • Add 
    email?.trim()?.isNotEmpty() == true
  • Test 
    validateEmail_null_returnsFalse()
  • Verify repro
  • 添加
    email?.trim()?.isNotEmpty() == true
  • 测试
    validateEmail_null_returnsFalse()
  • 验证复现步骤

6. Notes

6. 备注

  • Check other forms for missing null checks
undefined
  • 检查其他表单是否存在缺失的空值检查
undefined

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
  1. 连续编号：BFB-001、BFB-002，无间隔
  2. 简洁标题：3-5个单词，文件名采用kebab-case格式
  3. 根本原因：精确到文件、函数、行号
  4. 至少2种修复选项：包含优缺点及决策理由
  5. 可验证的检查清单：每一项都必须可测试

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
  • 需确认：写入前必须询问用户
  • 根本原因最多3行：保持简洁
  • 目录
    docs/bfb/
    ：若不存在则创建