# Bugfix

> End-to-end bugfix workflow — analyze environment (local Docker or cloud production), collect evidence, prepare bug report, plan fix, apply appropriate engineer role, implement and verify the fix.

- Skill: `avav25/bugfix-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add avav25/bugfix-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/avav25/bugfix-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: avav25 (https://skillmd.com/u/avav25)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/avav25/bugfix-2

---


# Bugfix

End-to-end workflow for investigating, diagnosing, and fixing bugs. Orchestrates environment analysis (`analyze-local` skill or `analyze-prod` skill), evidence collection, bug report preparation, fix planning, and implementation by the appropriate engineering role.

## 1. Receive Bug Report

Gather the bug description from the user:

- **What is the expected behavior?**
- **What is the actual behavior?** (error message, wrong output, crash, performance issue)
- **Steps to reproduce** (if known)
- **Environment**: local (Docker) or production (cloud K8s)?
- **When did it start?** (after deploy, config change, or unknown)
- **Severity**: P1 (outage), P2 (degraded), P3 (minor), P4 (cosmetic)

If the user provides partial information, extract what you can and fill gaps during analysis. For P1/P2 — skip detailed intake and proceed immediately to Step 2.

## 2. Analyze Environment

Based on the environment, delegate to the appropriate analysis follow-up skill:

| Environment | follow-up skill | When to use |
|---|---|---|
| Local Docker / Docker Compose | `analyze-local` skill | Bug observed in local dev environment |
| Cloud production (GKE/AKS/EKS, managed DB) | `analyze-prod` skill | Bug observed in production or staging |
| Code-only (no infra) | Skip to Step 3 | Bug is in application logic, no environment analysis needed |

Run the follow-up skill. It will:
- Apply the appropriate diagnostic role (`sre-engineer` role or `devops-engineer` role)
- Collect environment snapshot (container/pod status, logs, metrics, networking)
- Identify infrastructure-level issues
- Present diagnosis

**If the follow-up skill resolves the issue** (e.g., container restart, config fix) — skip to Step 8.

**If the root cause is in application code** — continue to Step 3 with the collected evidence.

## 3. Detect Stack and Apply Engineer Role

Determine the affected service's tech stack and apply the appropriate engineering role:

1. **Read project's `AGENTS.md`** — tech stack declaration
2. **Scan project files** — `package.json`, `pom.xml`, `requirements.txt`, `go.mod`, etc.
3. **Check evidence from Step 2** — which service's logs show the error? What language is the stack trace in?

**Role assignment:**

| Stack Signal | Role |
|---|---|
| Next.js, React, TypeScript, `.tsx` files | `frontend-engineer` role |
| Spring Boot, Java, `.java` files | `java-engineer` role |
| FastAPI, Python, `.py` files | `python-engineer` role |
| Terraform, Dockerfile, Helm, CI/CD | `devops-engineer` role |
| ML model, training pipeline, inference | `ml-engineer` role |
| Multiple stacks affected | Apply all relevant roles |
| Unknown / general | `software-engineer` role |

Announce the applied role(s) to the user.

## 4. Collect Evidence

Gather all evidence into a structured collection. Combine data from Step 2 (environment analysis) with code-level investigation:

<evidence_checklist>
- **Error output**: Full error message, stack trace, exit code
- **Logs**: Relevant log entries (timestamped) from the affected service
- **Reproduction**: Can you reproduce locally? Consistent or intermittent?
- **Scope**: Which endpoints / features / components are affected?
- **Timeline**: When did it start? What changed? (recent commits, deploys, config)
- **Data**: Specific inputs that trigger the bug (request payload, user ID, dataset)
- **Metrics** (if from prod): Error rate, latency change, affected user count
- **Related code**: Files, functions, lines most likely involved
</evidence_checklist>

Use the applied role's debugging methodology to trace the bug:
- Read error stack traces to identify the failing code path
- Search codebase for related functions, error handlers, and data flows
- Check recent changes (`git log -n 20 --oneline`) for potential regressions
- Identify the **minimal reproduction case**

## 5. Prepare Bug Report

Compile findings into a structured bug report. Present to the user for review:

```
## Bug Report

### Summary
[One sentence: what is broken]

### Severity: [P1 | P2 | P3 | P4]

### Environment
- **Type**: [local | production]
- **Service**: [name]
- **Stack**: [detected] | **Role**: [applied]

### Expected Behavior
[What should happen]

### Actual Behavior
[What actually happens — include error messages]

### Steps to Reproduce
1. [step]
2. [step]
3. [observed error]

### Evidence
- **Stack trace**: [snippet or reference]
- **Logs**: [relevant entries]
- **Metrics**: [if applicable]
- **Affected code**: [file:line references]

### Root Cause Analysis
[Technical explanation of why the bug occurs]

