Bug Fix Brief

This generates a standardized Bug Fix Brief document in your docs/bfb/ folder whenever you need to properly document a bug correction. It walks you through the essentials: repro steps, root cause down to the file and line number, at least two fix options with a decision rationale, and a verification checklist. The structure is opinionated but lightweight, which is the point. It keeps sequential numbering, forces you to compare alternatives before committing to a fix, and makes sure every bug gets the same treatment whether it's a null pointer or a race condition. Good for teams that want fix documentation without the ceremony of a full postmortem process.

skills.sh installs: 3.1K
GitHub stars: 369
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add giuseppe-trisciuoglio/developer-kit --skill bug-fix-brief --agent claude-code

Installs into .claude/skills of the current project.

Files

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