Bug Fixing Workflow - Automagik Suite Documentation

Overview

Bug fixing with Forge combines human debugging intuition with AI agent execution power. You identify and reproduce the bug, AI agents help fix it, and you verify the solution actually works.

The Bug Fixing Cycle

Step 1: Capture the Bug Report

Start with clear bug documentation.

Bug Report Template

Create a detailed task card with:

Via UI
Via CLI
Via MCP (Claude Code)

Title: "API returns 500 on malformed JSON input"

Description:
  Environment: Production API v2.3.1
  Endpoint: POST /api/users

  Steps to Reproduce:
  1. Send POST request with malformed JSON
  2. Missing closing brace in request body

  Expected: 400 Bad Request with error message
  Actual: 500 Internal Server Error

  Impact: High - crashes API server
  Frequency: ~50 requests/day

  Example Request:
  {
    "name": "John Doe",
    "email": "john@example.com"
    # Missing closing brace

Labels: bug, backend, priority:high, security

forge task create \
  --title "API returns 500 on malformed JSON input" \
  --type bug \
  --priority high \
  --labels "backend,security" \
  --description "$(cat <<EOF
Environment: Production API v2.3.1
Endpoint: POST /api/users

Steps to Reproduce:
1. Send POST request with malformed JSON
2. Missing closing brace crashes server

Expected: 400 Bad Request
Actual: 500 Internal Server Error

Impact: High - crashes API server
EOF
)"

"I found a bug in production. Create a bug task:

Title: API returns 500 on malformed JSON input
Type: bug
Priority: high
Labels: backend, security

The POST /api/users endpoint crashes with 500 when receiving malformed JSON.
It should return 400 Bad Request instead.

This happens about 50 times per day and crashes the API server.
High priority security issue."

Step 2: Reproduce the Bug

Before fixing, ensure you can reliably reproduce it.

Create Reproduction Task

# Create a task specifically for reproduction
forge task create \
  --title "Reproduce: API 500 on malformed JSON" \
  --description "Write failing test that demonstrates the bug" \
  --labels "bug,reproduction" \
  --agent claude-code

Why Reproduction Matters

Benefits of Reproduction

✅ Confirms the bug exists ✅ Provides regression test ✅ Documents exact conditions ✅ Verifies fix actually works

Example Reproduction Test

The AI agent might create:

// test/api/users.test.ts
describe('POST /api/users - Error Handling', () => {
  it('should return 400 for malformed JSON', async () => {
    const malformedJson = '{"name":"John","email":"john@example.com"'; // Missing }

    const response = await request(app)
      .post('/api/users')
      .set('Content-Type', 'application/json')
      .send(malformedJson);

    expect(response.status).toBe(400); // Currently fails with 500
    expect(response.body).toHaveProperty('error');
    expect(response.body.error).toContain('Invalid JSON');
  });
});

Step 3: Diagnose Root Cause

Use AI agents to help analyze the problem.

Diagnostic Approaches

Code Analysis
Log Analysis
Stack Trace Analysis

# Let agent analyze the codebase
forge task create \
  --title "Analyze root cause: API 500 error" \
  --description "Review error handling middleware and JSON parsing logic" \
  --agent claude-code \
  --labels "analysis,bug"

Agent might find:

// Missing error handling in middleware
app.use(express.json()); // ❌ No error handler

# Provide logs to agent for analysis
forge task create \
  --title "Analyze error logs for JSON parsing bug" \
  --description "Review last 100 error logs from production" \
  --agent gemini \
  --attach-file logs/error-2024-10-31.log

# Analyze stack trace
forge task create \
  --title "Trace error: SyntaxError in JSON.parse" \
  --description "Follow stack trace to find unhandled exception" \
  --agent claude-code

Step 4: Create Fix Tasks

Break down the fix into focused tasks.

Example: JSON Parsing Bug Fix

# Task 1: Add error handling middleware
forge task create \
  --title "Add JSON parsing error handler" \
  --description "Catch SyntaxError from express.json() and return 400" \
  --agent claude-code \
  --labels "bug,fix"

# Task 2: Add validation
forge task create \
  --title "Add request validation middleware" \
  --description "Validate request body structure before processing" \
  --agent cursor-cli \
  --labels "bug,validation"

# Task 3: Improve error messages
forge task create \
  --title "Add detailed error messages for malformed JSON" \
  --description "Return helpful error messages indicating what's wrong" \
  --agent gemini \
  --labels "bug,ux"

Step 5: Try Multiple Approaches

Use Forge’s multi-attempt feature to explore different solutions.

Approach Comparison

Attempt 1: Middleware Approach (Claude)

