# Bugfix

> Use this skill ALWAYS whenever there is a reproducible bug, failing test, runtime error, regression, or any defect report. Trigger this skill EVEN if the user just says "X is broken" or "fix Y" without describing the process. Use it for ANY defect work — never just patch and close.

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

---


# Bugfix workflow

When a bug, failing test, error, regression is reported — follow this exact sequence.

## 1. Reproduce
- Establish the smallest reliable repro path (test, command, sequence of clicks, payload).
- If you cannot reproduce — STOP and ask owner for repro steps. Do not "fix" what you cannot reproduce.

## 2. Read code BEFORE hypothesis (R1)
- Read the file(s) implicated in the failure. Do not skim — actually Read with the tool.
- If the issue touches an external SDK/API → trigger official-docs-first skill (R2).
- Cite specific file:line in your reasoning.

## 3. Identify root cause
- Walk the failing path from symptom backwards.
- Check git log of the failing file: `git log -p --follow <file>` — recent changes?
- Use Grep/Serena `find_references` for related call sites.
- Hypothesis is OK only AFTER reading. Mark explicitly: "Hypothesis (unverified): X. Verifying via Y."

## 4. Fix the CAUSE not the symptom (R10 — No band-aids)
- Architecturally correct fix, not a try/catch wrapper.
- If correct fix is larger than the bug warrants — write ADR + propose follow-up TZ instead of patching.

## 5. Validate (R12)
- Add or update test that would have caught this bug.
- Run `pytest tests/test_X.py` or equivalent. Must PASS.
- Run mypy/ruff on touched files. Must be CLEAN.

## 6. Update memory
- If issue partially resolved or revealed deeper problem → record in `docs/agent/06_known_issues.md`.
- If incident-worthy → start `docs/agent/08_postmortems.md` entry.
- Append to `docs/agent/04_changelog.md`.

## 7. ADR if architectural decision was made
- "Switched from X to Y to fix this" = architectural decision = needs ADR.
- "Patched edge case in Y" = not architectural, no ADR needed.

## Anti-patterns (do NOT do these)
- ✗ Catch exception silently
- ✗ Add `try/except: pass`
- ✗ Add boolean flag to skip the broken path
- ✗ Wrap bug with comment "// FIXME: weird issue, working around"
- ✗ Mark task done without test that verifies the fix