# Bug Fixing

> The user's workflow for fixing bugs and performance regressions. Use when the user reports something broken, throwing, failing, flaky, or slow, or says "fix this bug"/"debug"/"diagnose". Runs a disciplined diagnosis before any fix.

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

---


# Bug-fixing workflow

Diagnose before you change anything. Guessing at fixes wastes tokens and creates new bugs.

## Steps

1. **Recall context.** If a project memory exists (`project-memory` skill / `.memory/`), read it —
   the bug may be a known gotcha or tie to a past decision.
2. **Diagnose properly.** Invoke the **`diagnosing-bugs`** skill (mattpocock-skills) and follow its
   loop: reproduce, form a hypothesis, gather evidence, confirm root cause — before writing a fix.
   - Not installed? `npx skills@latest add mattpocock/skills --skill=diagnosing-bugs`
3. **Fix at the root**, not the symptom. Smallest change that addresses the confirmed cause.
4. **Prove it.** Add or run a test that fails before and passes after. Report the evidence honestly —
   if you couldn't reproduce or verify, say so.
5. **Close the loop.** Update docs if behavior changed (`keep-documentation`), and record a
   non-obvious root cause in project memory so it isn't rediscovered later.

## Redaction

Diagnosis surfaces logs and commands — redact secrets to `<REDACTED>` before showing them.