# Fix Bug

> Structured workflow to reproduce, diagnose, plan, fix, verify, and record a bug fix, requiring a deterministic reproduction before diagnosis and minimal changes only.

- Skill: `samyakjhaveri/fix-bug` (Agent Skill)
- Install (CLI): `npx skillmds add samyakjhaveri/fix-bug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samyakjhaveri/fix-bug/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity, Coding & Dev Tools, Debugging, Testing & QA
- Tags: Bug Fix, Debugging, Reproduction, Test, Verification
- Author: SamyakJhaveri (https://skillmd.com/u/samyakjhaveri)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/samyakjhaveri/fix-bug

---


# Bug Fix Workflow

Structured workflow for diagnosing and fixing a bug.

## Arguments
- `$ARGUMENTS` — bug description or spec name

## Workflow

### Phase 1: Reproduce
- Identify the failing command or test
- Run it and capture the exact error output
- Check `.claude/rules/known-issues.md` — is this a known bug?
- **Build a feedback loop**: before diagnosing, establish a fast, deterministic, repeatable pass/fail signal (failing test, curl script, CLI invocation with fixture input, or headless browser script). If you cannot build a loop after trying multiple approaches, stop and say so — do not proceed to diagnose without one.

### Phase 2: Diagnose
Use subagents to explore the relevant code paths in parallel:
- Trace the error to its root cause
- Identify all files involved in the call chain
- Check if the bug affects other specs/kernels

### Phase 3: Plan
Enter plan mode. Draft the fix:
- Root cause explanation
- Proposed change (minimal and targeted)
- Files to modify
- Risk of regression

Present the plan and **wait for user approval**.

### Phase 4: Fix
- Implement the minimal fix
- Do NOT refactor surrounding code
- Add a test if one doesn't exist for this case

### Phase 5: Verify
- Reproduce the original error — confirm it's fixed
- Run project test suite (e.g., `python3 -m pytest tests/ -v`)
- Check for regressions in related areas

### Phase 6: Record
- Update `.claude/rules/known-issues.md` if this was a known bug (mark as fixed)
- Update CLAUDE.md if new gotchas were discovered