### Affected Components
- [file/module 1] — [how it's affected]
- [file/module 2] — [how it's affected]
```

Wait for user confirmation before proceeding to fix.

## 6. Plan the Fix

Create an ordered fix plan following the applied role's guidelines:

1. **Root cause fix** — address the actual cause, not symptoms
2. **Complete fix** — fix everything described in the bug report. Do not leave cosmetic issues, lint warnings, or minor problems unfixed. Do not create follow-up tickets for things you can fix now
3. **Regression test** — test that would have caught this bug
4. **Related fixes** — any adjacent issues discovered during investigation. Fix them in the same changeset — do not increase tech debt

Present the plan:

```
## Fix Plan

### Root Cause
[What caused the bug — one sentence]

### Changes
1. [file] — [what to change and why]
2. [file] — [what to change and why]
...

### Tests
1. [test file] — [test that reproduces and verifies the fix]
2. [test file] — [regression test for edge cases]

### Risk Assessment
- **Blast radius**: [which features could be affected by this change]
- **Rollback**: [how to revert if the fix causes issues]
```

Wait for user approval before implementing.

## 7. Implement the Fix

Execute the approved plan step by step.

**For each change:**
1. State what you are about to do (file, change summary)
2. Implement the fix following the applied role's code quality standards
3. Verify the code compiles/parses without errors

**Then write tests:**
1. **Regression test**: Reproduces the original bug — must fail without fix, pass with fix
2. **Edge case tests**: Cover related scenarios discovered during investigation
3. Run the full test suite to catch regressions

**Rules:**
- Fix the root cause, not the symptom
- Fix EVERYTHING reported in the bug — do not leave non-blocking or cosmetic issues unfixed
- Fix all lint errors, style violations, and warnings introduced or exposed by the change
- Follow existing code patterns and conventions
- No new warnings or linter errors — and fix pre-existing ones in the affected files if trivial
- Do not defer fixes to "follow-up" tasks — complete the fix in this changeset
- Do not increase tech debt — if you touch it, leave it better than you found it
- If the fix is more complex than expected — stop and discuss with the user
- If you need more information about the environment, run specialized follow-up skills (`analyze-local` skill or `analyze-prod` skill) to collect it

## 8. Self-Review the Fix

Before declaring the bug fixed, perform a thorough self-review. Do NOT skip this step.

**Code review checklist:**
- [ ] Re-read every changed file diff — verify correctness and completeness
- [ ] Every item from the bug report or user description is addressed — nothing left unfixed
- [ ] No cosmetic issues, lint warnings, or style violations remain in changed files
- [ ] No TODO, FIXME, or "will fix later" comments introduced
- [ ] No tech debt created — the code is clean and production-ready
- [ ] Run linter on all changed files — zero warnings
- [ ] Run formatter on all changed files — zero diffs

If the self-review reveals any remaining issues — fix them before proceeding. Do not declare the bug fixed with known remaining problems.

## 9. Verify the Fix

Verify the bug is resolved in the appropriate environment:

**For local bugs:**
- Run the reproduction steps — confirm the bug no longer occurs
- Run the full test suite — all tests pass (new + existing)
- If Docker-based: rebuild and verify with `analyze-local` skill (optional)
- If you need more data, run specialized follow-up skills for `analyze-local` skill to collect environment state

**For production bugs:**
- Verify the fix locally first
- Deploy through normal CI/CD pipeline (do NOT hotfix production directly)
- After deploy: re-run relevant checks from `analyze-prod` skill to confirm resolution
- Monitor error rates and SLIs for regression

**Verification checklist:**
- [ ] Original bug no longer reproduces
- [ ] ALL items from the bug report are fixed — not just the primary symptom
- [ ] Regression test passes
- [ ] Full test suite passes (no new failures)
- [ ] Linter passes with zero warnings on changed files
- [ ] No unrelated files modified
- [ ] Code follows project conventions and role guidelines
- [ ] No deferred work — everything is done in this changeset

If any check fails — fix and re-verify. Do NOT declare the bug fixed until every checkbox passes.

## 10. Summary

Present the completed bugfix:

- **Bug**: one-sentence summary
- **Severity**: P1–P4
- **Environment**: local / production
- **Role(s) applied**: which roles were used
- **Root cause**: technical explanation
- **Fix**: what was changed (files, brief description)
- **Tests added**: count and description
- **Self-review**: passed — all items verified
- **Verification**: how it was confirmed fixed
- **Remaining issues**: NONE (if any remain, go back and fix them before reporting)
- **Prevention**: recommendations to avoid similar bugs (e.g., add validation, improve error handling, add monitoring)

## Integration

- **follow-up skills**: `analyze-local` skill, `analyze-prod` skill (environment diagnostics — launch as specialized skills when more data is needed)
- **Follow-up**: `run-tests` skill (verify fix), `pre-commit` skill (quality gate), `create-pr` skill (submit fix)
- **Skills**: `code-review` skill (review fix), `test-strategy` skill (test strategy), `worktree-isolation` skill (branch isolation)