How do I install the Bugfix skill?

Run npx skillmds@latest add engsimsoft/bugfix in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Bugfix safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Bugfix?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Bugfix free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Bugfix?

engsimsoft (@engsimsoft) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Bugfix by engsimsoft — Agent Skill

Name: Bugfix
Author: engsimsoft

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.

engsimsoft 63f4d0c 2.3 KB Updated Sep 17, 2026

File contents

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

---name: bugfixdescription: 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.---# Bugfix workflowWhen 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

Frequently asked questions