// Add error handling middleware
app.use((err, req, res, next) => {
  if (err instanceof SyntaxError && err.status === 400 && 'body' in err) {
    return res.status(400).json({
      error: 'Invalid JSON',
      message: err.message
    });
  }
  next();
});

Pros: Standard Express pattern Cons: Only handles middleware errors

Attempt 2: Custom Parser (Gemini)

// Replace express.json() with custom parser
app.use((req, res, next) => {
  try {
    req.body = JSON.parse(req.body);
    next();
  } catch (err) {
    return res.status(400).json({
      error: 'Malformed JSON',
      details: err.message
    });
  }
});

Pros: Full control over parsing Cons: Reinventing the wheel

Attempt 3: Wrapper with Validation (Cursor)

// Use express-json-validator-middleware
import { Validator } from 'express-json-validator-middleware';

const validator = new Validator({});

app.use(express.json({
  verify: (req, res, buf) => {
    try {
      JSON.parse(buf);
    } catch (err) {
      throw new SyntaxError('Invalid JSON format');
    }
  }
}));

Pros: Validates before parsing Cons: Additional dependency

Compare Attempts

# Run all three approaches
forge task start task-1 --agent claude-code
forge task fork task-1 --agent gemini
forge task fork task-1 --agent cursor-cli

# Compare results
forge task compare task-1

# Test each approach
forge task test task-1-attempt-1
forge task test task-1-attempt-2
forge task test task-1-attempt-3

Decision Matrix:

Criterion	Claude (Middleware)	Gemini (Custom)	Cursor (Validation)
Code Quality	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐
Performance	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Maintainability	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐
Security	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐
Winner	✅ Best overall	❌	⚠️ Good alternative

Step 6: Verify the Fix

Never trust a fix without verification.

Verification Checklist

1. Reproduction Test Passes

# Run the original failing test
forge task test task-reproduction

# Should now pass ✅

2. Edge Cases Covered

# Create additional test task
forge task create \
  --title "Test edge cases for JSON parsing fix" \
  --description "Test various malformed JSON scenarios" \
  --agent claude-code

Tests should cover:

Missing closing bracket
Extra commas
Invalid escape sequences
Empty request body
Non-JSON content type

3. No Regressions

# Run full test suite
forge task create \
  --title "Run full test suite" \
  --agent cursor-cli

Ensure the fix didn’t break existing functionality.

4. Performance Impact

# Benchmark before and after
forge task create \
  --title "Benchmark JSON parsing performance" \
  --description "Compare performance before and after fix" \
  --agent gemini

Step 7: Add Regression Test

Prevent the bug from coming back.

# Create comprehensive test task
forge task create \
  --title "Add regression test suite for JSON parsing" \
  --description "Cover all malformed JSON scenarios found in production" \
  --agent claude-code \
  --labels "testing,regression"

Example Regression Test Suite

describe('JSON Parsing - Regression Tests', () => {
  test.each([
    ['missing closing brace', '{"name":"John"'],
    ['extra comma', '{"name":"John",}'],
    ['invalid escape', '{"name":"John\\x"}'],
    ['trailing text', '{"name":"John"}extra'],
    ['leading text', 'extra{"name":"John"}'],
  ])('should return 400 for: %s', async (scenario, malformed) => {
    const response = await request(app)
      .post('/api/users')
      .send(malformed);

    expect(response.status).toBe(400);
    expect(response.body.error).toBeDefined();
  });
});

Step 8: Document the Fix

Update documentation to help prevent similar bugs.

Code Comments
CHANGELOG
API Documentation

// ⚠️ IMPORTANT: JSON parsing error handler
// This middleware catches SyntaxError from malformed JSON
// and returns 400 instead of crashing with 500.
// See: https://github.com/yourorg/repo/issues/123
app.use((err, req, res, next) => {
  if (err instanceof SyntaxError && 'body' in err) {
    return res.status(400).json({
      error: 'Invalid JSON',
      message: 'Request body contains malformed JSON'
    });
  }
  next();
});

## [2.3.2] - 2024-10-31

### Fixed
- API now returns 400 Bad Request instead of 500 when receiving malformed JSON
- Added comprehensive error messages for JSON parsing errors
- Added regression test suite for JSON validation

### Security
- Fixed crash vulnerability when processing malformed JSON input

Error Response Documentation:

400 Bad Request - Invalid JSON

Returned when request body contains malformed JSON.Example Response:

{
  "error": "Invalid JSON",
  "message": "Unexpected token } in JSON at position 42"
}

Common Causes:

Missing closing braces or brackets
Trailing commas
Invalid escape sequences

Real-World Example: Memory Leak Bug

Here’s a complete bug fix workflow for a production memory leak:

Day 1 - Investigation

