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)