MCPInstall

bug-fix-brief

by giuseppe-trisciuoglioCode Quality & Workflow

Generates a structured Bug Fix Brief (BFB) to document issue corrections. Includes root cause analysis, repro steps, fix options, and fix checklist. Use when user asks to create a BFB, document a bug fix, or generate a bug correction document.

Installs
3K
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill bug-fix-brief
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads bug-fix-brief automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

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

FAQ

What does the bug-fix-brief skill do?

Generates a structured Bug Fix Brief (BFB) to document issue corrections. Includes root cause analysis, repro steps, fix options, and fix checklist. Use when user asks to create a BFB, document a bug fix, or generate a bug correction document.

How do I install bug-fix-brief?

Run npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill bug-fix-brief in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/bug-fix-brief/ (personal) or .claude/skills/bug-fix-brief/ (project).

Which AI agents can use bug-fix-brief?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is bug-fix-brief safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains bug-fix-brief?

It is published by giuseppe-trisciuoglio in giuseppe-trisciuoglio/developer-kit. It has 3,005 recorded installs.

More from giuseppe-trisciuoglio/developer-kit

View all →

shadcn-ui

giuseppe-trisciuoglio/developer-kit

Provides complete shadcn/ui component library patterns including installation, configuration, and implementation of accessible React components. Use when setting up shadcn/ui, installing components, building forms with React Hook Form and Zod, customizing themes with Tailwind CSS, or implementing UI patterns like buttons, dialogs, dropdowns, tables, and complex form layouts.

Frontend & Design22.4K installs

tailwind-css-patterns

giuseppe-trisciuoglio/developer-kit

Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.

Frontend & Design17.7K installs

drizzle-orm-patterns

giuseppe-trisciuoglio/developer-kit

Provides comprehensive Drizzle ORM patterns for schema definition, CRUD operations, relations, queries, transactions, and migrations. Proactively use for any Drizzle ORM development including defining database schemas, writing type-safe queries, implementing relations, managing transactions, and setting up migrations with Drizzle Kit. Supports PostgreSQL, MySQL, SQLite, MSSQL, and CockroachDB.

Data & Databases5.4K installs

unit-test-bean-validation

giuseppe-trisciuoglio/developer-kit

Provides patterns for unit testing Jakarta Bean Validation (JSR-380), including @Valid, @NotNull, @Min, @Max, @Email constraints with Hibernate Validator. Generates custom validator tests, constraint violation assertions, validation groups, and parameterized validation tests. Validates data integrity logic without Spring context. Use when writing validation tests, bean validation tests, or testing custom constraint validators.

Testing & QA4.9K installs

nextjs-performance

giuseppe-trisciuoglio/developer-kit

Expert Next.js performance optimization skill covering Core Web Vitals, image/font optimization, caching strategies, streaming, bundle optimization, and Server Components best practices. Use when optimizing Next.js applications for Core Web Vitals (LCP, INP, CLS), implementing next/image and next/font, configuring caching with unstablecache and revalidateTag, converting Client Components to Server Components, implementing Suspense streaming, or analyzing and reducing bundle size. Supports Next.js 16 + React 19 patterns.

Frontend & Design4.9K installs

react-patterns

giuseppe-trisciuoglio/developer-kit

Provides comprehensive React 19 patterns for Server Components, Server Actions, useOptimistic, useActionState, useTransition, concurrent features, Suspense boundaries, and TypeScript integration. Generates executable code patterns, validates security for public endpoints, and optimizes performance with React Compiler or manual memoization. Proactively use when building React 19 applications with Next.js App Router, implementing optimistic UI, or optimizing concurrent rendering.

Frontend & Design4.8K installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs