home / skills / nickcrew / claude-cortex / workflow-bug-fix

workflow-bug-fix skill

safe

This skill guides you through a structured bug-fix workflow, from root cause analysis to deployment, ensuring safe, verifiable improvements.

npx playbooks add skill nickcrew/claude-cortex --skill workflow-bug-fix

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.8 KB

---
name: workflow-bug-fix
description: Systematic approach to identifying, fixing, and validating bug fixes. Use when fixing bugs, resolving issues, or addressing errors.
---

# Bug Fix Workflow

Systematic process for fixing bugs properly.

## Phase 1: Root Cause Analysis
**Agents:** `root-cause-analyst`

Methods:
- Error trace analysis
- Log investigation
- State inspection
- Reproduce the bug consistently

**Output:** Root cause, affected components, impact assessment

## Phase 2: Fix Implementation

Constraints:
- Minimal scope (fix the bug, nothing more)
- Backward compatible
- Well tested

## Phase 3: Code Review
**Agents:** `code-reviewer`

Focus:
- Fix correctness
- Side effects
- Edge cases

## Phase 4: Regression Testing
**Agents:** `test-automator`

Create tests:
- Regression test (prevents this bug from returning)
- Edge case tests
- Integration tests if affected

## Phase 5: Security Check
**Agents:** `security-auditor`

**Blocking:** Ensure fix doesn't introduce vulnerabilities

## Phase 6: Validation
**Agents:** `quality-engineer`

Checklist:
- [ ] Original issue resolved
- [ ] No new issues introduced
- [ ] All tests pass

## Phase 7: Documentation
**Agents:** `technical-writer`

- Changelog entry
- Incident report (for significant bugs)
- Prevention guide (what caused it, how to avoid)

## Phase 8: Deployment
**Agents:** `deployment-engineer`

Strategy: Hotfix if critical, normal release otherwise

Monitor for 24h:
- Error rate
- Performance metrics
- User reports

## Success Criteria
- [ ] Bug verified fixed
- [ ] Regression tests added
- [ ] No side effects
- [ ] Documentation updated

## Anti-patterns
- ❌ Fixing symptoms instead of root cause
- ❌ Large scope changes mixed with bug fix
- ❌ Skipping regression tests
- ❌ No documentation of what caused it

Overview

This skill provides a systematic, repeatable workflow for identifying, fixing, and validating software bugs. It guides engineers through root cause analysis, targeted implementation, testing, security checks, documentation, and monitored deployment to ensure reliable fixes. The goal is fast remediation with minimal risk and clear traceability.

How this skill works

The skill inspects error traces, logs, and application state to reproduce and isolate the root cause. It prescribes a minimal, backward-compatible code change, followed by focused code review, automated regression and integration tests, a security audit, and a validation checklist. Finally, it documents the change and monitors production after deployment.

When to use it

Fixing a reproducible bug in production or staging
Responding to an incident that requires a targeted patch
Preparing regression-proof fixes during sprint work
When you must minimize risk while delivering a hotfix
Onboarding teams to a standardized bug resolution process

Best practices

Always reproduce the bug and collect traces before changing code
Limit the fix scope to the root cause; avoid unrelated refactors
Add regression and edge-case tests that capture the failure mode
Run a security audit for fixes touching auth, input handling, or data flow
Document the fix, root cause, and prevention steps in changelog or incident report
Monitor key metrics (error rate, latency, user reports) for 24 hours post-deploy

Example use cases

A critical crash in the API needs a hotfix with regression tests to prevent recurrence
A flaky background job fails under specific state conditions—use state inspection and edge-case tests
A performance regression introduced by a patch—use targeted rollback and monitoring during deployment
Fixing a validation bug that could expose data—include a security check and documentation

FAQ

What if the bug cannot be reproduced reliably?

Capture more runtime data: increase logging, add diagnostic flags, and create a minimized repro script or test harness to isolate conditions.

When is a hotfix appropriate versus batching the fix into the next release?

Use hotfixes for severity-high incidents affecting availability or data integrity. For lower-severity bugs, prefer the normal release cadence to reduce risk.