# Bug Fix

> Bug Fix Lifecycle

- Skill: `jorelcb/bug-fix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jorelcb/bug-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jorelcb/bug-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jorelcb (https://skillmd.com/u/jorelcb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jorelcb/bug-fix

---

# Bug Fix Lifecycle

Drive a bug from report to verified fix through a disciplined sequence: reproduce, capture a failing test, diagnose the root cause, fix narrowly, and confirm no regressions. This prevents symptom-only patches and bugs that quietly return.

## When to use

- A bug report or issue needs a structured, end-to-end fix
- A defect was reproduced and you are about to change code
- You want a regression guard in place before shipping the fix
- Reviewing whether a "quick fix" actually addresses the root cause

As a Claude Code skill, this may declare `allowed-tools` so trusted, repeatable steps (running the test suite, linting) execute without re-prompting. Keep destructive or remote steps (merge, deploy) interactive.

## Process

### 1. Create the fix branch

Branch from the latest `main`/`develop`. Follow the project's naming convention (e.g. `fix/<issue-number>-short-description`) and reference the bug report so the branch is traceable back to the issue.

### 2. Reproduce the bug

Confirm the defect before touching code:

- Read the report — steps to reproduce, expected vs. actual behavior
- Recreate the environment: the specific data, configuration, and state
- Execute the reproduction steps
- Capture the broken behavior: error messages, logs, screenshots

If you cannot reproduce it, stop and gather more information — do not guess at a fix.

### 3. Write a failing test

When the bug is testable, encode it as a test first:

- The test must FAIL against the current code, proving the bug exists
- It should assert the expected correct behavior
- This test becomes the permanent regression guard

### 4. Diagnose the root cause

Investigate systematically rather than patching the first suspicious line:

- Trace the execution path from the reproduction steps
- Find WHERE behavior diverges from expectation
- Find WHY — the underlying cause, not the surface symptom
- Check whether the same flawed pattern exists elsewhere
- Record the findings for the commit message or PR description

### 5. Implement the fix

Fix the cause with the smallest change that works:

- Make the minimum change needed to correct the behavior
- Confirm the failing test from step 3 now passes
- Do not refactor unrelated code in the same commit
- If a broader refactor is warranted, file it as a follow-up

### 6. Verify no regressions

Run the full test suite, not just the new test:

- All existing tests still pass
- The new regression test passes
- Linting and static analysis are clean

### 7. Cover the edge cases

When the bug touches boundary conditions, probe the neighbors:

- Empty or null inputs
- Maximum and minimum values
- Concurrent-access scenarios
- Add tests for any uncovered edge case you surface

### 8. Open a focused pull request

- Title: `fix: <what was broken>`
- Description: root-cause analysis, what the fix does, how to verify
- Link the original bug report and include before/after behavior

### 9. Merge and confirm

After approval, merge with the project's preferred strategy, verify the fix in the target environment, close the issue with a reference to the fix, and delete the branch.

## Anti-patterns

- Patching symptoms without understanding the root cause
- Bundling the fix with unrelated changes in one PR
- Shipping without a regression test — the bug will return
- Fixing one bug and introducing another by skipping the full suite
- Leaving the root cause undocumented, making future debugging harder

## Verification

Before merging:

- [ ] Bug was reproduced and the broken behavior captured
- [ ] A regression test failed before the fix and passes after
- [ ] Root cause (not just the symptom) is identified and documented
- [ ] Full test suite, linting, and static analysis are green
- [ ] Relevant edge cases have test coverage
- [ ] PR is scoped to the fix only and linked to the issue