# Create investigation tasks
forge task create --title "Analyze memory usage patterns" --agent claude-code
forge task create --title "Review event listener registrations" --agent gemini
forge task create --title "Check for unclosed connections" --agent cursor-cli

# Run parallel analysis
forge task start-batch task-1 task-2 task-3

# Finding: WebSocket connections not cleaned up on disconnect

Day 2 - Fix Attempts

# Try different fix approaches
forge task create --title "Add connection cleanup on disconnect" --agent claude-code
forge task fork task-4 --agent gemini  # Alternative approach

# Compare solutions
forge task compare task-4

# Claude's approach wins - more comprehensive

Day 3 - Verification & Ship

# Add monitoring and tests
forge task create --title "Add memory leak regression tests" --agent claude-code
forge task create --title "Add connection pool monitoring" --agent gemini

# Verify fix in staging
forge task create --title "Load test in staging environment" --agent cursor-cli

# All passed - merge and deploy
forge task merge-all-approved

Bug Severity & Agent Strategy

Choose your approach based on bug severity:

Critical (P0)
High (P1)
Medium (P2)
Low (P3)

Characteristics: Production down, data loss, security breachStrategy:

# Use fastest, most reliable agent
forge task create --title "URGENT: Fix auth bypass" --agent claude-code

# No time for multiple attempts - go with proven agent
# Document and refactor later if needed

Characteristics: Feature broken, bad UX, performance issueStrategy:

# Try 2-3 approaches, choose best
forge task create --title "Fix slow API response" --agent claude-code
forge task fork task-1 --agent gemini

# Compare and pick winner
forge task compare task-1

Characteristics: Minor issue, edge case, cosmeticStrategy:

# Experiment with different agents
forge task create --title "Fix button alignment" --agent cursor-cli
forge task fork task-1 --agent gemini
forge task fork task-1 --agent claude-code

# Good opportunity to learn which agent handles CSS best

Characteristics: Nice-to-have, typos, cleanupStrategy:

# Use fastest agent, batch with other low-priority tasks
forge task create --title "Fix typo in error message" --agent gemini --batch-id cleanup-sprint

Pro Tips for Bug Fixing

Always Reproduce First

Never start fixing until you have a failing test:

# ✅ Correct order
Write failing test
Run test (confirms it fails)
Fix the bug
Run test (confirms it passes)

# ❌ Wrong order
Make changes hoping to fix bug
Deploy and pray

Use Git Bisect for Regression Bugs

# Create bisect task
forge task create \
  --title "Bisect: Find commit that introduced bug" \
  --description "Use git bisect to find regression commit" \
  --agent claude-code

Label Bugs Clearly

Good labels help with prioritization and analytics:

--labels "bug,security,database,priority:high,customer-reported"

Link to Issues and PRs

forge task create \
  --title "Fix #123: API timeout" \
  --github-issue 123 \
  --related-pr 456

Common Bug Patterns

Null/Undefined Errors

Best Agent: Claude Code (thorough type checking)

forge task create \
  --title "Add null checks to user profile" \
  --agent claude-code

Race Conditions

Best Agent: Claude Code (complex async logic)

forge task create \
  --title "Fix race condition in payment processing" \
  --agent claude-code

Memory Leaks

Best Agent: Claude Code or Cursor CLI

forge task create \
  --title "Fix memory leak in event listeners" \
  --agent claude-code

Performance Issues

Best Agent: Try multiple, compare benchmarks

forge task create \
  --title "Optimize slow database query" \
  --agent claude-code

forge task fork task-1 --agent gemini

Next Steps

Feature Development

Build new features with confidence

Refactoring Workflow

Safe code improvements with AI

Code Review

Multi-agent PR review process

Testing Guide

Comprehensive testing strategies

Remember: Bugs are opportunities to improve. With Forge, you can experiment with multiple fix approaches in isolation, choose the best solution, and ensure it never happens again.

Getting Started

Learn

Configuration

Reference

Troubleshooting

Documentation Index

​Overview

​The Bug Fixing Cycle

​Step 1: Capture the Bug Report

​Bug Report Template

​Step 2: Reproduce the Bug

​Create Reproduction Task

​Why Reproduction Matters

Benefits of Reproduction

​Example Reproduction Test

​Step 3: Diagnose Root Cause

​Diagnostic Approaches

​Step 4: Create Fix Tasks

​Example: JSON Parsing Bug Fix

​Step 5: Try Multiple Approaches

​Approach Comparison

​Compare Attempts

​Step 6: Verify the Fix

​Verification Checklist

​Step 7: Add Regression Test

​Example Regression Test Suite

​Step 8: Document the Fix

​400 Bad Request - Invalid JSON

​Real-World Example: Memory Leak Bug

​Bug Severity & Agent Strategy

​Pro Tips for Bug Fixing

​Common Bug Patterns