bugfix-workflow
/bugfix-workflow
End-to-end bugfix workflow. Test first, plan, fix, verify. Use when the user says "fix bug", "bugfix", "investigate issue", "fix #NNN", or any bug-related work. Covers reproduction, test creation, RCA, fix implementation, verification, and ticket documentation.
- Author
- arozumenko ↗
- Repository
- wikis ↗
- Licence
- MIT
- Last repository change
- 07.07.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 07.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
End-to-end bugfix workflow. Test first, plan, fix, verify. Use when the user says "fix bug", "bugfix", "investigate issue", "fix #NNN", or any bug-related work. Covers reproduction, test creation, RCA, fix implementation, verification, and ticket documentation.
Triggers from the description
Original author description
End-to-end bugfix workflow. Test first, plan, fix, verify. Use when the user says "fix bug", "bugfix", "investigate issue", "fix #NNN", or any bug-related work. Covers reproduction, test creation, RCA, fix implementation, verification, and ticket documentation.
How it works
- Bugfix Workflow: Reproduce → Test → Fix → Verify
- Workflow
- Step 1: Read & Understand the Bug
- Step 2: Reproduce
- Step 3: Write a Failing Test
- Step 4: Root Cause Analysis
- Step 5: Implement the Fix
- Step 6: Verify
- Step 7: Document on Ticket
- Anti-Patterns
SKILL.md preview
---
name: bugfix-workflow
description: End-to-end bugfix workflow. Test first, plan, fix, verify. Use when the user says "fix bug", "bugfix", "investigate issue", "fix #NNN", or any bug-related work. Covers reproduction, test creation, RCA, fix implementation, verification, and ticket documentation.
license: Apache-2.0
metadata:
author: octobots
version: "0.1.0"
---
## Bugfix Workflow: Reproduce → Test → Fix → Verify
Core philosophy: **reproduce before you fix, verify after you fix, link everything to the ticket.**
## Workflow
```
Step 1: Read & Understand the Bug
↓
Step 2: Reproduce
↓
Step 3: Write a Failing Test
↓
Step 4: Root Cause Analysis
↓
Step 5: Implement the Fix
↓
Step 6: Verify (tests pass)
↓
Step 7: Document on Ticket
```
## Step 1: Read & Understand the Bug
**Goal:** Fully understand the issue before touching code.
```bash
gh issue view <NUMBER>
```
Read all comments. Identify:
- Expected behavior vs actual behavior
- Which files/modules are involved
- Any error messages, stack traces, screenshots
- Related or duplicate issues
**Comment on ticket:**
```bash
gh issue comment <NUMBER> --body "🔧 **Investigating**: Reading the report and reproducing."
```
## Step 2: Reproduce
**Goal:** Confirm the bug exists and understand exact conditions.
### For UI Bugs (Playwright MCP)
```
browser_navigate → browser_snapshot → follow reported steps →
browser_console_messages → browser_network_requests → browser_take_screenshot
```
### For API Bugs
```bash
curl -s -X POST http://localhost:PORT/api/endpoint \
-H "Content-Type: application/json" \
-d '{"test": "data"}' | jq .
```
### For Logic Bugs
Write a minimal script that triggers the issue:
```python
# reproduce_issue_NNN.py
from module import function
result = function(edge_case_input)
print(f"Expected: X, Got: {result}")
```
**If you cannot reproduce:** Comment on ticket with what you tried and ask for more details. Do NOT proceed to fix.
**Comment on ticket:**
```bash
gh issue comment <NUMBER> --body "$(cat <<'EOF'
✅ **Reproduced**
**Steps:** [exact steps]
**Expected:** [what should happen]
**Actual:** [what happens]
**Frequency:** Always / Intermittent
EOF
)"
```
## Step 3: Write a Failing Test
**Goal:** Capture the bug as a test BEFORE fixing it. The test must fail now and pass after the fix.
```python
def test_issue_NNN_description():
"""Regression test for #NNN: [bug title]."""
# Arrange — set up the conditions that trigger the bug
input_data = edge_case_input
# Act — trigger the bug
result = function(input_data)
# Assert — what SHOULD happen (this fails now)
assert result == expected_value
```
Run it to confirm it fails:
```bash
pytest tests/test_module.py::test_issue_NNN -x -v
# Should FAIL — that's the point
```
## Step 4: Root Cause Analysis
**Goal:** Find the exact code that causes the bug.
1. **Locate** the relevant code:
```bash
# Search for the function/class involved
grep -rn "function_name" src/ --include="*.py"
```
2. **Trace** the execution path from entry point to failure
3. **Identify** the root cause:
- Logic error (wrong condition, off-by-one, missing case)
- Data error (unexpected input, type mismatch, null handling)
- Concurrency (race condition, missing lock)
- Configuration (wrong default, missing env var)
- Integration (API contract changed, dependency updated)
4. **Assess impact:** What else uses this code? Could the fix break other things?
**Comment on ticket:**
```bash
gh issue comment <NUMBER> --body "$(cat <<'EOF'
🔍 **Root Cause**
**Location:** `src/module.py:42`
**Cause:** [description of what's wrong]
**Impact:** [what else is affected]
**Fix approach:** [brief plan]
EOF
)"
```
## Step 5: Implement the Fix
**Goal:** Minimal, focused fix. Don't refactor, don't clean up neighbors.
1. Fix the root cause — only the root cause
2. Verify syntax: `python -m py_compile file.py` (or equivalent)
3. Don't change unrelated code
## Step 6: Verify
**Goal:** The failing test now passes. Nothing else broke.
```bash
# 1. The regression test passes
pytest tests/test_module.py::test_issue_NNN -x -v
# 2. Full test suite still passes
pytest tests/ -x -q
# 3. Lint/type check
ruff check . && mypy src/ # or your project's equivalent
```
If anything fails, fix it before proceeding.
## Step 7: Document on Ticket
**Goal:** Complete audit trail — what was wrong, what was fixed, proof it works.
```bash
gh issue comment <NUMBER> --body "$(cat <<'EOF'
✅ **Fixed**
**Root Cause:** [one sentence]
**Fix:** [what changed, which files]
**Regression Test:** `tests/test_module.py::test_issue_NNN`
**PR:** #XX
All tests passing.
EOF
)"
```
Commit and create PR:
```bash
git add -A
git commit -m "Fix: [description] (#NNN)"
git push -u origin HEAD
gh pr create --title "Fix: [description] (#NNN)" --body "Closes #NNN"
```
## Anti-Patterns
- Don't fix without reproducing first
- Don't skip the failing test — no test = no proof
- Don't refactor while fixing — separate concerns
- Don't close the ticket without documenting the fix
- Don't fix multiple bugs in one PR
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · arozumenko/wikis | 100 | MIT |
| arozumenko/sdlc-skills | 100 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version b1e9ada17f33 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90pm-bugfix
Create or manage a bug-fix workflow packet. Use when the user reports a bug, says "fix this bug", or needs a structured workflow for diagnosing and resolving a defect. Emphasizes reproduction, root cause analysis, minimal fix, and regression testing. - 100resolve-bug
Orchestrates the full bugfix pipeline for a BUG-XXX or GitHub issue: an isolated tester reproduces the bug and updates the issue, a senior-dev agent writes a root-cause fix plan while a business-analyst agent links the affected requirement(s) in parallel, then the fix is… - 100resolve-bug
Orchestrates the full bugfix pipeline for a BUG-XXX or GitHub issue: an isolated tester reproduces the bug and updates the issue, a senior-dev agent writes a root-cause fix plan while a business-analyst agent links the affected requirement(s) in parallel, then the fix is… - 100bugfix
Use when a bug is reported, something is broken, an error or crash needs fixing, a wrong output appears, or a regression shows up — guides Grimoire's Reproduce → Root-Cause → failing-test-FIRST → Fix → Verify discipline and will not let the fix begin until a failing regression… - 100bugfix
Lightweight bug-fixing loop — reproduce → root-cause → fix test-first → verify — deliberately separate from the heavyweight feature workflow so small fixes don't drag a spec-and-plan process behind them. Demands a deterministic reproduction before any code changes, a stated… - 100hatch3r-bug-fix
Step-by-step bug fix workflow. Diagnose root cause, implement minimal fix, write regression test. Use when fixing bugs, working on bug report issues, or when the user mentions a bug.