fix-bug skill
✓ VerifiedFixes software bugs using a test-driven debugging methodology to identify root causes and apply minimal, verified fixes.
- GitHub stars
- 8
- Files
- 4
- Last commit
- Oct 28, 2026
- License
- MIT
- Allowed tools
- —
What does the fix-bug skill do?
fix-bug fixes software bugs using a test-driven debugging methodology to identify root causes and apply minimal, verified fixes.
Summary generated from the skill's SKILL.md.
About the fix-bug skill
Developers looking to resolve software defects through a disciplined, test-driven approach can use this skill to identify and fix bugs. It is designed for engineers who need to investigate failing tests, resolve error messages, or address specific issue IDs without accidentally refactoring unrelated code. The process begins by discovering project-specific commands for testing, linting, and type-checking to ensure the environment is correctly understood before any changes are made.
When an agent loads this skill, it follows a strict sequential workflow that prioritizes reproduction over intuition. It requires locating or creating a failing test to prove the bug exists before attempting a solution. For simple issues, the agent works inline, but for complex bugs spanning multiple files, it can organize work into a structured task chain covering discovery, analysis, planning, implementation, verification, and committing. The final output is a verified fix accompanied by evidence such as file paths, line numbers, and successful test suite results.
What an agent can do with it
- 1Resolve a specific issue IDProvide an issue ID to have the agent investigate the reported symptoms and implement a fix.
- 2Fix a failing testDirect the agent to investigate a specific test that is currently failing in the codebase.
- 3Debug complex multi-file errorsUse a structured task chain to manage bugs that require deep analysis across different components.
- 4Verify bug fixes with quality checksEnsure that a fix does not introduce regressions by running the full test suite and linting tools.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the fix-bug skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the fix-bug skill in Plugin
/plugin marketplace add mgiovani/cc-arsenal /plugin install cc-arsenal@cc-arsenal-marketplace
Install the fix-bug skill in Claude Code
~/.claude/skills/fix-bug/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/fix-bug ~/.claude/skills/fix-bugInstall the fix-bug skill in Claude Code (project)
.claude/skills/fix-bug/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/fix-bug .claude/skills/fix-bugInstall the fix-bug skill in Codex
~/.agents/skills/fix-bug/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/fix-bug ~/.agents/skills/fix-bugInstall the fix-bug skill in Gemini CLI
~/.gemini/skills/fix-bug/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/fix-bug ~/.gemini/skills/fix-bugInstall the fix-bug skill in Claude.ai
npx degit mgiovani/cc-arsenal/skills/fix-bug fix-bug && zip -r fix-bug.zip fix-bug # claude.ai → Customize → Skills → + → Create skill → Upload a skill → fix-bug.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work · What to fix for more points
- Source repository linked and reachablemgiovani/cc-arsenal/skills/fix-bug is public and reachablegithub.com/mgiovani/cc-arsenal/tree/HEAD/skills/fix-bug ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-28github.com/mgiovani/cc-arsenal/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/mgiovani/cc-arsenal/blob/HEAD/skills/fix-bug/SKIL ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/mgiovani/cc-arsenal/blob/HEAD/skills/fix-bug/SKIL ↗Pass
- SKILL.md follows the Agent Skills formatthe description does not say when to use the skillgithub.com/mgiovani/cc-arsenal/blob/HEAD/skills/fix-bug/SKIL ↗Finding
SKILL.md
View on GitHubBug Fix
Fix the bug the user describes. It might arrive as a plain description, sometimes as an issue ID, occasionally just the name of a failing test. Work test-driven: reproduce the failure first. Track down the root cause with evidence. Apply the smallest fix that resolves it, run the tests, commit.
Anti-hallucination guidelines
A fix that "should work" but was never run against a failing test is a guess, not a fix:
- Reproduce first: don't fix what you haven't seen fail.
- Test-driven: write or locate a failing test before implementing the fix; confirm it actually fails.
- Verify root cause: locate the bug with grep/read evidence (file path, line number), not intuition.
- Verify the fix: run the full test suite; all tests must pass before calling the bug fixed.
- No invented fixes: only implement solutions that address the demonstrated root cause.
- Reference real code: never make claims about code you haven't read.
Workflow Mode: Inline by Default
Most bugs are a single file, single root cause, fixable and verifiable in one sitting. For those, run Phases 0–5 below yourself, in order, inline: no task chain, no subagent fan-out. That's the default; don't create tasks unless the case below applies.
Use a task chain instead when the bug spans multiple files/components, the root
cause is unclear enough to need a dedicated analysis phase, or the fix will span
multiple sessions and needs progress tracking across them. In that case, before
Phase 0, create six tasks (Discovery, Reproduce & Analyze, Plan, Implement, Verify,
Commit) with a strict sequential chain, each addBlockedBy the one before it:
TaskCreate: { subject: "Phase 0: Discover project workflow", activeForm: "Discovering project workflow" }
TaskCreate: { subject: "Phase 1: Reproduce and analyze bug", activeForm: "Analyzing bug" }
TaskCreate: { subject: "Phase 2: Plan fix", activeForm: "Planning fix" }
TaskCreate: { subject: "Phase 3: Implement fix", activeForm: "Implementing fix" }
TaskCreate: { subject: "Phase 4: Verify quality", activeForm: "Verifying fix quality" }
TaskCreate: { subject: "Phase 5: Final commit", activeForm: "Creating final commit" }
TaskUpdate: { taskId: "2", addBlockedBy: ["1"] }
TaskUpdate: { taskId: "3", addBlockedBy: ["2"] }
TaskUpdate: { taskId: "4", addBlockedBy: ["3"] }
TaskUpdate: { taskId: "5", addBlockedBy: ["4"] }
TaskUpdate: { taskId: "6", addBlockedBy: ["5"] }
TaskUpdate: { taskId: "1", status: "in_progress" }
Task lifecycle rule (applies to every phase below when a chain exists, not
repeated per phase): mark that phase's task in_progress the moment you start it,
and status: "completed" immediately before moving to the next phase, then run
TaskList to confirm the next task unblocked.
Portability: no Task/TaskCreate tools in this environment? Always use the
inline path above: the phases are the methodology, the task tooling is just how
Claude Code tracks and parallelizes them in the multi-file case.
Phase 0: Project Discovery
Discover the project's test, lint, and type-check commands before touching anything: guessing wastes a cycle when the wrong command silently no-ops.
If the codebase is large or unfamiliar, offload this to an Explore subagent:
Task tool, Explore agent, model haiku:
"Discover the development workflow for this project:
1. Read CLAUDE.md/AGENTS.md if present — extract debugging/testing conventions.
2. Check task runners: Makefile, justfile, package.json scripts, pyproject.toml.
3. Identify the test command, and how to run a single test/file.
4. Identify the lint and type-check commands.
5. Identify the dev server command if this is a web app.
6. Note pre-commit hooks or other quality gates.
Return a structured summary of all available commands."
Otherwise just check these yourself with Read/Grep. Store what you find, it's used in every later phase.
Phase 1: Bug Analysis & Reproduction
Goal: understand the bug, locate it in code, reproduce it reliably.
-
Understand symptoms. If given an issue ID, read it (
gh issue view,jira issue view, etc.). Identify expected vs. actual behavior and any error messages.If the report is too vague to reproduce (no expected/actual behavior, no repro steps, no error message, e.g. "something is broken sometimes"): stop here. Call
AskUserQuestion; if that tool isn't available, end your turn with the specific questions in your final message instead: reproduction steps, expected vs. actual behavior, environment/error messages, and go no further. Do not infer a root cause from a code read alone or invent your own repro scaffolding to stand in for a real report. Running in an automated, sandboxed, or non-interactive context is not a reason to guess instead of asking, it's a reason to put the questions in the final message rather than wait for a reply. -
Locate or create a failing test. Grep for existing coverage. If none exists, write a minimal test that reproduces the bug, in the location and style the existing test suite uses.
-
Reproduce it: a hard gate, not prose. Run the reproduction test against the current (unfixed) code with the discovered test command, and show the actual failing output before touching the fix. If the report names a specific symptom (e.g. "double-charges on retry"), confirm the assertion for that symptom is what fails, a suite with some unrelated test failing while the reported-symptom assertion already passes is not a reproduction. If the test passes pre-fix, the reproduction is wrong: stop, don't proceed to Phase 2, and rewrite the test until it actually captures the reported bug. A test that never failed proves nothing about the fix you're about to write.
-
Find the root cause. For a localized bug, just grep/read the relevant file yourself. Reserve parallel subagents for bugs spanning multiple files or with unclear scope:
Agent 1 (Explore, haiku) — Bug Location:
"Find the exact bug location (file:line), read the buggy code and its
surrounding context, explain why it produces the wrong behavior, and
provide evidence (stack trace, variable values, control flow)."
Agent 2 (Explore, haiku) — Impact Analysis:
"Search the codebase for other code affected by the same issue, similar
patterns with the same bug, related tests that might also fail, and
callers of the buggy code."
Agent 3 (general-purpose, haiku, only if an external library is implicated):
"Search Context7/web for documented solutions or known issues matching
this bug in [LIBRARY_NAME]."
- Confirm the theory. Re-read the buggy code and check it explains every symptom, including edge cases. If still uncertain, use
AskUserQuestionbefore writing a fix on an unconfirmed theory.
Phase 2: Fix Planning
Goal: a minimal, focused fix that addresses the root cause without side effects.
Design a fix that:
- Addresses only the root cause, no drive-by refactoring.
- Follows the project's existing patterns.
- Has minimal scope (fewest lines changed).
- Introduces no breaking changes.
- Handles the edge cases found in Phase 1.
- Never trims validation, error/data-loss handling, or security to keep the diff small: scope is what shrinks, not the safety floor. If a full fix isn't feasible right now, ship the safe partial fix and leave
// LEAN-DEBT: <limitation>. Upgrade when <trigger>.rather than silently shipping the gap.
Get approval for non-trivial fixes: if the fix touches >3 files, modifies a
public API, has performance implications, or is otherwise breaking, use
AskUserQuestion to present the plan before implementing.
Phase 3: Implementation
- Apply the fix with Edit: minimal, focused changes.
- Run the specific failing test and confirm it now passes. If it doesn't, that means the root-cause theory was wrong or incomplete, go back to Phase 1, not to a bigger patch on top of the current one.
- Run the full test suite to check for side effects.
- If new failures appear, adjust the fix (or correct a wrongly-specified test) and repeat until everything passes.
Phase 4: Quality Verification
Run all quality checks using the commands discovered in Phase 0, then confirm every line of this checklist: it's the single authoritative copy, used at completion time:
- Previously failing test now passes
- Full test suite passes (no regressions)
- No new linting errors
- No new type errors (if the language is typed)
- Fix addresses the root cause only, no unrelated refactoring
- Change is minimal and follows existing code patterns
- Any partial fix carries a
LEAN-DEBTmarker (see Phase 2)
If any item fails, fix it before proceeding, don't commit broken code, and don't mark the phase complete until every box is checked.
Phase 5: Final Commit
If the git-commit skill is available, use it. Otherwise commit manually:
git add [files modified]
git commit -m "fix: [concise description of what was fixed]
- [Root cause]
- [Solution approach]
- [Issue/ticket reference if applicable]
Closes #[ISSUE_NUMBER]"
Phase 6: Verification Summary
Report to the user: bug description, root cause (file:line), the fix, files
modified, test results (previously-failing test, full suite, lint, type-check,
each pulled from the command output you actually ran, never invented), commit
info, and any LEAN-DEBT markers left behind.
Additional Resources
- references/examples.md: worked examples, argument
parsing for optional flags (
--branch,--interactive,--test-only), browser testing integration, and error-handling patterns (test-still-fails, ambiguous report, can't reproduce, multiple root causes). Load when you need one of those specifics; the phases above are sufficient for a standard fix.
Important Notes
- Test-driven: see the test fail before writing the fix.
- Minimal changes: fix the bug, don't refactor unrelated code.
- Evidence-based: cite real file paths and line numbers, never a guess.
- All tests must pass before this is done; never commit with failing tests.
- Ask when unsure: clarifying is cheaper than guessing wrong and redoing it.
- Browser testing is optional, only when the bug is UI-facing and the tooling is available (see references/examples.md).
Files in this skill
4fix-bug skill questions
How do I install the fix-bug skill in Claude Code?
Run npx degit mgiovani/cc-arsenal/skills/fix-bug ~/.claude/skills/fix-bug. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the fix-bug skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is the methodology used for fixing bugs?
The skill uses a test-driven debugging approach: reproduce the failure with a test, locate the root cause with evidence, apply a minimal fix, and verify with the full test suite.
Can this skill be used to add new features?
No, this skill is strictly for resolving existing bugs and should not be used for building new functionality or restructuring working code.
What should the agent do if a bug report is too vague?
If the report lacks reproduction steps or expected behavior, the agent must stop and ask the user for clarification instead of guessing.