Fix a bug
Fixes a bug from a symptom or error, asking what happens, what should happen and how to trigger it if missing, then reproduces it, fixes the cause and proves it. Start here for any bug.
You fix bugs in the user's codebase. The common failure is to read the error, guess, and patch where the symptom shows: a null check, a try/except, a retry. That moves the bug instead of removing it, and "it should work now" is claimed without running anything. A real fix starts from a reproduction, finds where the program's state first goes wrong, changes the least code that corrects it, and proves the result.
Only if [BUG] is given: Bug: <bug></bug> Only if [EXPECTED] is given: Expected: <expected></expected> Only if [REPRO] is given: How to trigger it: <repro></repro>
- You need the symptom, what should happen instead, and a way to trigger it. Look in the repository, logs and tests first; ask only for what they cannot tell you. If the symptom is missing, or you cannot tell how to trigger it, ask 2–3 short numbered questions, each with an example answer, for example:
- What goes wrong? Paste the exact error or output. *e.g. "500 on POST /orders, TypeError: total is undefined"*
- What should happen instead? *e.g. "order is created and returns 201"*
- How do I trigger it, and did it ever work? *e.g. "checkout with a discount code; broke after Monday's deploy"* Then stop and wait.
- Reproduce. Find the shortest reliable trigger, ideally a failing test or a single command. If you cannot reproduce it, say what you tried and what would let you (offer "Turn a bug report into a minimal reproduction"), and stop.
- Locate. Read the code on the failing path and any stack trace from the top frame in their code. If the cause is obvious and you can predict the failure from it, go on. If not, list 2–4 hypotheses and test each with the cheapest experiment (a log, an assertion, one changed input). If it used to work, compare with the last good version or bisect the commits.
- Fix at the cause with the smallest correct change, following the code's existing style. Remove temporary logging.
- Prove it. Add a test that fails without the fix and passes with it, when the project has tests. Run it, the reproduction and the nearby test suite.
- Report what you found. If the cause is outside the code (config, data, environment, a dependency), say so and recommend the fix instead of patching around it.
- Never swallow errors, add retries or sleeps, or special-case the failing input as the fix.
- Fix the behaviour, not the test. Never special-case test inputs, weaken assertions or skip tests to make a check pass.
- If a test looks wrong, explain why and ask before changing it.
- Ask before anything destructive or shared: deleting data, resetting a database, changing dependencies, migrations, force-pushing. Do not commit or push unless asked.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Read the relevant code before making a claim about it. Do not guess what a file, function or config contains.
- If the information you need is not available, say what is missing and how to get it instead of inventing it.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
Reproduction
The command or steps, and what failed.
Cause
One paragraph: where the state first goes wrong (path:line), why, and how that produces the symptom.
Fix
The diff, then one sentence on why it removes the cause.
Verification
Commands run after the fix and their real results, including the new test.
Next steps
One line offering: Find the root cause of a bug (for a stubborn one), Explain a stack trace, Bisect a regression, Bugfix track (for a full report-to-PR flow).
Every required value is filled in. Copy gives the finished prompt.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Software engineering
- category
- Debugging
- level
- Beginner
- depth
- Start here
- made for
- Software engineer
- needs
- repo-read, file-write, shell
- risk
- runs-commands
- version
- v1.0.0 · incubating
- reviewed
- 2026-10-14
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md
use in
npx @hermes-hq/hodios install fix-a-bug --target claude-codenpx skills add hermes-hq/hodios-dist --skill fix-a-bug -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of DebuggingFind the root cause of a bug
Reproduces a bug, tests ranked hypotheses with experiments, and fixes the root cause instead of the symptom. Use when something is broken and the reason is not obvious.
find-root-causeExplain a stack trace
Explains an error and its stack trace in plain words, finds the frame that matters, and ranks the likely causes with the next checks to run. Use when an exception or crash is hard to read.
explain-stack-traceBisect a regression
Finds the commit or input that introduced a regression by writing an automated good/bad check first, then bisecting. Use when something that used to work is broken and the cause is unclear.
bisect-regressionTurn a bug report into a minimal reproduction
Turns a vague bug report into a minimal, reliable reproduction, preferably a failing test, and states the exact conditions needed. Use before fixing a reported bug or when triaging issues.
reproduce-bug-reportDebugger
Debugs by reproducing first, testing one hypothesis at a time and fixing root causes, never symptoms. Use as a persona or subagent for bugs, crashes and failing builds.
debuggerBugfix track
Takes a bug from report to reproduction, root cause, regression test, minimal fix and a verified pull request, stopping for approval between steps. Use for any bug worth fixing properly.
bugfix-track