Examples
Bug Fix Workflow

Bug Fix Workflow

A comprehensive workflow for finding and fixing bugs.

Overview

This workflow guides an AI assistant through:

  1. Analyzing the bug and its root cause
  2. Implementing a fix
  3. Writing tests to prevent regression
  4. Reviewing and committing changes

Complete Manifest

{
  "$schema": "https://hydra.opiusai.com/schemas/workflow/v1.0.json",
  "manifest_version": "1.0",
  "name": "Bug Fix Workflow",
  "intent": "Systematically identify, fix, and validate a reported bug with comprehensive test coverage",
  "context": {
    "language": "typescript",
    "framework": "Express",
    "test_framework": "Jest"
  },
  "steps": [
    {
      "id": "understand_bug",
      "name": "Understand the bug report",
      "action": "analyze_code",
      "agent": "bug_investigator",
      "parameters": {
        "focus": "bug symptoms, error messages, reproduction steps"
      }
    },
    {
      "id": "find_root_cause",
      "name": "Find root cause",
      "action": "analyze_code",
      "depends_on": ["understand_bug"],
      "parameters": {
        "focus": "root cause analysis, affected code paths, edge cases"
      }
    },
    {
      "id": "implement_fix",
      "name": "Implement the fix",
      "action": "edit_file",
      "depends_on": ["find_root_cause"],
      "parameters": {
        "focus": "minimal fix, no side effects, maintain backwards compatibility"
      }
    },
    {
      "id": "write_tests",
      "name": "Write regression tests",
      "action": "generate_tests",
      "depends_on": ["implement_fix"],
      "parameters": {
        "focus": "regression tests, edge cases, the specific bug scenario",
        "coverage_target": 80
      }
    },
    {
      "id": "run_tests",
      "name": "Run all tests",
      "action": "execute_command",
      "depends_on": ["write_tests"],
      "parameters": {
        "command": "npm test"
      }
    },
    {
      "id": "review_and_commit",
      "name": "Review and commit",
      "action": "review_and_commit",
      "depends_on": ["run_tests"],
      "parameters": {
        "focus": "clean diff, descriptive commit message, no debug code"
      }
    }
  ],
  "outputs": {
    "type": "code",
    "expected_files": ["src/**/*.ts", "tests/**/*.test.ts"]
  },
  "adapters": {
    "claude": {
      "mode": "sub_agent",
      "config": {
        "spawn_agents_per_step": true,
        "max_parallel_agents": 2
      }
    },
    "cursor": {
      "mode": "direct",
      "config": {
        "use_composer": true,
        "show_diff": true
      }
    }
  }
}

Step-by-Step Breakdown

Step 1: Understand the Bug

The AI first comprehends what's happening:

  • Reads the bug report/description
  • Identifies symptoms and error messages
  • Notes reproduction steps

Step 2: Find Root Cause

Deep analysis to find the actual problem:

  • Traces code execution path
  • Identifies the faulty logic
  • Documents findings

Step 3: Implement Fix

Makes the minimal necessary changes:

  • Fixes the identified issue
  • Avoids introducing new bugs
  • Maintains compatibility

Step 4: Write Tests

Creates tests to prevent regression:

  • Tests the specific bug scenario
  • Covers edge cases
  • Achieves coverage target

Step 5: Run Tests

Validates everything works:

  • Runs full test suite
  • Ensures no regressions
  • Verifies the fix works

Step 6: Review and Commit

Finalizes the change:

  • Reviews all changes
  • Creates descriptive commit
  • Prepares for PR

Usage

With Claude Code

Run the Bug Fix workflow.
Bug: Users can't log in when their email contains a plus sign.
File: src/auth/login.ts

With Cursor

@hydra Run Bug Fix workflow on @src/auth/login.ts
Issue: Email validation rejects valid plus signs

Customization

For Python Projects

{
  "context": {
    "language": "python",
    "framework": "FastAPI",
    "test_framework": "pytest"
  },
  "steps": [
    ...
    {
      "id": "run_tests",
      "action": "execute_command",
      "parameters": {
        "command": "pytest -v"
      }
    }
  ]
}

For React Projects

{
  "context": {
    "language": "typescript",
    "framework": "React",
    "test_framework": "Vitest"
  }
}

Tips

  1. Provide clear bug description - The more context, the better
  2. Specify the file if known - Helps focus the analysis
  3. Include error messages - Stack traces are valuable
  4. Mention reproduction steps - Helps verify the fix
OverviewCode Review Workflow