How do I install the Fix Bug skill?

Run npx skillmds@latest add kunalsuri/fix-bug 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 Fix Bug 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 Fix Bug?

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 Fix Bug free to use?

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

Who published Fix Bug?

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

Fix Bug by kunalsuri — Agent Skill

Name: Fix Bug
Author: kunalsuri

Fix Bug

Fix a bug in this repository the safe way — reproduce first, failing regression test, root cause via the maps, surgical fix, review, ledger entry. Use whenever the user reports broken, wrong, or crashing behavior.

kunalsuri 66826dd 2 files · 2.8 KB Updated Sep 17, 2026

File contents

Fix a bug

The contract: no fix before a reproduction, no reproduction without a failing test, no "fixed" without the regression test green, no closing without the ledger row and the gotcha recorded.

1. Reproduce

Draft ai/lab/specs/BUGFIX_<name>.md from BUGFIX_TEMPLATE.md: symptom (observed vs expected), exact reproduction steps. Get the user's OK.

2. Prove

Turn the reproduction into a regression test and watch it fail. A bug you cannot make a test fail for is a bug you do not understand yet. The test is permanent — it outlives the fix.

3. Locate

ai/guide/MODULE_MAP.md → which modules; note Stability of every suspect.
ai/guide/FEATURE_MAP.md gotchas + ai/lab/WORKLOG.md → was this area recently touched, or is the "bug" deliberate behavior a past ADR explains?
Keep broad reading read-only and cheap (directory listings, manifests, search hits over whole-file reads) to protect context.

4. Gate

Root cause in a file with Stability frozen or ? ⇒ stop and ask the human. Record their approval in the bugfix doc before proceeding.

5. Diagnose, then fix

Name the root cause in the bugfix doc — the defect, not the symptom. Then make the smallest diff that turns the regression test green. Match the license headers of neighboring files. No drive-by refactors, no layout changes, no dependency additions while "in there".

6. Verify

Run the regression test (now green), then the suites covering the touched area. Report command run · exit status · failures verbatim. Red or unrun ⇒ not fixed.

7. Review & record

Request /review-change on the diff (fresh context — not this session). Append a bugfix row to ai/lab/WORKLOG.md linking the bugfix doc and review; add the gotcha line to FEATURE_MAP so the next agent knows the trap. All [inferred] — tell the user which tags await their [verified] flip.

---name: fix-bugdescription: Fix a bug in this repository the safe way — reproduce first, failing regression test, root cause via the maps, surgical fix, review, ledger entry. Use whenever the user reports broken, wrong, or crashing behavior.---# Fix a bugThe contract: **no fix before a reproduction, no reproduction without a failingtest, no "fixed" without the regression test green, no closing without theledger row and the gotcha recorded.**## 1. ReproduceDraft `ai/lab/specs/BUGFIX_<name>.md` from BUGFIX_TEMPLATE.md: symptom(observed vs expected), exact reproduction steps. Get the user's OK.## 2. ProveTurn the reproduction into a regression test and watch it **fail**. A bug youcannot make a test fail for is a bug you do not understand yet. The test ispermanent — it outlives the fix.## 3. Locate- `ai/guide/MODULE_MAP.md` → which modules; note Stability of every suspect.- `ai/guide/FEATURE_MAP.md` gotchas + `ai/lab/WORKLOG.md` → was this area recently touched, or is the "bug" deliberate behavior a past ADR explains?- Keep broad reading read-only and cheap (directory listings, manifests, search hits over whole-file reads) to protect context.## 4. GateRoot cause in a file with Stability `frozen` or `?` ⇒ stop and ask the human.Record their approval in the bugfix doc before proceeding.## 5. Diagnose, then fixName the root cause in the bugfix doc — the defect, not the symptom. Then makethe smallest diff that turns the regression test green. Match the licenseheaders of neighboring files. No drive-by refactors, no layout changes, nodependency additions while "in there".## 6. VerifyRun the regression test (now green), then the suites covering the touched area.Report command run · exit status · failures verbatim. Red or unrun ⇒ not fixed.## 7. Review & recordRequest `/review-change` on the diff (fresh context — not this session).Append a `bugfix` row to `ai/lab/WORKLOG.md` linking the bugfix doc and review;add the gotcha line to FEATURE_MAP so the next agent knows the trap. All`[inferred]` — tell the user which tags await their `[verified]` flip.

Frequently asked questions